This article is for Neos 2.0 and thing migt 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.
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 (
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+
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:
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.
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.
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:
If there’s already a “Directory” section available, replace it with the lines above.
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!
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:
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.
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.
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! 🙂