Introduction

This aims to be a generic all-purpose guide for preparing a Linux system for running X2CRM, which applies both to physical servers and virtual servers, i.e. Amazon EC2 instances. It will cover two main families of Linux distributions: RHEL-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. It will be assumed in this guide, unless otherwise noted, that command line operations are being performed as the root user.

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.

On Debian-based systems, the command is:

apt-cache search <package name> # (Debian-like)
yum search <package name> # (RHEL-like)

In each case, use parts of the full name to increase the likelihood of getting search results. Note that Debian's apt-cache search utility will accept regular expressions (if quoted properly). To search for packages on RHEL-based systems with regular expressions, search results from yum can be simply piped to grep:

yum search <package name> | grep <package regex>

Installing the Base Stack

To begin, refresh the software package database:

apt-get update # (Debian-like)
yum update # (RHEL-like)

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:

tasksel lamp-server

However, this task usually does not include the package for the PHP cURL extension, so it must be installed separately via apt-get install php5-curl

On RHEL-based systems:

yum install install mysql php-mysql php httpd php-mbstring php-curl

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 phpinfo() ). 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 php-process or php-posix (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 apt-get install php5-suhosin php-apc. In CentOS, they can be acquired by enabling the EPEL software repository and then running yum install php-suhosin php-pecl-apc.

To start the server, run:

service apache2 start # (Debian-like)
service httpd start # (RHEL-like)

Navigate to the web server's FQDN[[wikipedia:Fully qualified domain name]]: a domain name that specifies its exact location in the tree hierarchy of the Domain Name System (DNS). or IP address to verify that the web server is running.

Preparing the Environment

The default DocumentRoot of Apache Webserver on most distributions of Linux will be owned by the root user immediately after installation, whereas its default User and Group will be set to "www-data" (Debian) or "apache" (RHEL). Thus, no web application whatsoever will have write permissions to the directory it runs in (which is problematic). Thus, the first step 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:

grep -r '^ DocumentRoot' /etc/apache2/ # (Debian-like)
grep -r '^ DocumentRoot' /etc/httpd/ # (RHEL-like)

In most cases, the directive will be set to /var/www on Debian-based distributions and /var/www/html 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:

grep -r '^ *\(User\|Group\)' /etc/apache2/ # (Debian-like)
grep -r '^ *\(User\|Group\)' /etc/httpd/ # (RHEL-like)

Note that on Debian-based systems you may see that, in place of literal strings, there are references to environment variables, i.e. ${APACHE_RUN_USER}. To find their actual values, search for them in the same manner:

grep -r '^ *export *APACHE_RUN_' /etc/apache2/

Using ps

One can search for the process and see its user, if Apache is already running, using ps:

ps aux | grep '\(apache|httpd\)'

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 /usr/sbin/apache2 or /usr/sbin/httpd).

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 DocumentRoot with the following contents and opening it in a web browser:

<?php 
echo 'UID (Server): '.posix_geteuid().'<br>';
echo 'UID (Directory owner): '.fileowner(realpath(dirname(__FILE__)));
?>

If the web server is properly set up, both of those numbers 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:

chown -R <user>:<group> <DocumentRoot> # (Debian-like)
chown -R <user>:<group> <DocumentRoot> # (RHEL-like)

Use the user name or ID of the running webserver process in place of <user> and <group>, and the server's DocumentRoot in place of <DocumentRoot>.

Enabling Login as the Webserver User

To greatly ease the process of installing and maintaining X2CRM, the default Apache web user (assumed www-data in the Debian family and apache in the RHEL family) can also be used for logging into the server. However, the ability to log in as that user will in many cases be disabled for security purposes (mostly due to how the usernames are easy to guess in brute-force remote login attempts). Regardless, this issue can be circumvented 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 (using asymmetric key pairs instead). If your server is an Amazon Linux EC2 instance, this will typically be the case already.

(Work in progress)