Installation

This article covers manual installation of X2CRM on a webserver. If this is your first time working with a web server, it is recommended that you first try installing via an automatic full-stack installer that will set up a self-contained web server environment for you. See Bitnami's X2CRM stack installers for download links.

Before Installation

Before installing X2CRM, you should first ensure that

• You have a web server
• You understand the basics of installing a PHP web application
• Your hosting environment is properly configured and meets all the minimum requirements

Required Knowledge

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 web 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.

System Requirements

You can quickly determine if your web server can run X2CRM by downloading the requirements checking script (link: requirements.php), uploading it to your web server, and opening it in a web browser. When finished using the script, delete it; it displays detailed information about the server's PHP configuration. Displaying it publicly for indefinite time can pose a security risk; it could be useful to attackers. In general, the following are the absolute minimum requirements for installation:

• A web server that can execute PHP.
• 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
• PHP must be run as the same system user that owns the directory where X2CRM will be installed.

If Requirements Are Not Met

Directory Ownership

This is typically caused by a hosting environment malconfiguration wherein, regardless of the method for uploading files to the server, their ownership always differs from that of PHP processes. To correct this issue in CPanel: see Apache PHP Request Handling; change the settings so that suPHP, FCGI or CGI is used for running PHP scripts. In all other cases, or if the option to change the PHP execution mode is not available, contact the system administrator or customer service department of the hosting provider.

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 re-visiting the requirements checker script and verifying that the PHP version in use is 5.3 or later.

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.

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; in most cases, the package manager will automatically configure and reload the HTTP server to enable them.

On Ubuntu & Debian: the extension mbstring will typically be included in the Apache module package.

sudo apt-get install php5-mysql php5-curl

On CentOS (6+), the mbstring extension must be installed separately with other missing modules:

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

Installing Without All 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:

Deficiency	Severity	Problems/Notes
cURL extension missing	Minor	Time zone widget will not work Contact views may be inaccessible Cannot use local scripts that make API calls Cannot use built-in error reporter
allow_url_fopen set to "No"/0 in PHP configuration	Major	Cannot receive software updates using the built-in update utility, and cannot receive notifications of new software versions from within the app.
Directory ownership mismatch	Major	Application cannot be updated and cannot run unless the permissions on all files and directories are set to allow any system user to read/write (not recommended). The application uses file-based caching and also creates files and folders during software updates, both of which require write access to the filesystem.
PHP version earlier than 5.3	Fatal	Fatal errors include but not limited to: "filename cannot be empty" due to the unavailability of magic constant __DIR__ Undefined function "lcfirst"
mbstring extension missing	Fatal	Application crashes upon login with "invalid unicode sequence" error.
pdo_mysql extension missing	Fatal	Application cannot run; no database connection is possible. It is a requirement of Yii Framework.
Any other PHP extensions listed as required but missing	Fatal	Application cannot run (requirements of Yii)
Outdated PCRE library version	Fatal	Application cannot run. Regex used in URL rules requires the "?J" group type, which was added to PCRE in version 7.4 (September 21, 2007)

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.10 and later
• MySQL 5.5
• Apache 2.2 with mod_rewrite enabled.
• Ubuntu 12.04 LTS, CentOS 6.3, or Amazon Linux

If only Windows is available, the environment provided by WampServer is recommended, especially for development.

Installing

Using The Installation Page

Browser-based 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 first test the database connection without losing the installation form by using the "Test Connection" button. Doing this before clicking the install button is highly recommended.

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 contacts and email-type action records by capturing emails from external email software, i.e. Outlook and GMail. The methods for using it are as follows:

Method 1

CC

When sending an email to a contact, include the email alias in the CC field

Method 2

Forward

After receiving an email from a contact, forward it to the email alias.

Setting it up requires a Linux/Unix server environment, a Mail Transfer Agent or MTA[[wikipedia:Message transfer agent]]: an email relay service, i.e. Postfix, QMail or Exim4. (i.e. Postfix/Exim4) service running on the server, and some knowledge about how to set up email aliases. Getting it configured properly requires the following steps:

1. Using CPanel, Webmin, or any other web host administrative tool, create a mail alias on the server, i.e. "archive@yourdomain.com". (Note: you can also do this manually by editing the mail server's configuration files, although doing that is beyond the scope of this guide.)
2. Find the absolute path on the web server's filesystem to X2CRM, if you're not sure where it is already:
   1. Paste the following into a PHP file called "path.php", in the same directory as X2CRM:

      <?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. Create an email alias. Set its destination a pipe to a program: php /path/to/x2crm/email.php (versions up to 2.5.2) or php /path/to/x2crm/protected/yiic emaildropbox (versions 2.5.7 and later)
4. (X2CRM versions 2.5.7 and later) Change the permissions on the protected/runtime folder in X2CRM to 777 (all users can read/write).
5. Test the alias by sending a message to a fictitious name/email address (i.e. "Sue Doenimm" <test@example.com>) and CC-ing the mail alias.
6. Check in the Contacts module after sending the email, and if the fictitious contact was created, check to see that the email was attached properly to the contact record. If the contact was not created or the email was not imported:
   • Check that "Create Contacts" is enabled in the email dropbox settings.
   • Check the logs of the MTA[[wikipedia:Message transfer agent]]: an email relay service, i.e. Postfix, QMail or Exim4. for any errors.
7. 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 in the next release. A self-service page in the Administrative console that will allow users to build patterns for recognizing their own email software is also currently in progress and scheduled for a future release.

References