© 2015 X2Engine Inc.

Difference between revisions of "Installation"

From X2Engine
Jump to: navigation, search
(→‎System Requirements)
(→‎System Requirements)
 
(110 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
[[Category:Support]]
 
[[Category:Support]]
 +
This article covers manual installation of X2Engine 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 [http://bitnami.org/stack/X2CRM Bitnami's X2Engine stack installers] for download links.
  
−
= System Requirements =
+
= Before Installation =
−
Before installing X2EngineCRM, you should first ascertain whether your hosting environment is properly configured. The following are the '''minimum''' requirements for X2EngineCRM to function properly:
+
Before installing X2Engine, 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
  
−
* The [http://httpd.apache.org/ Apache 2] web server, with [http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html mod_rewrite] enabled.
+
== Required Knowledge ==
 +
Installing X2Engine requires you are able to perform the following taks (and have basic knowledge of how to perform them):
 +
# Upload files to a web server via a hosting file manager, FTP/SFTP, or otherwise
 +
# Creating a MySQL database and a database user, if they aren't available already
 +
# 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 [http://x2community.com The X2Engine Forums].
 +
 
 +
== System Requirements ==
 +
You can quickly determine if your web server can run X2Engine by downloading the requirements checking script (link: [[requirements:|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).
 
* 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 version 5.3-5.6 (PHP 7 support will be introduced in X2CRM 5.4.4)'''
 +
* PHP must be run as the same system user that owns the directory where X2Engine will be installed.
  
−
Additionally, the following PHP extensions are required:
+
== If Requirements Are Not Met ==
−
* [http://php.net/manual/class.reflectionclass.php reflection class]
+
=== Directory Ownership ===
−
* [http://www.php.net/manual/book.pcre.php PCRE]
+
If you are running a dedicated web server and/or have administrative access, please refer to [[Preparing_a_Linux_Server_Environment#Server_Preparation|Preparing a Webserver]].
−
* [http://www.php.net/manual/book.spl.php SPL]
 
−
* [http://php.net/manual/book.curl.php cURL]
 
−
* [http://www.php.net/manual/ref.pdo-mysql.php PDO (MySQL)]
 
−
* [http://www.php.net/manual/book.ctype.php CType]
 
−
* [http://www.php.net/manual/book.mbstring.php multibyte string]
 
−
If any requirements are missing, the installation page should display a list of them.
 
  
−
= If Requirements Are Not Met =
+
This is a hosting environment misconfiguration wherein files uploaded to the server are owned by a different system user than the user as whom PHP executes. It is an ease-of-use issue that many shared hosting providers still haven't gotten right. It can in most cases be resolved by changing the PHP gateway interface, i.e. from SuPHP to FCGI, using your hosting control panel ('''To correct this issue in CPanel''': see [http://docs.cpanel.net/twiki/bin/vief/EasyApache3/ApachePHPRequestHandling Apache PHP Request Handling]).
−
== Getting The Right PHP Version ==
+
 
 +
You should also use a method of uploading files to the server that results in them having the same ownership as the "domain owner" (this terminology is used by most shared hosting providers). FTP services have been known to fail in this regard, whereas web-based file managers available in hosting control panels are often much more consistent. Uploading files with proper ownership will completely circumvent file permission and ownership issues.
 +
 
 +
In any case, refer to your hosting provider's documentation. If the option to change the PHP execution mode does not appear to be available, contact the system administrator or customer service department of the hosting provider. If they don't give you a satisfactory answer, consider switching to a better web host. <ref>In a discussion on our forums, [http://x2community.com/topic/703-hosting-that-works/ "Hosting that works"], some users propose or advocate web hosts that they have had experiences with. A general consensus on GoDaddy (and our own professional opinion, based on repeated bad experiences) is that it is a very poor choice for hosting X2Engine.</ref>
 +
 
 +
=== PHP Version ===
 
In some cases, it may be possible to enable PHP 5.3+ using an [http://httpd.apache.org/docs/2.2/howto/htaccess.html Apache override]; see  
 
In some cases, it may be possible to enable PHP 5.3+ using an [http://httpd.apache.org/docs/2.2/howto/htaccess.html Apache override]; see  
 
* [http://www.velvetblues.com/web-development-blog/activate-php-5-3-hostgator-godaddy/ Velvet Blues: How to Activate PHP 5.3 on HostGator and GoDaddy]
 
* [http://www.velvetblues.com/web-development-blog/activate-php-5-3-hostgator-godaddy/ Velvet Blues: How to Activate PHP 5.3 on HostGator and GoDaddy]
 
* [http://kb.siteground.com/article/How_to_have_different_Php__MySQL_versions.html SiteGround knowledge base: How to switch to a different PHP version]
 
* [http://kb.siteground.com/article/How_to_have_different_Php__MySQL_versions.html SiteGround knowledge base: How to switch to a different PHP version]
−
By adding the appropriate directives to the <tt>.htaccess</tt> file in the web root of X2EngineCRM (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 <tt>phpinfo.php</tt> containing
+
By adding the appropriate directives to the <tt>.htaccess</tt> file in the web root of X2Engine (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.
−
<syntaxhighlight lang="php"><?php phpinfo(); ?></syntaxhighlight>
 
−
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.
 
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 ==
+
=== 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.
 
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 [[wikipedia:Package management system|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.
+
In most distributions of Linux, PHP extensions can be easily installed by the distribution's default [[wikipedia:Package management system|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.
  
−
=== Ubuntu &amp; Debian ===
+
On Ubuntu &amp; Debian: the extension <tt>mbstring</tt> will typically be included in the Apache module package.
 
<pre>sudo apt-get install php5-mysql php5-curl</pre>
 
<pre>sudo apt-get install php5-mysql php5-curl</pre>
−
The extension <tt>mbstring</tt> will typically be included in the Apache module package.
 
  
−
=== CentOS, RHEL &amp; Oracle Linux ===
+
 
 +
On CentOS (6+), the mbstring extension must be installed separately with other missing modules:
 
<pre>sudo yum install php-pdo php-mbstring php-common curl</pre>
 
<pre>sudo yum install php-pdo php-mbstring php-common curl</pre>
  
−
== Without Requirements: What Won't Work ==
+
== Installing Without All Requirements: What Won't Work ==
 +
'''This section is obsolete as of 3/26/2013.''' The severity of each missing requirement, in addition to explanation of what functionality will be unavailable/broken for each missing requirement, has been written directly into the requirements check script and should be displayed there. Thus, it is no longer necessary to list them here, although the list as it was last maintained is left here for archival/demonstrative purposes.
 +
 
 
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:
 
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:
+
{|class="wikitable" align="left"
−
** Time zone widget will not work, and may make contact views inaccessible <ref>[http://x2community.com/index.php?/topic/386-cant-open-contact-view/ X2Community Forums: "Can't open contact View"]</ref>
+
|-
−
** Cannot use local scripts that make API calls
+
! scope="col" | Deficiency
−
* PHP version earlier than 5.3 ('''not''' recommended; has not been tested on versions earlier than 5.3)
+
! scope="col" | Severity
−
** Chat widget will not work
+
! scope="col" | Problems/Notes
−
** Installation form does not fully render (X2EngineCRM versions 1.6.5 - 1.6.6)
+
|-
−
** Numerous controllers, models and components that use the function [http://www.php.net/manual/en/function.lcfirst.php lcfirst]
+
! scope="row" | IMAP extension missing
−
* mbstring extension missing
+
|
−
** Application crashes upon login
+
<span style="background-color:yellow">Minor</span>
−
* pdo_mysql extension missing
+
|
−
** Application cannot run (required by Yii)
+
The email manager depends on the IMAP extension.
−
* All other PHP extensions:
+
|-
−
** Application cannot run (required by Yii)
+
! scope="row" | Zip extension missing
 +
|
 +
<span style="background-color:yellow">Minor</span>
 +
|
 +
Cannot import or export custom modules.
 +
|-
 +
! scope="row" | cURL extension missing
 +
|
 +
<span style="background-color:yellow">Minor</span>
 +
|
 +
* Google integration will not work
 +
* Time zone widget will not work
 +
* Contact views may be inaccessible <ref>[http://x2community.com/index.php?/topic/386-cant-open-contact-view/ X2Community Forums: "Can't open contact View"]</ref>
 +
* Cannot use local scripts that make API calls
 +
* Cannot use built-in error reporter
 +
|-
 +
! scope="row" | allow_url_fopen set to "No"/0 in PHP configuration
 +
|
 +
<span style="background-color:orange">Major</span>
 +
|
 +
Cannot receive software updates using the built-in update utility, and cannot receive notifications of new software versions from within the app.
 +
|-
 +
! scope="row" | Directory ownership mismatch
 +
|
 +
<span style="background-color:orange">Major</span>
 +
|
 +
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 <strong>(not recommended)</strong>. The application uses file-based caching and also creates files and folders during software updates, both of which require write access to the filesystem.
 +
|-
 +
! scope="row" | json extension missing
 +
|
 +
<span style="background-color:orange">Major</span>
 +
|
 +
Numerous components and features will not work; the json_encode function is used throughout the application
 +
|-
 +
! scope="row" | PHP version earlier than 5.3
 +
|
 +
<span style="background-color:red; color:white; font-weight:bold;">Fatal</span>
 +
|Numerous fatal errors, including errors that inhibit installation
 +
|-
 +
! scope="row" | mbstring extension missing
 +
|
 +
<span style="background-color:red; color:white; font-weight:bold;">Fatal</span>
 +
|
 +
Application crashes upon login with "invalid unicode sequence" error.
 +
|-
 +
! scope="row" | pdo_mysql extension missing
 +
|
 +
<span style="background-color:red; color:white; font-weight:bold;">Fatal</span>
 +
|
 +
Application cannot run; no database connection is possible. It is a requirement of [http://www.yiiframework.com/ Yii Framework].
 +
|-
 +
! scope="row" | Any other PHP extensions listed as required but missing
 +
|
 +
<span style="background-color:red; color:white; font-weight:bold;">Fatal</span>
 +
|
 +
Application cannot run (requirements of Yii)
 +
|-
 +
! scope="row" | Outdated PCRE library version
 +
|
 +
<span style="background-color:red; color:white; font-weight:bold;">Fatal</span>
 +
|
 +
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)<ref>[http://www.pcre.org/changelog.txt PCRE Changelog]</ref>
 +
|}
  
 
== Recommended System ==
 
== 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 X2EngineCRM is most commonly developed and tested, and thus would be the most likely to never cause problems:
+
The following attributes of the hosting environment are by no means required. However, they are the same as the primary servers on which X2Engine is most commonly developed and tested, and thus would be the most likely to never cause problems:
−
* PHP 5.3.2
+
* PHP 5.3.10 and later
 
* MySQL 5.5
 
* MySQL 5.5
−
* Apache 2.2
+
* Apache 2.2 with [http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html mod_rewrite] enabled.
−
* Ubuntu 12.04
+
* Ubuntu 12.04 LTS, CentOS 6.3, or Amazon Linux
 +
 
 +
If only Windows is available, the environment provided by [http://www.wampserver.com/ WampServer] is recommended, especially for development.
  
 
= Installing =
 
= Installing =
−
== Minimum Knowledge Requirements ==
+
== Using The Installation Page ==
−
Installing X2EngineCRM requires you are able to perform the following taks (and have basic knowledge of how to perform them):
+
Browser-based installation generally proceeds as follows:
−
# Upload files to a server via FTP/SFTP or otherwise, using a server-based file manager
 
−
# Creating a MySQL database and a database user, if they aren't available already
 
−
# 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 [http://x2community.com The X2Engine Forums].
 
−
 
 
−
== Installing Using The Installation Page ==
 
−
Installation generally proceeds as follows:
 
 
# Make sure a MySQL database and a database user with full permissions to that database are available from the web server.
 
# Make sure a MySQL database and a database user with full permissions to that database are available from the web server.
 
# Upload the contents of the <tt>x2engine</tt> folder to the document root of the web server, or a subdirectory if desired.
 
# Upload the contents of the <tt>x2engine</tt> folder to the document root of the web server, or a subdirectory if desired.
 
# Navigate to the webroot (or subdirectory) where the contents of the folder were uploaded.
 
# Navigate to the webroot (or subdirectory) where the contents of the folder were uploaded.
−
# Fill out the installation form. Note the following:
+
# 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.
 
#* 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.
+
#* 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 ==  
+
== Using The Command Line Installer ==  
−
It is possible to install X2EngineCRM from the command line via SSH or otherwise. This is performed as follows:
+
It is possible to install X2Engine from the command line via SSH or otherwise. This is performed as follows:
−
# There is a script in the root of the web application named <tt>installConfig.php</tt>. Fill it with the same information that would be submitted by the installation page form, except for the variable <tt>$unique_id</tt>; leave it as is.
+
# There is a script in the root of the web application named <tt>installConfig.php</tt>. Fill it with the same information that would be submitted by the installation page form. If you are installing a commercial edition of X2Engine, fill the variable <tt>$unique_id</tt> with your product key.
 
# Change directory into the root folder of the web application.
 
# Change directory into the root folder of the web application.
 
# Run: <pre>php initialize.php silent</pre>
 
# Run: <pre>php initialize.php silent</pre>
  
−
= Notes =
+
The configuration variables in <tt>installConfig.php</tt> are as follows:
 +
;host
 +
: The (MySQL) database hostname
 +
;db
 +
: The database name
 +
;user
 +
: The database username
 +
;pass
 +
: The database password
 +
;app
 +
: The application name (i.e. "Company X CRM") that shows up in various places throughout the app.
 +
;currency
 +
: The 3-letter code for the currency to be used in quotes and opportunities. Currently supported currencies include: USD,EUR,GBP,CAD,JPY,CNY,CHF,INR, and BRL.
 +
;lang
 +
: The application's language.
 +
;timezone
 +
: The time zone. It must be a valid timezone alias; see [http://php.net/manual/en/timezones.php List of supported time zones] for more info.
 +
;adminEmail
 +
: The email address of the application's owner
 +
;adminPassword
 +
: The administrator's application password
 +
;adminUsername
 +
: The username of the administrator
 +
;dummyData
 +
: Whether to include sample data in the installation, for evaluative purposes
 +
;webLeadUrl
 +
: The base URL of the web application.
 +
;unique_id
 +
: The product key, if installing a commercial edition. In Open Source Edition, it can simply be left "none". If it is "none" in Open Source Edition, the user will need to enable software updates separately by going to "Updater Settings" in the administrative index, in the "System Settings" section.
 +
;visibleModules
 +
: Initial module visibility setting; a comma-delineated list of modules to be displayed in the menu at the top of the CRM.
 +
;test_db
 +
: Set this to 1 if constructing a unit/functional testing environment (see [[Test-Driven_Development#Preparing_a_testing_database|Test-driven Development: preparing a testing database]])
 +
;test_url
 +
: If installing a testing environment, the URL to the "index-test.php" entry script that web tests will use.
 +
;installType
 +
: Installation type to report to the updates server. This is a setting that is used for internal reporting/statistical purposes and should be left as-is.
 +
 
 +
= Miscellaneous Post-Installation Tasks =
 +
== Configuring the "Email Dropbox" ==
 +
This section has been moved to the article: "[[E-Mail Configuration]]"
 +
 
 +
= References =
 
<references />
 
<references />

Latest revision as of 20:40, 4 February 2016

This article covers manual installation of X2Engine 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 X2Engine stack installers for download links.

Before Installation

Before installing X2Engine, 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 X2Engine 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 a hosting file manager, FTP/SFTP, or otherwise
  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 X2Engine 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-5.6 (PHP 7 support will be introduced in X2CRM 5.4.4)
  • PHP must be run as the same system user that owns the directory where X2Engine will be installed.

If Requirements Are Not Met

Directory Ownership

If you are running a dedicated web server and/or have administrative access, please refer to Preparing a Webserver.

This is a hosting environment misconfiguration wherein files uploaded to the server are owned by a different system user than the user as whom PHP executes. It is an ease-of-use issue that many shared hosting providers still haven't gotten right. It can in most cases be resolved by changing the PHP gateway interface, i.e. from SuPHP to FCGI, using your hosting control panel (To correct this issue in CPanel: see Apache PHP Request Handling).

You should also use a method of uploading files to the server that results in them having the same ownership as the "domain owner" (this terminology is used by most shared hosting providers). FTP services have been known to fail in this regard, whereas web-based file managers available in hosting control panels are often much more consistent. Uploading files with proper ownership will completely circumvent file permission and ownership issues.

In any case, refer to your hosting provider's documentation. If the option to change the PHP execution mode does not appear to be available, contact the system administrator or customer service department of the hosting provider. If they don't give you a satisfactory answer, consider switching to a better web host. [1]

PHP Version

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

By adding the appropriate directives to the .htaccess file in the web root of X2Engine (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

This section is obsolete as of 3/26/2013. The severity of each missing requirement, in addition to explanation of what functionality will be unavailable/broken for each missing requirement, has been written directly into the requirements check script and should be displayed there. Thus, it is no longer necessary to list them here, although the list as it was last maintained is left here for archival/demonstrative purposes.

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
IMAP extension missing

Minor

The email manager depends on the IMAP extension.

Zip extension missing

Minor

Cannot import or export custom modules.

cURL extension missing

Minor

  • Google integration will not work
  • Time zone widget will not work
  • Contact views may be inaccessible [2]
  • 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.

json extension missing

Major

Numerous components and features will not work; the json_encode function is used throughout the application

PHP version earlier than 5.3

Fatal

Numerous fatal errors, including errors that inhibit installation
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)[3]

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 X2Engine 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 Command Line Installer

It is possible to install X2Engine 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 a commercial edition of X2Engine, 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

The configuration variables in installConfig.php are as follows:

host
The (MySQL) database hostname
db
The database name
user
The database username
pass
The database password
app
The application name (i.e. "Company X CRM") that shows up in various places throughout the app.
currency
The 3-letter code for the currency to be used in quotes and opportunities. Currently supported currencies include: USD,EUR,GBP,CAD,JPY,CNY,CHF,INR, and BRL.
lang
The application's language.
timezone
The time zone. It must be a valid timezone alias; see List of supported time zones for more info.
adminEmail
The email address of the application's owner
adminPassword
The administrator's application password
adminUsername
The username of the administrator
dummyData
Whether to include sample data in the installation, for evaluative purposes
webLeadUrl
The base URL of the web application.
unique_id
The product key, if installing a commercial edition. In Open Source Edition, it can simply be left "none". If it is "none" in Open Source Edition, the user will need to enable software updates separately by going to "Updater Settings" in the administrative index, in the "System Settings" section.
visibleModules
Initial module visibility setting; a comma-delineated list of modules to be displayed in the menu at the top of the CRM.
test_db
Set this to 1 if constructing a unit/functional testing environment (see Test-driven Development: preparing a testing database)
test_url
If installing a testing environment, the URL to the "index-test.php" entry script that web tests will use.
installType
Installation type to report to the updates server. This is a setting that is used for internal reporting/statistical purposes and should be left as-is.

Miscellaneous Post-Installation Tasks

Configuring the "Email Dropbox"

This section has been moved to the article: "E-Mail Configuration"

References

  1. ↑ In a discussion on our forums, "Hosting that works", some users propose or advocate web hosts that they have had experiences with. A general consensus on GoDaddy (and our own professional opinion, based on repeated bad experiences) is that it is a very poor choice for hosting X2Engine.
  2. ↑ X2Community Forums: "Can't open contact View"
  3. ↑ PCRE Changelog
Retrieved from "http://wiki.x2crm.com/index.php?title=Installation&oldid=1948"