How To Install MODX on a VPS Running Ubuntu 12.04

Status: Deprecated

This article covers a version of Ubuntu that is no longer supported. If you are currently operate a server running Ubuntu 12.04, we highly recommend upgrading or migrating to a supported version of Ubuntu:

• Upgrade to Ubuntu 14.04.
• Upgrade from Ubuntu 14.04 to Ubuntu 16.04
• Migrate the server data to a supported version

Reason: Ubuntu 12.04 reached end of life (EOL) on April 28, 2017 and no longer receives security patches or updates. This guide is no longer maintained.

See Instead:
This guide might still be useful as a reference, but may not work on other Ubuntu releases. If available, we strongly recommend using a guide written for the version of Ubuntu you are using. You can use the search functionality at the top of the page to find a more recent version.

MODX is an open source Content Application Platform that allows you to build sites of any size, managed with ease from the backend administration. It has a very flexible templating system which is ideal for designers and a robust OOP API for developers who wish to extend its functionality.

In this tutorial we will see how to install MODX on a VPS running Ubuntu 12.04 with the LAMP stack (Linux, Apache, MySQL and PHP) installed. Therefore it assumes you have this covered as a basis to start from. If you need help setting up LAMP, check out this tutorial first.

Although we are going with LAMP for this tutorial, MODX can also be installed on other operating systems (such as Windows or Mac OSX) and webservers (such as Lighttpd, IIS or Nginx). It does however require PHP older than 5.1.2 with a number of extensions that we will install in the course of this tutorial and MySQL older than 4.1.20 (excluding 5.1.51).

Download

First thing we need to do is download a copy of the application .zip file onto our VPS. To get it, go to http://modx.com/download/ and click on the Traditional link of the Standard Distribution. This should download the archive to your computer, so go ahead and stop the download. The page that opened however contains a link you can copy so we can download it straight onto our VPS (with the wget command). Copy that link and navigate to your VPS root directory (for Apache it’s /var/www):

cd /var/www

Now, run the following command to download the zip file:

wget http://modx.com/download/direct/modx-2.2.9-pl.zip

Make sure you replace the link with the one you found of the release. This should download a zip file that needs to be unzipped with the following command:

unzip modx-2.2.9-pl.zip

Again make sure you replace the name of the archive with the one you downloaded. If you run into an error and you don’t have zip installed, you can quickly install it with the following command:

sudo apt-get install unzip

Then you can try again to unzip the file. Now you have a folder with all the MODX files inside that you should rename to something more suitable for you, for instance modx:

mv modx-2.2.9-pl modx

Requirements

In order for your MODX site to run normally on your VPS, you’ll need to take care of a couple of things (if your system is not already set up like this). First, you need to make sure the PHP memory limit is higher than 24 MB. To change this, edit the php.ini file:

nano /etc/php5/apache2/php.ini

And edit the following line:

memory_limit = ??M

If the question marks you have over 24 MB, you are good to go. Next, but in the same file, you’ll need to make sure that the register_globals, magic_quotes_gpc and safe_mode directives are off. Now you can save and exit the file. If you made any changes, don’t forget to restart Apache for the changes to take effect:

sudo service apache2 restart

Next, you also need to install a couple of PHP extensions if you don’t already have them:

sudo apt-get update
sudo apt-get install php5-gd
sudo apt-get install imagemagick --fix-missing

Finally, you’ll need to have the mod_rewrite module enabled in your Apache. To check if it's already enabled, use the following command:

apache2ctl -M

If you see "rewrite_module" in the list, you are fine. If not, use the following command to enable the module:

a2enmod rewrite

Then edit the Apache default virtual host file and make sure that Allow Overrides is set to All under the /var/www directory. Edit the file with the following command:

nano /etc/apache2/sites-available/default

And where you see this block, make the changes to correspond to the following:

		Options Indexes FollowSymLinks MultiViews
		AllowOverride All
		Order allow,deny
		allow from all

This will make sure that .htaccess files can override the default Apache instructions.

In order for any of these two changes to take effect, you’ll need to restart your Apache server:

sudo service apache2 restart

Installer

Before running the installer, we need to make a couple of folders writable by the web server.

Change into the MODX directory.

cd modx/

So let’s first change their ownership to the root user and www-data group (which includes the www-data user - the Apache web server):

chown -R root:www-data core/cache
chown -R root:www-data core/config
chown -R root:www-data core/export
chown -R root:www-data core/packages

And now change the permissions so that the group users can also write in these folders:

chmod -R 775 core/cache
chmod -R 775 core/config
chmod -R 775 core/export
chmod -R 775 core/packages

Now, let’s create an empty database for MODX to use. In your MySQL terminal, you can run this command to create a db named modx:

create database modx;

And you can exit the MySQL terminal.

Now we can go ahead and run the installer by pointing the browser to www.example.com/modx/setup. If you get an error about the PHP date.timezone, you’ll have to edit the php.ini file again and set a timezone:

nano /etc/php5/apache2/php.ini

And in this file where you see the following line:

;date.timezone =

Remove the preceding semi-colon and set a PHP type timezone in the following format:

date.timezone = US/Central

Save the file, exit and restart Apache for the change to take effect:

sudo service apache2 restart

Then you can try again the setup link and you should get prompted with the language choice for the new site. Proceed with the installer wizard and follow the instructions on the screen. Choose New installation and proceed with the defaults. Then fill in the database connection information (specifying the database we just created of course). You should then test the connection right there on the page. Below, choose a collation and click on Create or test selection of your database. This should open up a new section for creating an administrator account so make sure you fill that in too, and click Next.

Thus should lead you to an installation summary page where if the installer has any problems you will be notified. Make sure you correct anything mentioned there and then continue by clicking Install. This should install the application and lead you to a page where it’s recommended to check the box Check this to DELETE the setup directory from the filesystem before logging in to your new site. It serves as a security precaution. And you are now done.

To access the site's home page you have to go directly to its folder in the browser (www.example.com/modx) as that's where it resides (don't worry if you get a black page, it's just because you have no content yet). But what if you want the site to be available at your domain name which is set to point to your web server's root folder (/var/www)? You have three choices, One: you can move all the MODX related files to this folder; Two: you can change the webserver's root directory to point to the /var/www/modx folder instead of the default one; or Three: you can create a new virtual host for the domain name with that directory as its document root. The choice depends on your setup.

If you want to create a virtual host for the domain name, follow the instructions in this tutorial. But if you want to quickly change the default web server document root, open up again the file you edited before to allow the .htaccess overrides:

nano /etc/apache2/sites-available/default

And change this line from this:

DocumentRoot /var/www/

To this:

DocumentRoot /var/www/modx/

This is assuming that your MODX site is in the modx folder.

Now you should be able to access your MODX site straight from your domain name that is set to use your VPS' default virtual host.

Good luck building your new site with MODX.