Setup a working Neos CMS environment

This article is for Neos 2.0 and thing might have changed in the meantime. At least the software packages are required in newer versions. Neos is well known for its well designed interface for editors who quickly fall in love with the system. On the other hand, it's also infamous for being hard t...

This article is for Neos 2.0 and thing might have changed in the meantime. At least the software packages are required in newer versions.

Neos is well known for its well designed interface for editors who quickly fall in love with the system. On the other hand, it's also infamous for being hard to set up by starters due to its high demands towards the hosting environment. Someone also compared it to walking on a slack line: It's easy to stumble and to get frustrated.

Neos error page

This article focuses on creating a hosting environment suited for Neos so you will be able to finish the Neos setup and get a running instance afterwards. I'm using Ubuntu 14.04 as reference but it also applies to other Linux distributions like Fedora, only the path names might differ a bit (/etc/apache2/ vs. /etc/httpd/).

Required software

At first, you need to make sure that the required software is installed. Apache, MySQL and PHP might be obvious but that's not enough. Especially the additional Apache and PHP modules are important to get it running at all. You will have a good start with these packages:

- Apache 2.2+

- MySQL 5.1+

- PHP 5.3.2+

mbstring

- tokenizer

- pdo_mysql

Even if the minimum requirement for PHP is version 5.3.2, it's better to use newer versions for performance reasons. Also, the requirements for Neos will be PHP 5.5+ for Neos 2.0.

You can install the required packages via the package manager of your distribution (apt-get for Ubuntu/Debian, rpm for Fedora/SuSE):

sudo apt-get install apache2 mysql-server libapache2-mod-php5 php5 php5-mysql

To check if all required PHP extensions are available, the easiest way is to place a short PHP file named info.php in your Apache document root directory (usually /var/www/) containing this content:

<?php phpinfo();

If you open http://localhost/info.php in your browser, the output will contain the environment, the configuration settings and the installed modules available in your installation. Search for the strings "mbstring", "tokenizer" and "pdo_mysql". There should be sections with this names in the rendered page.

Apache configuration

Most often, the first problems occur due to an insufficient Apache configuration. Neos uses .htaccess files and needs some modules that are not activated by default all the times. The "mod_rewrite" and "mod_env" modules are the best examples for this. To enable them in your Apache configuration, you need to execute these commands on the command line:

sudo a2enmod rewrite
sudo a2enmod env

If you got the message that one or both modules had been already enabled then this was set up correctly before.

The VHost configuration is another common source of problems and you have to adapt it for sure. The default configuration is located in /etc/apache2/sites-enabled/000-default.conf (in Fedora or other Linux distributions the files might be located somewhere else). In this file, change the DocumentRoot to the Neos ./Web/ directory, e.g.

DocumentRoot /var/www/Neos/Web

Furthermore, you need to add a "Directory" directive below the "DocumentRoot" line to allow the Neos .htaccess file to add rewrite rules and some settings:

AllowOverride All

If there's already a "Directory" section available, replace it with the lines above.

Warning: Keep care that the named directory in the "Directory" directive is exactly the same as in the "DocumentRoot" AND contains a trailing slash (/).

The last task is to restart Apache:

sudo service apache2 restart

Now you should be at able to open at least http://localhost/setup in your browser but beware: http://localhost/index.php/setup still won't work!

PHP configuration

There are various PHP settings that can cause your Neos installation to fail. First of all you should have a look into the output of the info.php file again and check if one of the required PHP functions is disabled. This is often the case for security reasons in shared hosting environments and this leads to errors afterwards. Especially check the disable_functions line in the core section for:

- system

- shell_exec

- escapeshellcmd

- escapeshellarg

If non of these function is listed there, then you are on the safe side.

The next problems are lurking in your PHP configuration but that can be fixed either by adding a few lines to your /etc/php5/apache2/php.ini or to the .htaccess file in the Neos ./Web/ directory. When using the php.ini file you should add these lines at the end of the file:

memory_limit = 256M
magic_quotes_gpc = off # only for PHP 5.3 to be sure
date.timezone = Europe/Berlin # or any other valid timezone
xdebug.max_nesting_level = 500 # only if XDebug extension is installed

In case you are allowed to overwrite settings also via the .htaccess file, you can add these lines to the ./Web/.htaccess of your Neos installation:

php_value memory_limit = 256M
php_flag magic_quotes_gpc off # only for PHP 5.3 to be sure
php_value date.timezone Europe/Berlin # or any other valid timezone
php_value xdebug.max_nesting_level 500 # only if XDebug extension is installed

Neos can be very memory consuming so even the standard memory limit of 128MB can be to low. Errors due to an insufficient memory limit are written to the Apache error log file (usually in /var/log/apache2/error.log) so it's a good idea to keep an eye on the content of that file.

The magic_quotes_gpc directive has been removed in PHP 5.4 and was already deprecated before. To disable it for PHP 5.3 is only a safety measure for installations that have been constantly updated during the last years.

For the timezone value you can use any valid timezone if it fits better for your location. A list of valid timezones is available at the PHP web site.

When you've installed the PHP XDebug extension you might run into error messages like Maximum function nesting level of '...' reached. Only in this case you need to increase the XDebug nesting level for functions.

Done!

Finally, you should be able to open the Neos setup page in your browser, that is available at http://localhost/setup. The rest of the installation is usually a non-brainer due to the nice setup routine provided by the Neos installer.

Afterwards you can enjoy Neos. Happy editing! :-)