Revision as of 21:31, 9 November 2012

System Requirements

Before installing X2CRM, you should first ascertain whether your hosting environment is properly configured. The following are the minimum requirements for X2CRM to function properly:

• The Apache 2 web server, with mod_rewrite enabled.
• A password-protected MySQL database server connection, and a database on which the user of the connection has all rights (i.e. select, drop, create and update).
• PHP (version 5.3 or later)

Additionally, the following PHP extensions are required:

• reflection class
• PCRE
• SPL
• cURL
• PDO (MySQL)
• CType
• multibyte string

If any requirements are missing, the installation page should display a list of which ones are missing (as of version 2.0). Alternately, you can check for the availability of most of the above modules by using the requirements checker of Yii Framework, as follows:

1. Download Yii Framework and upload the "requirements" folder to your web server.
2. Navigate to the requirements folder on your server using a web browser. You should see a page that looks similar to this:

   

3. Note that the following requirements are not necessary:
   • The SQLite and PostgreSQL extensions; X2Engine depends on MySQL, so these other extensions will not be used.
   • The DOM extension; it is not required.
   • The caching extensions (Memcache, APC cache); caching is not currently required, although APC can increase performance
   • The SOAP extension; the classes that depend on it are not used

If Requirements Are Not Met

Getting The Right PHP Version

In some cases, it may be possible to enable PHP 5.3+ using an Apache override; see

• Velvet Blues: How to Activate PHP 5.3 on HostGator and GoDaddy
• SiteGround knowledge base: How to switch to a different PHP version

By adding the appropriate directives to the .htaccess file in the web root of X2CRM (NOT replacing the file, but changing it), the PHP version can ideally be set. You can test whether this method succeeds by uploading a file into the web root called phpinfo.php containing

<?php phpinfo(); ?>

Navigate to it in your web browser, and look for the version information. Delete the file when done; displaying PHP info publicly for indefinite time can pose a security risk.

In other cases, it may be possible to enable later versions of PHP via the web hosting control interface (i.e. CPanel or Webmin). Otherwise, the only option will be to contact the hosting provider and request that version 5.3 be made available.

Enabling PHP extensions

If your server does not meet the minimum system requirements for running X2Engine, and you are a system administrator of your server, you will be able to install the necessary modules. Note, however, that as of the most recent version, the MySQL PDO extension is the only extension used by X2Engine that isn't included by default and always enabled in PHP 5.3; the reflection class and extensions SPL, PCRE and Ctype should all be available if PHP is at version 5.3 or later.

In most distributions of Linux, PHP extensions can be easily installed by the distribution's default Package management system. That is the recommended method of installing them; typically, the package manager will automatically configure and reload the HTTP server to enable them.

Ubuntu & Debian

sudo apt-get install php5-mysql php5-curl

The extension mbstring will typically be included in the Apache module package.

CentOS, RHEL & Oracle Linux

sudo yum install php-pdo php-mbstring php-common curl

Without Requirements: What Won't Work

If your server environment does not meet the minimum system requirements, and it is not possible to add PHP extensions, you can still install X2Engine, though it is not recommended. Note the following issues that can occur:

• cURL extension missing:
  • Time zone widget will not work, and may make contact views inaccessible ^[1]
  • Cannot use local scripts that make API calls
• PHP version earlier than 5.3 (not recommended; has not been tested on versions earlier than 5.3)
  • Chat widget will not work
  • Installation form does not fully render (X2CRM versions 1.6.5 - 1.6.6)
  • Numerous controllers, models and components that use the function lcfirst
• mbstring extension missing
  • Application crashes upon login
• pdo_mysql extension missing
  • Application cannot run (required by Yii)
• All other PHP extensions:
  • Application cannot run (required by Yii)

Recommended System

The following attributes of the hosting environment are by no means required. However, they are the same as the primary servers on which X2CRM is most commonly developed and tested, and thus would be the most likely to never cause problems:

• PHP 5.3.2 and later
• MySQL 5.5
• Apache 2.2
• Ubuntu 12.04

Installing

Minimum Knowledge Requirements

Installing X2CRM requires you are able to perform the following taks (and have basic knowledge of how to perform them):

1. Upload files to a server via FTP/SFTP or otherwise, using a server-based file manager
2. Creating a MySQL database and a database user, if they aren't available already
3. Using a web browser, and knowing what URL to use to access a location on the server

If you are unsure of how to perform any of these, please ask for assistance on The X2Engine Forums.

Installing Using The Installation Page

Installation generally proceeds as follows:

1. Make sure a MySQL database and a database user with full permissions to that database are available from the web server.
2. Upload the contents of the x2engine folder to the document root of the web server, or a subdirectory if desired.
3. Navigate to the webroot (or subdirectory) where the contents of the folder were uploaded.
4. Fill out the installation form. Note the following:
   • If you leave "Create Sample Data" checked, the installer will insert fictitious contact, user, account and action records into the initial installation for testing purposes. Uncheck the box if this is not desired.
   • You can test the database connection without submitting the form by using the "Test Connection" button.

Using The Silent Installer

It is possible to install X2CRM from the command line via SSH or otherwise. This is performed as follows:

1. There is a script in the root of the web application named installConfig.php. Fill it with the same information that would be submitted by the installation page form. If you are installing X2CRM Professional Edition, fill the variable $unique_id with your product key.
2. Change directory into the root folder of the web application.
3. Run:

   php initialize.php silent

Miscellaneous Post-Installation Tasks

Configuring the Email "Dropbox"

This feature, available in X2CRM Professional Edition, provides the means to automatically create contact records by forwarding emails from new leads to a mail alias on the server where X2CRM is installed. It can also do this if an email is sent to the lead and CC'd to the mail alias. However, it requires extra server configuration:

1. Using CPanel, Webmin, or any other web host administrative tool, create a mail alias on the server, i.e. "archive@yourdomain.com"
2. For the alias's action, set it to pipe to the program:

   php /path/to/email.php

   (the script email.php should exist in the same folder as the web root of the X2CRM application). To find the absolute path to the web root:
   1. Paste the following into a PHP file called "path.php":

      <?php echo realpath(dirname(__FILE__)); ?>
      

   2. Navigate to the file using a web browser
   3. Record the path, append "email.php", and use the resulting string as the path to the capture script in the mail alias.
   4. Delete the file "path.php" from the server.
3. Test the alias by sending a message to a fictitious name/email address (i.e. "Sue Doe Nimm" <test@example.com>) and CC-ing the mail alias.
4. Check in the Contacts module after sending the email. If nothing appears in the contacts database:
   • Check the web server error logs
   • Check the mail transfer agent (i.e. Postfix) logs
5. Test to see if your email software's forwarded message format is supported by forwarding an email from a contact to the mail alias.

If you receive a response email notifying of an unsupported forwarded message format, or do not see the email attached to the appropriate contact in X2CRM, forward the the email to X2Engine Customer Support, using the same email software that was used to test the feature. Due to the great diversity of email software and the inconsistency of forwarded/attached message formatting across platforms, the forwarded message capture may not immediately work with your email software of choice. However, per request, support for new forwarded message formats will be added. Once the new format has been integrated and tested in the email lead capture script, you will be sent a new version of the parser which supports your forwarded message format.

References

1. ↑ X2Community Forums: "Can't open contact View"