X2Engine - User contributions [en]

Installation

2016-02-04T20:40:26Z

Derek Mueller: /* System Requirements */

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

= 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):
# 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).
* '''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_Linux_Server_Environment#Server_Preparation|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 [http://docs.cpanel.net/twiki/bin/vief/EasyApache3/ApachePHPRequestHandling 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. <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
* [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]
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.

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

On Ubuntu & 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>

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>

== 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:

{|class="wikitable" align="left"
|-
! scope="col" | Deficiency
! scope="col" | Severity
! scope="col" | Problems/Notes
|-
! scope="row" | IMAP extension missing
|
Minor
|
The email manager depends on the IMAP extension.
|-
! scope="row" | Zip extension missing
|
Minor
|
Cannot import or export custom modules.
|-
! scope="row" | cURL extension missing
|
Minor
|
* 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
|
Major
|
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
|
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.
|-
! scope="row" | json extension missing
|
Major
|
Numerous components and features will not work; the json_encode function is used throughout the application
|-
! scope="row" | PHP version earlier than 5.3
|
Fatal
|Numerous fatal errors, including errors that inhibit installation
|-
! scope="row" | mbstring extension missing
|
Fatal
|
Application crashes upon login with "invalid unicode sequence" error.
|-
! scope="row" | pdo_mysql extension missing
|
Fatal
|
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
|
Fatal
|
Application cannot run (requirements of Yii)
|-
! scope="row" | 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)<ref>[http://www.pcre.org/changelog.txt PCRE Changelog]</ref>
|}

== 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 [http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html mod_rewrite] enabled.
* 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 =
== Using The Installation Page ==
Browser-based 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.
# 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.
# 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:
# 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.
# Run: <pre>php initialize.php silent</pre>

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 />

MediaWiki:Sitenotice

2015-09-16T02:15:45Z

Derek Mueller:

Preparing a Linux Server Environment

2015-06-23T01:49:52Z

Derek Mueller:

[[Category:Support]]

This aims to be a generic guide for manually preparing a Linux-based web server, which applies both to physical servers and virtual servers, i.e. Amazon EC2 instances. It will cover two main families of Linux distributions: RHEL (Red Hat Enterprise Linux) based and Debian-based. RHEL-based distributions include, most notably: CentOS, Oracle Linux and Amazon Linux. Debian-based distributions include the popular Ubuntu and Ubuntu derivatives, as well as Linux Mint, Knopper Linux and many others<ref>See: [http://wiki.debian.org/Derivatives/Census|the Debian Derivatives Census]</ref>.

= Introduction =

It will be assumed in this guide, unless otherwise noted:
* Command line operations are being performed as the root user
* Names enclosed in angle brackets (< >) are intended as placeholders for actual input and should not be used verbatim
* The server is ''dedicated,'' i.e. will be used mainly for X2CRM on a single domain name, and will not be set up with multiple virtual hosts.
* The Linux system's ''[http://en.wikipedia.org/wiki/Package_manager software package manager]'' has been configured properly
* Software will be installed using pre-built packages available through the particular distribution's software package repositories.
* A distribution of Linux based on Red Hat Enterprise Linux or Debian is in use.

'''When installing packages, note:''' there may be slight differences in the names of software packages between distributions of Linux. Thus, in cases where a package name copied verbatim from this guide does not exist, the package manager's ''search'' utility should be used to determine the proper package name.

The command for searching for packages by name is as follows:
<pre>apt-cache search <package name> # (Debian-like)
yum search <package name> # (RHEL-like)</pre>
In each case, use parts of the full name to increase the likelihood of getting search results. Note that Debian's <tt>apt-cache search</tt> utility will accept regular expressions (if quoted properly). To search for packages on RHEL-based systems with regular expressions, search results from <tt>yum</tt> can be simply piped to grep:
<pre>yum search <package name> | grep <package regex></pre>

= Installing the Web Server =
== Acquiring Software Packages ==
To begin, refresh the software package database:
<pre>apt-get update # (Debian-like)
yum update # (RHEL-like)</pre>
There may also be software updates. If any are available, <tt>yum</tt> will download prompt you if you want to install them. Debian's apt, on the other hand, only updates the package databases. To install software updates, if any are available, run <tt>apt-get upgrade</tt>.

Next install Apache, PHP and MySQL. '''Debian-based systems''' should have a utility called "tasksel" that can begin installation of all the necessary packages for a LAMP (Linux, Apache, MySQL & PHP) server in one command:
<pre>tasksel install lamp-server</pre>
However, this task usually does not include the package for the PHP cURL extension, so it must be installed separately via <pre>apt-get install php5-curl</pre>

On '''RHEL-based systems:''' run
<pre>yum install mysql mysql-server php-mysql php httpd php-mbstring php-curl</pre>
''On many RHEL-based systems,'' PHP will be built without POSIX support (the compile flag '--disable-posix' should appear in the "Configure Command" section of <tt>phpinfo()</tt> ). Thus, the requirements checker script will not display the proper warning when the apache UID doesn't match the ownership of the web document root. Although it is not necessary (the next steps will ensure that this requirement is met anyway), the POSIX extension can be added if desired by installing the package <tt>php-process</tt> or <tt>php-posix</tt> (depending on the distribution and release version).

There are two more optional but useful PHP extensions: APC (caching extension) and Suhosin (PHP security). These packages should be available in most Debian-based distributions and can be installed via <tt>apt-get install php5-suhosin php-apc</tt>. In CentOS, they can be acquired by enabling the EPEL software repository <ref>[http://www.cyberciti.biz/faq/fedora-sl-centos-redhat6-enable-epel-repo/ CentOS / RHEL / Scientific Linux 6 Enable (Install) EPEL Repo]</ref> and then running <tt>yum install php-suhosin php-pecl-apc</tt>.

== Starting the Server ==
To start the server, run:
<pre>service apache2 start # (Debian-like)
service httpd start # (RHEL-like)</pre>
Navigate to the server with a web browser to verify that the web server is running and responding to requests on its IP address / fully-qualified domain name.

== Assigning a Domain Name ==
Due to the great diversity of DNS services and tools, the exact procedure for associating a domain name with the web server is beyond the scope of this guide. However, the most important facts are:
* To direct a domain name to an IP address, use the <tt>A</tt> type DNS record.
* To direct a domain name to another domain name, use the <tt>CNAME</tt> type DNS record.
For instance, given the hostname of an Amazon Web Services EC2 instance, one would associate a domain name with it via a <TT>CNAME</tt> record (to ensure proper resolution).

= Server Preparation =
The default [http://httpd.apache.org/docs/current/mod/core.html#documentroot DocumentRoot] of Apache Webserver on most distributions of Linux will be owned by the <tt>root</tt> user immediately after installation, whereas its default [http://httpd.apache.org/docs/current/mod/mod_unixd.html#user User] and [http://httpd.apache.org/docs/current/mod/mod_unixd.html#group Group] will be set to "www-data" (Debian) or "apache" (RHEL). This configuration makes it so that no web application whatsoever will have write permissions to the directory it runs in (which is problematic). Thus, the first step of preparation once the server has been installed and started is to ensure the ownership of the files and Apache process are the same.

== Determining the DocumentRoot ==
This is a rather important aspect of a web server is where the files to be served are stored in the local filesystem, and will be necessary in the next steps of this process. To obtain it, search for the DocumentRoot directive in the configuration as follows:
<pre>grep -r '^ DocumentRoot' /etc/apache2/ # (Debian-like)
grep -r '^ DocumentRoot' /etc/httpd/ # (RHEL-like)</pre>
In most cases, the directive will be set to <tt>/var/www</tt> on Debian-based distributions and <tt>/var/www/html</tt> on RHEL-based ones.

== Determining the Apache User/Group ==
On Debian-based systems, these directives are typically set to "www-data", and on RHEL-based systems, to "apache". However, if in doubt, there are at least three methods of finding out the values to which the User/Group directives set.

=== Direct Method ===
The most reliable way of finding out what they are is by searching the configuration files for the directives:
<pre>grep -r '^ *$User\|Group$' /etc/apache2/ # (Debian-like)
grep -r '^ *$User\|Group$' /etc/httpd/ # (RHEL-like)</pre>
Note that on Debian-based systems you may see that, in place of literal strings, there are references to environment variables, i.e. <tt>${APACHE_RUN_USER}</tt>. To find their actual values, search for them in the same manner:
<pre>grep -r '^ *export *APACHE_RUN_' /etc/apache2/</pre>

=== Using ps ===
One can search for the process and see its user, if Apache is already running, using <tt>ps</tt>:
<pre>ps aux | grep '$apache\|httpd$'</pre>
The first column of output should be the user name or id of the running process, whereas the last should be the executable file of the process. Locate the web server process (the path to the executable should be something like <tt>/usr/sbin/apache2</tt> or <tt>/usr/sbin/httpd</tt>).

=== Using PHP's POSIX Library ===
If the POSIX library is available in PHP, you can find the UID by creating a PHP script in the [http://httpd.apache.org/docs/current/mod/core.html#documentroot DocumentRoot] with the following contents and opening it in a web browser:
<syntaxhighlight lang="php">
<?php
echo 'UID (Server): '.posix_geteuid().' ';
echo 'UID (Directory owner): '.fileowner(realpath(dirname(__FILE__)));
?>
</syntaxhighlight>
If the web server is properly set up, both of the numbers displayed should be equal.

== Changing DocumentRoot Ownership ==
Once the UID of the webserver has been determined, change the ownership of the public web directory as follows:
<pre>chown -R <user>:<group> <DocumentRoot> # (Debian-like)
chown -R <user>:<group> <DocumentRoot> # (RHEL-like)</pre>
Use the user name or ID of the running webserver process in place of <tt><user></tt> and <tt><group></tt>, and the server's DocumentRoot in place of <tt><DocumentRoot></tt>.

== Testing the Webserver ==
When done, download the requirements checking script:
<pre>cd <DocumentRoot>
wget http://x2planet.com/installs/download/requirements.php
chown <apache user>:<apache user> requirements.php</pre>

Next, open the file in a web browser to verify that the system meets all of the requirements. Note that, if you see no "posix" section in the phpinfo() output and the flag "--disable-posix" appears in the configure command, and you skipped [[#Changing DocumentRoot Ownership|changing ownership]], the results of the requirements check will not be accurate.

= Preparing a Database =
X2CRM needs a MySQL database for storing persistent data. To prepare this final requirement, you will first need to start the MySQL server daemon:
<pre>service mysql start # (Debian-like)
service mysqld start # (RHEL-like)</pre>

Next, log into the database server as the database administrator (typically root).
<pre>mysql -u root -p</pre>
You may have to enter a password. On Debian systems, during the installation of the MySQL server, you should have been prompted for a root password, and thus you will need to use it for logging in. On Amazon Linux and some other RHEL derivatives, the root password won't be set, and so you can log in without the <tt>-p</tt> flag.

Once you have logged in, create the database, and create a non-admin user with full access to it. The database name "x2crm" and user name "x2crmuser" will be used in this example.
<pre>mysql> CREATE DATABASE x2crm;
Query OK, 1 row affected (0.00 sec)

mysql> CREATE USER x2crmuser@localhost IDENTIFIED BY '<password>';
Query OK, 0 rows affected (0.00 sec)

mysql> GRANT ALL ON x2crm.* TO x2crmuser@localhost;
Query OK, 0 rows affected (0.00 sec)

mysql></pre>

When you install X2CRM on the server, user "localhost" in the database "Host Name" settings, the database name you used in place of "x2crm", and the username/password you used in place of "x2crmuser" and "<password>."

Finally, if the root user on your MySQL server does not have a password set, it is a very good idea security-wise to set a password to protect the server. Do so using the following command (from the system shell, logged out of <tt>mysql></tt>):
<pre>mysqladmin -u root password <newpassword></pre>

= Enabling Login as the Webserver User =
To greatly ease the process of installing and maintaining X2CRM, the default Apache web user (assumed <tt>www-data</tt> in the Debian family and <tt>apache</tt> in the RHEL family, and denoted <tt><apache user></tt> in the general case) can also be used for logging into the server and uploading / altering files, thus avoiding all permissions issues. In many cases, the ability to log in as the web server user will be disabled for security purposes. This is mostly due to how the usernames are easy to guess in brute-force remote login attempts, although this problem can be circumvented. See [[#Securing Login|Securing Login]] for details.

== Setting the Shell ==
In most cases, login as the user is disabled via the shell environment variable. To check that this is so, use the <tt>getent</tt> command as follows:
<pre>getent passwd <apache user></pre>
You should see output that looks like this:
<pre>www-data:x:33:33:www-data:/var/www:/bin/false</pre>
Or:
<pre>apache:x:48:48:Apache:/var/www:/sbin/nologin</pre>
In both cases, the last field in the (colon-delinated) line indicates the login shell; <tt>/bin/false</tt> and <tt>/sbin/nologin</tt> each make it impossible to run a shell as the user. Note also that the second-to-last field is the home directory of the user. If the field is blank (i.e. there are two colons side-by-side before the login shell) it is recommended at this stage to set the home directory of the user as follows:
<pre>usermod -d <DocumentRoot> <apache user></pre>
If that command returns the error message that the user is currently logged in, try again after shutting down the web server as follows:
<pre>service apache2 stop # (Debian-like)
service httpd stop # (RHEL-like)</pre>

Finally, to change the login shell, use <tt>chsh</tt>:
<pre>chsh <apache user> -s /bin/bash</pre>

== Securing Login ==
The risk of brute-force logins can be avoided by ensuring that the main method of logging into the server and transferring files is through the secure shell daemon (SSHD), and that SSHD is configured to disallow password-based logins. SSHD will then require asymmetric key pairs to log in instead of passwords, thus making brute-force password attempts a non-issue. '''If your server is an Amazon Web Services EC2 instance, this will be the case already;''' the key pair is selected/generated before instantiation as the primary means of accessing the virtual server.

=== Configuring SSH For Key-based Authentication ===
On a generic Linux server:
# Begin a shell session as the web server user: <pre>sudo -u <apache user> -i</pre> All of the following commands will be run as this user.
# Create a ".ssh" directory in the user's home: <pre>mkdir -p ~/.ssh</pre>
# Ensure the directory has the proper permissions: <pre>chmod 700 ~/.ssh</pre>
# Run: <pre>ssh-keygen -t rsa</pre> and (optionally) enter a passphrase to protect the key. The keypair, when done, should be stored as the files <tt>~/.ssh/id_rsa</tt> (private) and <tt>~/.ssh/id_rsa.pub</tt> (public).
# Create the authorized_keys file with the public key to enable authenticating with the private key on the remote end: <pre>cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys</pre>
# Ensure the authorized_keys file has the proper permissions: <pre>chmod 600 ~/.ssh/authorized_keys</pre>
# Download the private key (<tt>~/.ssh/id_rsa</tt>) and delete it from the server as soon as possible.

'''If the server is an Amazon EC2 instance,''' it is not necessary to create a new key pair; the existing key pair can be used for authentication, if desired, by using the existing authorized_hosts file in the <tt>.ssh</tt> directory of "ec2-user" (Amazon Linux) or "ubuntu" (Ubuntu) into the <tt>.ssh/</tt>, as follows:
# Make the directory and copy the files: <pre>mkdir -p ~<apache user>/.ssh; cp ~<default user>/.ssh/authorized_keys ~<apache user>/.ssh/</pre>
# Ensure proper user/group ownership of the files: <pre>chown -R <apache user>:<apache group> ~<apache user>/.ssh</pre>
# Ensure proper permissions of the files: <pre>chmod 700 ~<apache user>/.ssh; chmod 600 ~<apache user>/.ssh/*</pre>
Note that you may still have to protect the <tt>.ssh</tt> directory.

=== Protecting ~/.ssh ===
If the user's home directory is the same as (or lies within) the web server's DocumentRoot (this is the case for the default LAMP configuration on Ubuntu 12.04), it is generally a very good idea to prevent all HTTP access to the directory storing the public key, regardless of whether the key pair is password-protected. The most straightforward way of doing this is by editing the main Apache configuration (<tt>/etc/apache2/apache2.conf</tt> Debian, <tt>/etc/http/conf/httpd.conf</tt> RHEL ) and adding the following lines to it (for Apache versions 2.0-2.2):
<syntaxhighlight lang="apache">
<Directory /var/www/.ssh>
Order allow,deny
Deny from all
</Directory>
</syntaxhighlight>
If using Apache 2.4 or later, you can use the non-deprecated configuration directive "Require"<ref>See: [http://httpd.apache.org/docs/2.4/howto/access.html Apache 2.4 Documentation: Access Control]</ref> as follows :
<syntaxhighlight lang="apache">
<Directory /var/www/.ssh>
Require All Denied
</Directory>
</syntaxhighlight>
In both of these examples, it is assumed that the home directory is <tt>/var/www</tt>.

For extra privacy and security, it may also be desirable to deny access to all hidden dotfiles and directories used by the user shell and local programs (i.e. <tt>.bashrc</tt>, <tt>.bash_history</tt>, <tt>.viminfo</tt> etc.), in which case you can use the following directive:
<syntaxhighlight lang="apache">
<DirectoryMatch /var/www/\..*>
# Denial directives i.e. "Require All Denied" go here
</DirectoryMatch>
</syntaxhighlight>

=== Disabling Password-based Authentication ===
To verify that password authentication is disabled, search for the directive in the SSHD configuration (which should be in the same place on almost every Linux and Unix system<ref>Assuming the ubiquitous [http://www.openssh.com/ OpenSSH] server is the software in use. All RHEL-based and Debian-based Linux systems, as well as FreeBSD, use OpenSSH as their chosen SSH server, and as of this writing none of the mainstream distributions are known to build OpenSSH such that the path to the daemon's configuration file is any different.</ref>):
<pre>grep '^PasswordAuthentication' /etc/ssh/sshd_config</pre>
In the output of <tt>grep</tt> you should see this:
<pre>PasswordAuthentication no</pre>
If this is not the case, i.e. if it reads "yes" instead of "no", or the only instance of "PasswordAuthentication" is commented in the file by having its line begin with a hash symbol ("#"), edit the file <tt>/etc/ssh/sshd_config</tt> so that it contains a line that reads <tt>PasswordAuthentication no</tt> and then restart the SSH daemon to enact the changes via <tt>service ssh stop</tt> (Debian) or <tt>service sshd stop</tt> (RHEL). However, '''before doing this,''' ensure that the primary administrative user already has a key pair set up for remote access; you will otherwise be locked out of your server. To do this, the same method that was used for creating a key pair for the web server user can be used to do so for the administrative user.

= Notes & References =
<references />

Software Updates and Upgrades

2014-12-04T00:32:22Z

Derek Mueller: /* Updating to Beta Versions */

[[Category:Support]]

= Introduction =
The following things happen in typical a software update (or upgrade):
* Files that are new in the new version are added
* Files that have been changed in the new version are replaced with the new versions of those files
* Files that are no longer used in the new version are deleted
* Changes to the database are made to make the database compatible with the new version of X2Engine
* The main configuration file, <tt>X2Config.php</tt>, is edited to reflect the new state of the application.
* X2Engine data caches are cleared

These operations are typically handled by the updater utility component [[x2doc:UpdaterBehavior|UpdaterBehavior]] and controlled via the in-app web-based updater or the command line updater. This article will cover both how to use said interfaces to the updater, and how to perform updates manually or with the "offline" method if the need arises, in addition to troubleshooting and recovering from an update that did not complete cleanly.

= Disclaimer =
This article covers the standard and recommended update/upgrade methods, in addition to alternate methods and supplemental procedures. As general rules and precautions for using this article:
# ''If you do not fully and completely understand any step of any instructions given in this article, '''do not''' follow them''; ask for help instead on [http://x2community.com the forums] or through contacting X2Engine Technical Support if you are an existing customer.
# You should always make a backup of all of your files ''and'' a full backup copy of your database, preferably in a format (i.e. SQL script) that can be used to create a verbatim/carbon copy of the original database, with all of the features of the original schema, '''before''' attempting any steps of the update process manually.
# Some of the procedures outlined in this article involve manually creating or modifying files. Note that the same filesystem prerequisite for installation, namely that the file ownership must match the user under which PHP executes on the web server, applies to these steps.

Furthermore, '''in regard to uploading files:''' note that any instructions to upload folders into X2Engine, and replace/merge contents, refer to replacing files in X2Engine with files in the archive at analogous paths. For example, if you have a zip file that contains a folder <tt>protected</tt>, and inside of that is a folder <tt>components</tt>, and inside of that is a file <tt>UpdaterBehavior.php</tt>, and the instructions are to upload/replace in X2Engine, you should upload <tt>UpdaterBehavior.php</tt> to replace the existing file of the same name in <tt>protected/components</tt> inside of X2Engine.

X2Engine Inc. cannot be held accountable for damage/errors caused by any missteps or mistakes in manually-performed update operations. If in doubt, make a sandbox/clone of your X2Engine installation by copying the files and database to a different server, and test performing the operations on that before proceeding with your production install of X2Engine.

= Update Notifications =
[[File:Update Notification.png|200px|frame|right|System flash message displaying software update notification.]]
To get notified of software updates, unless already using X2Engine Professional Edition, one must first "subscribe" to them. This can be done via checking the box "Notify me of software updates" in the installation form. If X2Engine is already installed, this can be done by going to "Updater Settings" from the Admin page and enabling them. If using Professional Edition, these steps are not not necessary.

Once that has been completed, set the update notification interval as desired in "Updater Settings".

= Update Methods =
[[File:Update_Process.svg|200px|thumb|right|Top-level overview of the update process]]
There are, in essence, just three basic methods of updating, and variations on each. The three main methods are:
# web updater,
# command line updater, and
# manually.
In each case, an update package from the update data server is used as the authoritative list of changes to apply, but in the non-manual methods, X2Engine's own updater class does all the work applying changes from said package.

In web and command line updates, there is also the option to first download and unpack the package manually (see [[#Performing_.22Offline.22_Updates|performing "offline" updates]]). This circumvents the need for the local server (on which X2Engine is hosted) to be connected to the internet. Similarly, in the case of manual updates, it is not necessary for the web server to actually have an internet connection.

== Using the Web Updater ==
[[File:Updater-1.png|300px|thumb|right|The updater utility page.]]
The web updater can be accessed by any of the following methods:
* Using the link in the notification message at the top of the window in versions later than 3.5.5
* By going to the Admin page and clicking the "Update" button at the top, in earlier versions, with update notifications enabled
* Through "Update X2Engine" under "System Settings" in the Admin page

=== How to use ===
First, navigate to the web updater page, and '''do not''' cancel the request (stop or hit your browser's "back" button) until the page has loaded. If the updater utility has undergone changes and needs to self-update to be compatible with the software updates server, this is when it will do so. Thus, it is critical that you do not interrupt this process. If the page does not load, or displays the error message that dependencies could not be retrieved, you may have to [[#Performing_.22Offline.22_Updates|perform an "offline" update]].

There are three ways of getting to the updater page. One is to simply click the link given in the update notification flash message, if available. The other is to click on the "Update" button at the top of the admin page. If software update notifications are not enabled, one can manually check for and install an update by going to "Update X2Engine" under "System Settings" in the Admin page.

Next, make a backup of the database and files (recommended), follow the instructions on the page, and click the "Update" button when ready.

=== Advantages ===
It is generally quick and is the easiest method to use, and it does not require shell/SSH access to the web server.

=== Disadvantages ===
It is not recommended for use on large installations of X2Engine, i.e. containing over a million records, or for updating from very old versions (i.e. a version more than five months old). This is because, in such cases, the final update process will take a very long time. It will thus be more likely that the process will be cut short by a server gateway timeout or an interruption in the network connection. '''This can result in an incomplete/broken update''' that requires [[#Recovering_From_Failed_Updates|recovering manually]] at best, or actual loss of data at worst.

==== Explanation ====
The inherent weakness of the web updater (or any web-based updater to any web application) is that it must always rely upon web requests to the server, and it thus must perform extremely critical operations for the update all within the scope of a web request. Web requests, it goes without saying, are not always reliable.

For example, one's internet connection might get cut off due to being on a wireless network and encountering interference, i.e. from a 5.8 GHz cordless phone or microwave oven. Furthermore, if any operations take an exceedingly long amount of time, e.g. because of the size of the data set (and thus indexes) on which the update must operate, or the number of database changes that need to be applied, the web request for those operations may take longer than the PHP execution time limit as configured on the webserver.

In the event of a failed request to the server, the update could be cut short at a critical update stage, and thus require manual recovery at best, or completely restoring X2Engine to a backup at worst.

==== How to Avoid Timeouts ====
You can usually get around this by setting the value of <tt>'''max_execution_time'''</tt> to a higher value in the web server's PHP configuration. It is highly recommended that you either disable the timeout or set it to a very generous value (such as 300 or more seconds) while attempting to update via the web updater, especially if you are many versions behind or have a high volume of data in your CRM.
Also, it is generally always a good idea to create a backup copy ''before'' updating, and to download it.

==== Recovering From Crashes ====
If you downloaded the backup copy of your database, then after you encounter a failure/timeout, you can use the .sql backup script to restore the database to its original form. However, be aware, that if there are any '''<tt>CREATE TABLE</tt>''' commands in the update data (expand the ''Database Commands to Run'' list to see), you will need to manually drop the created tables in order to once again make your installation compatible with the update.

See [[#Recovering_From_Failed_Updates|Recovering From Failed Updates]] for comprehensive information on this process.

== Using the Command Line Updater ==
This update method uses all of the same thoroughly-tested underpinnings and processes as the web updater, but does so all within a system command to the Yii console.

=== How to use ===
While in via SSH, or in a terminal emulator, or in a script, run the following command in the <tt>protected</tt> subdirectory of X2Engine:
<syntaxhighlight lang="bash">./yiic update app</syntaxhighlight>
Note the following optional arguments to the command line updater:
;<tt>--force</tt>
: Use "1" for this option (i.e. <tt>--force=1</tt>) to proceed with the update even if compatibility issues were detected. Default: 0 (halt if compatibility issues were detected).
;<tt>--backup</tt>
: Use "1" to specify that a database backup should be performed first before updating, "0" to proceed without creating a backup first. Default: 1.
;<tt>--lock</tt>
: Use "1" to specify that the application should be locked during the final installation of the update package to prevent data entry during the sensitive moments when the database is being altered and the files updated, "0" to permit use even when changes to the app are being applied. Default: 0.

If running the command gives you the following message:
<pre>The updater is now up-to-date and compliant with the updates server. Re-run the command to proceed.</pre>
That indicates that the updater first needed to self-update, and succeeded in doing so. You should then run the same command again to complete the update.

=== Advantages ===
Safer to use on large, mission-critical systems, and is in general the simplest and most reliable update method. The success of a software update (or upgrade) does not hinge upon a single web request completing successfully, like it does with the web updater.

=== Disadvantages ===
More difficult to use; requires shell access to the web server. The console command must be run as the same system user that owns all the files and directories of X2Engine, in order to circumvent permission issues when manipulating file system objects.

== Using the Automatic Updater ==
[[File:Auto-Update.png|400px|thumb|right|Auto-update scheduler on the Updater Settings page]]
This method uses the command line updater, but runs the command on your behalf using the local cron daemon. To configure, go to the Updater Settings Page, check the box titled "Update Automatically", and save. If you have Professional Edition, you can manage the update schedule in addition to other automated tasks from the Cron Table settings page, which can also be found under "System Settings" in the Admin page.

=== Advantages ===
Automates the entire process of updating.

=== Disadvantages ===
Only available on UNIX-like systems that have a local cron service running, and which permit user access to the cron table.

== Performing "Offline" Updates ==
In some server environments, the updater may not be able to access the updates server by itself, due to (for example) the PHP or network configuration, or because the "zip" PHP extension (requried) is unavailable or has been disabled. It is in these situations necessary to download the update package manually, unpack on the server (or unpack and upload the files to the server), and then run the updater. When performing updates in this way, the updater will not need to access the updates server, but will use the manually-downloaded and extracted package files present in the local filesystem.

=== Refreshing and Updating the Updater Utility ===
Before starting, note that the updater itself may have undergone changes; the X2Engine update process is subject to change. To address this technical challenge, the updater utility within X2Engine would normally first attempt to download the latest version of itself, in order to be compatible with the updates server. However, this sometimes will not work properly. If your X2Engine installation is running in a hosting environment that prevents it from making outbound HTTP requests (the [[requirements:|requirements check script]] should tell you if this is the case), you will need to do this manually. Also, in version 3.5.5, there was a bug in the updater utility's self-update methods.

To update the updater utility:
# '''Determine the version of the updater utility package''' by visiting [https://x2planet.com/installs/updates/updateCheck this link]. You should see a page that's entirely blank except for a version number.
# '''Download the updater package.''' In versions 3.6 and later, a download link for this should be available through the ''Updater Settings'' page. Otherwise, use the following URL (if in Open Source Edition): <pre>https://x2planet.com/installs/updater.zip</pre> Otherwise, if using Professional Edition, paste the following url, after replacing {key} with your license key, into your browser's address bar: <pre>https://x2planet.com/installs/{key}/updater-pro.zip</pre>
# '''Extract the downloaded zip archive and upload''' the "protected" folder to your server. Merge folders and overwrite existing files when prompted.
# '''Open the file <tt>protected/config/X2Config.php</tt> in a text editor''' and find the line that looks like this:<syntaxhighlight lang="php">$updaterVersion = '3.5.2';</syntaxhighlight>
# '''Change the text inside the pair of single quotes''' on that line so that it is the current updater version obtained in step #1.
# '''Save the file.'''

=== Obtaining the Update Package ===
First, use the link in the ''Updater Settings'' page entitled "Latest Update Package for Version...", to download the update package. If the link in the Updater Settings page does not work, use the following URL to download the update package (if using Open Source Edition), replacing <tt>{version}</tt> with your X2Engine installation's version:
<pre>https://x2planet.com/installs/updates/{version}/none</pre>
You should receive, from that URL, a zip archive file called "update.zip".

If using Professional Edition, and your download link is not working, contact [mailto:customersupport@x2engine.com customer support].

=== Unpacking the Update ===
[[File:Update-in-Progress.png|200px|frame|right|System flash message displaying notification of pending update.]]
The update package will be a zip archive. The ''contents'' of this archive must be extracted ''into'' a folder called "update" in the installation directory. So, in other words, after extracting and uploading to the server, there should be a folder called <tt>update</tt> alongside <tt>protected</tt>, <tt>assets</tt>, <tt>framework</tt> (etc). Within that folder (<tt>update</tt>) should be the following contents:

;<tt>manifest.json</tt>
: A file containing important data to be used by the updater
;<tt>contents.md5</tt>
: A message digest file containing MD5 checksums of all files in the archive excluding itself.
;<tt>source</tt>
: A sub-folder/directory, whose internal structure mimics that of X2Engine, containing files that were changed in the update. If there were no files changed (i.e. only database changes were in the update), this directory will not be present.
;<tt>data</tt>
: A directory containing flat data files. These files are typically not used by the updater, but are useful if performing manual updates or recovery.

=== Applying the Update ===
[[File:Steps-post-Unpack.png|200px|frame|right|Steps of the update process in the event of manually-extracted package (or resuming a preexisting update)]]
After unpacking, if you run the command line updater, it should (if no problems arise, i.e. incompatible package version) apply the update straight away. Otherwise, log into X2Engine, and you should see a system flash message notifying you of an update in progress. This message shows up whenever there is an update package folder ("update") present on the server. If you then go to the updater page, once the page has finished loading, you should see that there only remain the steps "Review and confirm changes", "Apply changes" and "Reload" remain to be completed. To complete the update, when ready, click "Update"; otherwise, to delete the "update" folder and cancel the update, click "Cancel" either on the updater page or in the system flash message.

== Performing Updates Manually ==
While it is preferable to avoid manually applying changes to X2Engine, and you may never need to, it may in some circumstance or another actually be necessary to do so. For all such situations, the raw update data files generated by the X2Engine update build process are bundled with every update package to help you perform the operations described in [[#Introduction|"Introduction"]]. This section will describe how to perform each of those operations.

=== Prerequisites ===
First and foremost, all shell commands listed here, and in general, any operations that create or modify files, ''must be run as the same system user under which the server runs PHP scripts.'' Otherwise, the ownership and/or permissions of files and directories will have to be changed after completing all changes.

To obtain the update package (which will be necessary), refer to "[[#Obtaining_the_Update_Package|Obtaining the Update Package]]".

Furthermore, it is strongly advised that you first make a back-up copy of all files and of X2Engine's database. Your database backup would best be a full, exact copy, such as one that would be made by [http://dev.mysql.com/doc/refman/5.1/en/mysqldump.html mysqldump], or the built-in export tools of [http://www.phpmyadmin.net/home_page/index.php PHPMyAdmin].

The X2Engine global import/export utility ("Import All Data"/"Export All Data") in Admin '''is not recommended by itself as the sole backup tool'''. This is especially important to note because of how this tool cannot re-create ancillary data such as tags or relationships, or user roles. However, using it to ''supplement'' your standard database backup method will prove useful in the event that you:
# don't have any custom roles, relationships, tags, etc.
# cannot manage to update X2Engine with success, and
# wish to start over with a fresh installation.
In such a case, you will then be able to import your old data into the new installation.

=== Introduction: Data Files ===
In [[#Unpacking_the_Update|Unpacking the update]], a rough overview of an update package's contents were given. In this section, the anatomy and purpose of each of the data files will be introduced.

Included in every update package is two copies of the following data:
* Files to copy
* Files to delete
* Database changes to enact
* Migration scripts to run, if any

The first, immediately visible place where all of this data is stored is in the file <tt>manifest.json</tt>, as a JSON-encoded array. See the next section for how to use this file.

The second place, which can be useful to users who do not wish to automate or script any step of a manual update, is in the files contained in the <tt>data</tt> directory. Each file is named after the version to which it corresponds, and contains the data required to update ''to'' that version ''from the version immediately preceding it.''' Thus, the versions you should see in each file name are the versions above your X2Engine installation's current version, up to and including the version being updated to.

In an update, the directory will contain the following subdirectories:
;<tt>fileList</tt>
: Contains files for each version, each containing the list of files to copy. The format is each line containing a file path in the list.
;<tt>deletionList</tt>
: Contains files for each version, each containing the list of obsolete files for that version which will need to be deleted. The format is the same as in <tt>fileList</tt>.
;<tt>sqlList</tt>
: Contains .sql scripts corresponding to each version. Each file is formatted such that it can be directly run on the database as an SQL script, although this is not generally recommended. The list of SQL commands to run is a of the following format:
[query 1];
/*&*/
[query 2];
/*&*/
[etc]
;<tt>sqlForce</tt>
: Contains .sql scripts with similar naming and formatting conventions to the <tt>sqlList</tt> scripts. See [[#The_structure_of_the_.22data.22_array|The structure of the "data" array]] for explanation of the purpose of <tt>sqlForce</tt>.

=== How to use the manifest for updating manually ===
If you so choose, you may write a script to perform all of the operations for an update in one fell swoop. If so, and if the preferred scripting language of choice has a JSON-parsing library available, you will be able to save yourself a lot of effort by using the main data file (<tt>manifest.json</tt>) to load all of the necessary data for the update.

==== The structure the manifest ====
In updates, the contents of the plain-text file manifest.json are a JSON-encoded object containing the following properties:
;<tt>data</tt>
: An array containing the data corresponding to each intermediate version. It is, in essence, all the data stored in the files in <tt>update/data</tt>. If the update is for an installation of X2Engine that is only one version behind, it will contain only one element. Each element of this array is itself an array containing respective data for the intermediate version.
;<tt>versions</tt>
: An array listing the version numbers of each intermediate version in the update. Similar to <tt>data</tt>, this array will contain only one element if updating to the next version, and that version ''will be the next version''.
;<tt>deletionList</tt>
: An array containing the cumulative list of deletions of obsolete files across versions through which the update traverses.
;<tt>fileList</tt>
: An array containing the cumulative list of files added or changed across versions through which the update traverses.
;<tt>fromVersion</tt>
: A string, containing the version number that the update is ''from'', or in other words, the version of X2Engine before the package is applied. '''This must be the same as the version of installation to which the package is being applied.''' If this is not so, the updater utility would exit immediately, as applying the changes in the update would have potentially harmful results to data and/or compatibility with future updates.
;<tt>targetVersion</tt>
: A string, containing the version number that the update is ''to'', or in other words, the version of X2Engine before the package is applied.
;<tt>updaterVersion</tt>
: A string denoting the version of the updater utility for which the package was compiled. If the structure of the update package or of the manifest changes, the updater must also change to accommodate and recognize the changes; else it might try to access properties that don't exist, or ignore important ones that do. This is the single property of manifest.json that should never change.
;<tt>scenario</tt>
: A string, which should be "update" if the package is for an update. In the case of upgrades, which use most of the same functionality of the updater, it should be "upgrade".
;<tt>targetEdition</tt>
: A string denoting the edition of the X2Engine installation after the package is applied. It should be "opensource" for open source edition, "pro" for professional edition. In the case of an upgrade package, it differs from the <tt>fromEdition</tt> property.
;<tt>fromEdition</tt>
: A string denoting the edition of the X2Engine installation before the package is applied.
;<tt>buildDate</tt>
: An integer denoting the timestamp of the release date of the version of X2Engine denoted by <tt>targetVersion</tt>

==== The structure of the "data" array ====
In updates, each version's data, contained in each element of the <tt>data</tt>, contains the following nested array properties:
;<tt>fileList</tt>
: The list of files added for the version
;<tt>deletionList</tt>
: The list of files deleted in the version
;<tt>sqlList</tt>
: A list of SQL commands to bring the database structure and contents into compliance with the version from the previous version
;<tt>sqlForce</tt>
: A prerequisite list of SQL commands that should be run before those in <tt>sqlList</tt>, and if any fail, the failures should be ignored. These are added to updates whenever it is necessary to normalize the database schema, i.e. in the event that some installations' databases may not be consistent with others, but the commands might fail on every other system. These SQL commands were intended to be "attempted"; they are not guaranteed to succeed on all installations. An example of when this is necessary would be adding a foreign key constraint when in previous versions the storage engine was left to the database's default settings in old versions. MyISAM does not natively support foreign key constraints. Thus, to standardize this across all installations, including installations on servers where the storage engine defaulted to MyISAM, the constraint must first be dropped (in a <tt>sqlForce</tt> command) before the relevant tables are changed to the InnoDB storage engine, and the constraint is added back again, in the usual <tt>sqlList</tt>.
;<tt>version</tt>
: The version number
;<tt>edition</tt>
: The edition
;<tt>migrationScripts</tt>
: A list of PHP scripts that would be run in an update for this version. These are a subset of fileList and are typically used for advanced database operations, i.e. restructuring values of JSON-encoded fields, which are extremely impractical (or impossible) to perform using raw SQL commands. The files contained in the list all have paths that look like "<tt>protected/migrations/{version}/{timestamp}-name-of-operations.php</tt>". Note, if this array is not empty, and the <tt>'''runmigrationscript'''</tt> Yii command does not work (or isn't available yet), you may need to reverse-engineer or otherwise copy and re-purpose/re-write any migration scripts listed in order to perform their necessary operations. This is because they often depend on running within a Yii Framework environment, i.e. will contain references to components of the Yii application singleton such as "db".

Also note that in upgrades, <tt>fileList</tt> and <tt>sqlList</tt> are replaced by <tt>fileUpgrade</tt> and <tt>sqlUpgrade</tt> (respectively), and <tt>deletionList</tt>, <tt>sqlForce</tt> and <tt>migrationScripts</tt> are missing (because they aren't necessary).

==== What you will need for the update, if using the manifest ====
''Among this data, what you will need:'' <tt>deletionList</tt>, which will give you the full list of files that need to be deleted, <tt>fileList</tt>, which will give you the full list of files to copy from the <tt>update/source</tt> directory, <tt>updaterVersion</tt>/<tt>targetVersion</tt>/<tt>buildDate</tt>, which give you values with which to update the main X2Engine configuration file, and, within each element of <tt>data</tt>, the sub-array properties <tt>sqlList</tt>, <tt>sqlForce</tt> and <tt>migrationScripts</tt>, with which you will construct the list of database commands to run.

A procedure for manually updating X2Engine, with data from manifest.json, thus might look like this:
# For each element of <tt>data</tt> (or in other words, each version's changes):
## Run all the SQL commands in its corresponding <tt>sqlForce</tt> sub-array, ignoring errors
## Run all SQL commands in its <tt>sqlList</tt> array
## Perform database operations that would be equivalent to those performed in migration scripts
# For each file in the cumulative list <tt>fileList</tt>, copy it from the <tt>update/source</tt> directory into its analogous location in the installation directory of X2Engine, creating parent directories as necessary if they don't already exist.
# Delete all files in the cumulative list <tt>deletionList</tt> from the installation directory
# Clear the data cache files in <tt>protected/runtime/cache</tt> and the temporary asset folders in <tt>assets/</tt>
# Clear all session data (<tt>x2_sessions</tt>) and auth cache data (<tt>x2_auth_cache</tt>).
# Update the main X2Engine configuration (<tt>protected/config/X2Config.php</tt>) file, setting:
## <tt>$buildDate</tt> to the <tt>buildDate</tt> property,
## <tt>$version</tt> to the <tt>targetVersion</tt> property, and
## <tt>$updaterVersion</tt> to the <tt>updaterVersion</tt> property.

=== Enacting Database Changes ===
Inside the <tt>update/sqlList</tt> and <tt>update/sqlForce</tt> folder is a list of <tt>.sql</tt> files, named according to their corresponding version's update, that can essentially be run as SQL scripts to perform the update. Note, however, that '''if the update traverses more than one version, the scripts must be run in the order of their corresponding version.''' This is because, in the database changes for any version, it is assumed that the database schema and contents conform to the version that immediately preceded it. The PHP function [[phpfunc:version-compare|version_compare]], and the method "[http://pythonhosted.org/setuptools/pkg_resources.html#parsing-utilities parse_version]", in the pkg_resources module of setuptools, should correctly identify which version should come first. Note, the [[#The_structure_the_manifest|"versions" property of the manifest]] will contain the list of versions in the correct order.

Furthermore, note, "sqlList" and "sqlForce" may not encompass all necessary database changes; if there are any migration scripts in the update, the operations they perform will similarly need to be performed in the current update (see the description of <tt>migrationScripts</tt> in [[#The_structure_of_the_.22data.22_array|"the structure of the 'data' array"]]).

In summary, for each version traversed in the update, the following operations should be run in order, with <tt>{version}</tt> being the version number of the version in question:
# '''Run all of the SQL commands in the <tt>data/sqlForce/{version}.sql</tt> file,''' in the order they appear in the file. Ignore if any commands fail. Note, if passed to the MySQL client as a script, any failures might trigger a halt in execution and thus skip the remainder of the commands.
# '''Run all of the SQL commands in the <tt>data/sqlList/{version}.sql</tt> file.'''
# '''Run migration scripts using <tt>./yiic runmigrationscript {path}</tt>, if any.''' The first part of a script file name is the timestamp it was added to the codebase, and this also dictates the order in which they should be run.

=== Copying new files ===
Files added/changed in the new version are stored in the <tt>update/source</tt> directory. In an update, they should be copied into the installation directory, replacing any existing files of the same name/path. If the <tt>rsync</tt> utility is available on the system, you can use one command to safely copy these files into the installation directory as follows (executed in that same directory):
<syntaxhighlight lang="bash">
rsync -avc update/source/ ./
</syntaxhighlight>
Otherwise, you will need to use <tt>cat</tt> and <tt>cp</tt>, two utilities that should be available on every UNIX-like system, and the lists of files added in each intermediate version. These lists are stored in the folder <tt>update/data/fileList</tt> and named like "{version}.txt" (<tt>{version}</tt> being the version to which it applies), each file on its own line in that file. Run the following command, ignoring errors:
<syntaxhighlight lang="bash">
for f in update/data/fileList/*; do for l in $(cat $f); do cp update/source/"$l" ./"$l" ; done ; done
</syntaxhighlight>

=== Deleting old files ===
Files to be deleted are listed in a similar manner as the files to be added: one file per line. The list of files to delete are located at files with paths that look like this: <tt>update/data/deletionList/{version}.txt</tt>
So, for an update from 5.5 to 5.7 with intermediate version 5.6 (for instance), the files would be <tt>update/data/deletionList/5.6</tt> and <tt>update/data/deletionList/5.7</tt>.

If there is only one version through which to update, the operation is very simple, and can be performed in one UNIX/Linux (bash) shell command as follows (if the version is 3.6.3, for example):
<syntaxhighlight lang="bash">
xargs -a update/data/deletionList/3.6.3.txt -d"\n" rm -fv
</syntaxhighlight>
Otherwise, if there are multiple versions, this may be a more tricky proposition. The necessity arises to create a cumulative list, because there might be the possibility that a file is deleted in one version and re-established in a new version. Nevertheless, while this is possible, it is highly unlikely, and in most cases it is safe to simply iterate over all the <tt>deletionList</tt> data files and delete all the files listed therein. As a bash command:
<syntaxhighlight lang="bash">
for f in update/data/deletionList/*; do xargs -a $f -d"\n" rm -fv ; done
</syntaxhighlight>

=== Editing the Configuration File ===
This final step in the update process, before refreshing, should not be done manually unless you are completely certain that all the files (not counting customizations) and the structure of the database are equivalent to a fresh installation at the same version as the one to which you have updated.

To update the configuration manually:
# Open the file <tt>protected/config/X2Config.php</tt> in a text editor
# Find the line with the <tt>$version</tt> variable in it. It should look like this (but with the version from which you are updating): <syntaxhighlight lang="php">$version = '3.5.2';</syntaxhighlight>
# Change the value in quotes to the current version being updated to, and save the file.

=== Clearing caches and refreshing the application ===
It is generally always a good idea to clear the application's server-side cache and other ephemeral files/data after updating. This is taken care of automatically by the built-in updater, but barring proper use and functioning of that, the operations can be performed manually as follows:
;clear the data cache
: delete all "<tt>.bin</tt>" files in <tt>protected/runtime/cache</tt>: <syntaxhighlight lang="bash">rm -fv protected/runtime/cache/*.bin</syntaxhighlight>
;clear web assets
: delete all sub-folders of <tt>assets</tt> by running this command (in the installation directory): <syntaxhighlight lang="bash">rm -r assets/*/</syntaxhighlight>
;clear the "auth cache"
: Flush the auth cache table, i.e. run the following command on the database:
<syntaxhighlight lang="mysql">
DELETE FROM `x2_auth_cache` WHERE 1;
</syntaxhighlight>
;log all users out
: Flush the sessions table, i.e. run the following command on the database:
<syntaxhighlight lang="mysql">DELETE FROM `x2_sessions` WHERE 1;</syntaxhighlight>

= Upgrading =

== Using the Web Interface ==
[[File:Software-Upgrade-Registration.png|400px|thumb|right|Software upgrade page, in the first step (registration)]]
To upgrade to Professional Edition
# Purchase X2Engine Professional Edition Download. Note the registration info in the activation email.
# Go to the Admin page in X2Engine and find "Upgrade X2Engine" under "System Settings".
# In the ''Upgrade'' page, enter your registration info into the form and click "Register" to continue. Once complete, you will see a list of changes similar to those displayed when performing an update.
# Review the changes to be applied and then proceed by clicking "Upgrade", similar to performing an update.

== "Offline" Upgrading ==
This works in exactly the same way as offline updating. However, to obtain your upgrade package, which you will extract into a folder called "update" on the X2Engine web server, contact [mailto:customersupport@x2engine.com customer support]. Furthermore, you will need to run the following database command on your X2Engine database when done with the upgrade, replacing <tt>{product key}</tt> with your product key, to allow your installation to receive Professional Edition software updates:
<syntaxhighlight lang="mysql">UPDATE `x2_admin` SET `unique_id`='{product key}' WHERE `id`=1;</syntaxhighlight>

== Manually Upgrading ==
The process of upgrading is very similar to that of updating, and uses all of the same underpinnings as the updater. Thus, almost all of the above information and procedures will apply to upgrades. However, note the following crucial differences:

* '''X2Engine must be at the latest available version in order to upgrade.'''
* '''To obtain the upgrade package, you must be an owner of an X2Engine Professional Edition Download-type license.''' Contact [mailto:customersupport@x2engine.com customer support] for further details.
* '''There will be only one "intermediate" version.''' The changes to apply will move X2Engine from a version to that same version, applying instead the necessary changes to switch its ''edition'' from Open Source to Professional.
* '''There are no file deletions.'''
* '''The properties of the package manifest differ slightly.''' In upgrades, the properties of the data object are <tt>sqlUpgrade</tt> and <tt>fileUpgrade</tt> instead of <tt>sqlList</tt>, <tt>fileList</tt>, etc. Note also, the update data is in aptly-named sub-folders of <tt>update/data</tt> as well, and there are no <tt>sqlForce</tt> or <tt>migrationScripts</tt> lists to handle.
* '''The configuration is not changed.''' Instead, the value stored in the field <tt>unique_id</tt> of the admin record in the database table <tt>x2_admin</tt> must be changed to the license key, and the <tt>edition</tt> field must be changed to "pro". To perform these both, run the following command on the X2Engine database: <syntaxhighlight lang="mysql">UPDATE `x2_admin` SET `unique_id`='{license key}',`edition`='pro' WHERE `id`=1;</syntaxhighlight>
* '''It is not necessary to clear caches or user sessions when done.''' These operations are performed in updates to eliminate ephemeral (session-ingrained) data that may no longer be applicable and thus cause problems. Upgrades will rarely, if ever, invalidate this data.

= Updating to Beta Versions =
'''Please note: Beta versions are for testing purposes only and are not intended to be deployed in your production environment.'''

Beginning at version 4.1.2, after much advocacy to adopt this practice, X2Engine began a two-phase release process in which each version would be released first as a beta, then to the broader public after initial bug finds. The purpose behind this is to avoid updating production installations of X2Engine to new versions that have had zero public exposure, and thus avoid introducing bugs that were not found in initial QA testing (due to a incompatibility with a particular server environment or configuration of X2Engine) into sensitive production environments.

By default, the updater will not update to beta versions. The updater must be configured to use the proper URL on the update server for beta release data, by the following procedure:
# Create a file "constants-custom.php" in the root level of X2Engine. You can easily do this by renaming "constants-custom.example.php" to that name (remove ".custom").
# Look for the following line, and in it, change "false" to "true": <syntaxhighlight lang="php">defined('X2_UPDATE_BETA') or define('X2_UPDATE_BETA',false);</syntaxhighlight>

The advantage of enabling beta releases is that new features will be available much sooner. Additionally, fixes to bugs will also be available sooner. The main disadvantage of enabling beta releases is that they are never guaranteed to be as stable as non-beta releases. We encourage users to clone their installations of X2Engine and use beta versions on them, and report any issues they encounter for their particular server environment/special configuration/custom implementation of X2Engine. This way, any issues that arise can be fixed in the stable release. The more users participate in beta testing, the more stable the non-beta releases will become.

= Recovering From Failed Updates =
Uh-oh. You attempted to update, and found out too late that the database was incompatible with the changes. You might have used the web updater and experienced a server timeout, or made changes to the schema outside of X2Engine that conflicts with the update. Your backup is either out of date or nonexistent.

Fortunately, recovery from such a scenario is fairly straightforward provided one has basic knowledge of MySQL, but it requires hands-on work with the files and MySQL database. If you have no experience managing databases either through a MySQL command console or a web UI (i.e. [http://www.phpmyadmin.net/home_page/index.php PHPMyAdmin]), it is recommended you seek help with this process. Furthermore, like manually updating, this process requires access to the file system. If all that is available to you is accessing your application via the web, i.e. pure SAAS, you will need to contact your hosting provider or system administrator for assistance.

== Recovery Checklist ==
In summary, before beginning, you're going to need the following:

* '''Access to the file system and database of X2Engine.''' Without these, your hands are tied, and you cannot effectively do anything. You will need someone else who does have access to fix X2Engine on your behalf.
* '''The exact error message given by the updater in its entirety.''' It explains what went wrong.
* '''The updater package for the version you attempted updating/upgrading from.''' This contains not just the important data but also flat data files that should prove helpful in diagnosing and fixing the problems. See "[[#Obtaining_the_Update_Package|Obtaining the Update Package]]."

== If The Update Failed After Applying Database Changes ==
If this happened, the update is almost complete, and it is less effort to simply perform the final steps manually than trying to recover/reset the installation and start over. You will know if this is the case when it is explicitly indicated by an updater error message that begins with

<blockquote style="color:red">Encountered an issue after applying database changes.</blockquote>

You can, in nearly all such cases, complete the update by performing the final steps of a manual update from [[#Copying_new_files|copying the new files]] through [[#Clearing_caches_and_refreshing_the_application|cleaning up]]. Note, however, that if the error indicates that it failed to modify the configuration, i.e.

<blockquote style="color:red">Failed to set version info in the configuration.</blockquote>

then the task at hand is even easier. All that would required in that case is updating the configuration and cleaning up, because at this stage of the update all the necessary changes to the local filesystem have already been enacted.

== Using Backups ==
If a backup copy of the database is available, and the update failed in the middle of database changes, restoring the database to the backup can prove to be the easiest way to reset the database to a known state and saving effort in the recovery process. Doing so is recommended unless your database is exceedingly large (i.e. several hundred megabytes or more), in which case the restore operation will take a long time and possibly cause more damage if done improperly.

=== Backup Validity and Applicability ===
Note that, when making a backup copy of the database, whether using the button in the updater's web interface or some third-party tool, that ''the backup represents the exact state of the database when it is created.'' Furthermore, if the backup-database button is used after attempting to update unsuccessfully, that will overwrite the old backup. Thus, it should go without saying: '''DO NOT back up again if your first attempt failed.''' You should back up your files and database '''before you attempt to update,''' and only then; nothing after that is useful. After the first attempt, any backup made will reflect the broken/intermediate state, in which case it does no good and only returns you to the broken state when you use it.

=== Restoring a SQL Backup Manually ===
Database backup copies, especially those made with MySQLDump and the built-in database backup utility of X2Engine, retain both the schema and content of the database. They can be run as SQL scripts to completely restore the database to its previous state. How exactly to do this depends entirely on the end user's preferred method and thus is not covered here (there are many possible ways).

If using a backup copy that is in the form of a SQL script, it is vitally important to first drop all tables in the target database that were not created in the backup script. This is important because the restore script will not drop any tables in the current database that aren't in the backup (which need to be dropped before re-creating them in the backed-up state). This will include any tables created since the time that the backup was made. The reasoning behind this is that if the error is "''Base table or view already exists''," restoring in itself will not help, because the offending table will still remain in the database after restoring. Note, the auto-restore operation in the updater takes care of this automatically.

== Step 1: Examine the Files ==
The first appropriate step is to look at the modification times of the files that were supposed to be updated or added in the update. Lists of such files, one per line, are in the files stored in <tt>data/fileList</tt> within the update package. Pick one of them and see if it was changed today. Compare, i.e. using <tt>diff</tt>, the files in the update package versus the files in the installation.

=== Bulk Comparison of Files ===
''To compare all files in one command:'' assuming you are in a Unix/Linux shell session (i.e. bash) on the web server, and you are in the base directory of X2Engine, and the updater package has been unpacked into the "update" directory, run

diff -rq update/source/ ./

=== Get a List of Migration Scripts ===
Migration scripts perform ancillary data transformation after a version's worth of updates that cannot be performed using pure SQL. They are PHP source files, and can be found in the directory <tt>source/protected/migrations</tt> within the unzipped update package. If any migration scripts are present, this will impact how one must proceed, if finishing the update manually rather than restoring the database to the backup copy and modifying the database for update compatibility.

== Step 2: Examine the Database ==
If any of the files differ and have not been updated, this indicates that the update halted in the middle of database changes, and thus, you will need to determine the state that it is in. On the other hand, if all of the files are identical to the copies in the update package, the chances are good that all of the database ''and'' file changes have already been applied, and all that remains to be done is [[#Editing_the_Configuration_File|update the configuration]] with the new version. However, checking that the database is in the expected state is still recommended in this case.

What will essentially be accomplished in this step is choosing the best possible option for actions to take in manually altering the database.

=== Read the Update Error Output ===
In many cases, the error output from the updater will tell you exactly what went wrong in the update. If it is a simple problem, i.e. table/column already exists, and you are mostly certain that this is the only compatibility issue, you can skip a full database comparison and opt rather to try removing any incompatibilities in the database first before attempting to update a second time.

=== Compile The Full Update SQL ===
To make subsequent tasks easier, one can compile the full list of SQL statements into one file. First, however, it is necessary to compile the chronologically-ordered list of versions. This is important because, while one can iterate over files in data/sqlList, the ordering of files may not result in a listing that accurately reflects the order in which the versions were released.

So, to get the list of files, look for the "versions" property of the json object stored in <tt>update/manifest.json</tt>, or run the following command to extract it into a file "versionList.txt":

php -r '$m = json_decode(file_get_contents("update/manifest.json"),1); echo implode("\n",$m["versions"]);' > versionList.txt

Now, with the list of files in <tt>versionList.txt</tt>:

for v in `cat versionList.txt`; do echo "/* VERSION $v */"; cat update/data/sqlList/$v.sql; done > update.sql

The file <tt>update.sql</tt> will now contain a list of all SQL commands, in chronological order, that are part of the update.

=== Perform a Binary Search for the Current State ===
This may only be necessary in cases where the database changes were cut short, i.e. a server timeout in the web updater. In this process, one determines which changes have been applied in the update and which have not. It will reveal what if any action is necessary to "repair" the database.

For those unfamiliar with the term, a binary search works as follows:
# Start with an "upper" and "lower" limit item in the ordered list being searched.
# Pick an item in the middle of the list, between the upper and lower limits.
# If the item is before the item we want, change the lower limit to that item. Otherwise, change the upper limit to that item.
# Repeat steps 1-3 until the desired point in the list is found.

In our case, the ordered list is the full list of SQL to be run in the update, and the desired item is the first database change that didn't get applied. That leaves the binary condition, which is ''choose the lower bound if the change appears to have already been applied, and choose the upper bound if it hasn't been applied.''

To begin, open the .sql file created in the previous part of this step, and:
# Find the first and last SQL statements.
# Look in the database schema (and, if necessary, data) for those changes, i.e. the presence of those columns/records. Note:
#* ''If neither of them have been applied:'' the problem to be fixed is not an incomplete update; it is an incompatible schema, in which case the best option is removing the incompatibilities.
#* ''If both of them have been applied:'' the issue is that the database is already up-to-date and at the latter version, and so no other action need be taken.

Finding out if a given change has been applied requires basic knowledge of MySQL; for instance, given an <tt>INSERT</tt> command in the update, one will need to know how to compose an appropriate <tt>SELECT</tt> statement (or know which buttons to press) to search for and find the records that would be inserted by it.

== Step 3: Determining the Appropriate Course of Action ==

=== If The Database Is Already Up To Date ===
If this is the case, and you have determined that the database changes have all been applied, then all that remains to be done are the final steps in [[#Performing_Updates_Manually|manually updating]]. Those steps include everything from [[#Copying_new_files|copying the new files]] through [[#Clearing_caches_and_refreshing_the_application|the final clean-up process]], and they are all the easier steps in the process.

=== If The Schema Includes a Known Incompatibility ===
In this scenario, you have a feature which you know that you added, but it somehow conflicts with a database change to be applied. The way to recover from or get around this this could range from very simple to very complex. For the simpler case, i.e. a column name conflict, you can get around this by renaming the column to something else temporarily, and then copying the data into the newly-created column as desired after the update.

=== If The Schema/Data Contains an Unknown Incompatibility ===
If the database is incompatible vis-a-vis the updater error messages, and you have no idea why the offending database feature is there (i.e. primary key conflict, table, column, etc), try removing the feature from the database and re-attempting the update. This may have to include anything from dropping tables to deleting records; again, this requires knowledge of MySQL.

=== If The Update Is In a State Between Versions ===
In this scenario, there are two options worth considering. First, you could try manually applying each subsequent database change and running accompanying migration scripts for each version. In other words, pick up where the database changes left off, as though in the middle of a [[#Performing_Updates_Manually|manual update]].

If there are a very large number of database changes between the state of the database and the final change, one might consider reverting the changes instead, i.e. remove columns that get added. Note, however, that migration scripts cannot be applied in reverse, and so this task may be far less simple if any migration scripts have been run already at the stage that the database is currently in.

In either case, if a working/compatible and sufficiently up-to-date database backup has been made ''before the update attempt'' and is available, one should try to use that and re-attempt the update first, provided that it does not take too long to restore the database.

= Troubleshooting =

== User interface (UI) "bugs" after the update ==
It is extremely common (and easily remedied) that after an important update, certain features of the user interface of X2Engine may not work properly. This is caused, in nearly all cases, by the web browser's cache, which contains out-of-date copies of X2Engine's essential user interface files. To solve these problems, the first step to try is clearing the cache. A step-by-step guide to doing so is given in [[wikihow:Clear-Your-Browser%27s-Cache]].

== Errors in the updater itself ==
When all else fails, the updater may have to be patched due to an irreconcilable backwards compatibility issue. Fortunately, if one has read/write access to the source files on the webserver, this is straightforward to fix. See [[#Refreshing_and_Updating_the_Updater_Utility|Refreshing and Updating the Updater Utility]].

== Professional Edition not in effect after upgrading ==
This may be caused by Professional Edition not getting "switched on" properly, despite all the necessary filesystem and database changes already being in effect. First, to see if this scenario applies to you, look for a folder "<tt>reports</tt>" inside <tt>protected/modules</tt>, and a table <tt>x2_reports</tt> in the X2Engine database. If you find these things, you can try the following to enable Professional Edition:
# Find the file <tt>constants.php</tt> in the installation directory. Open it in a text editor, and look for the following line: <syntaxhighlight lang="php">defined('PRO_VERSION') or define('PRO_VERSION',false);</syntaxhighlight>
# Change <tt>false</tt> to <tt>true</tt> on that line, and save the file.
# Run the following SQL command (replacing <tt>{license key}</tt> with your X2Engine license key) on the X2Engine database: <syntaxhighlight lang="mysql">UPDATE `x2_admin` SET `unique_id`='{license key}',`edition`='pro' WHERE `id`=1;</syntaxhighlight>

== General Procedures to Try ==
It may sometimes be possible that the update did not finish cleanly. In such cases, it will be necessary to manually re-perform some of the final operations in the update, described in [[#Introduction|Introduction]].

=== Refresh the Source Code ===
This step is not really the best step to try first, as it is usually more time-consuming. It entails re-uploading the entire application, in order to reset all non-ephemeral (source code) files to what they should be in a fresh installation of X2Engine. To do this:
# Download the refresh package. There should be a download link for this in the ''Updater Settings'' page. Otherwise, if that doesn't work and you're using Open Source edition, use [https://x2planet.com/installs/refresh.zip this link], or if using Professional Edition, paste the following url (after replacing {key} with your license key) into your browser's address bar: <pre>https://x2planet.com/installs/{key}/refresh-pro.zip</pre>
# Upload the ''contents'' of the downloaded zip archive to the installation directory, overwriting existing files.

=== Clear Caches ===
See "[[#Clearing_caches_and_refreshing_the_application|Clearing Caches...]]" for details.

=== Regenerate the Configuration ===
Again, this should not be done unless you are completely certain that all the files (not counting customizations) and the structure of the database are equivalent to a new installation at the same version as the one you updated to. Refer to [[#Editing_the_Configuration_File|Editing the Configuration File]].