Manual Neos Setup on a web server 

#1. Install composer

Composer is the PHP dependency manager, similar to NPM for Node.js, or Maven for Java. If you do not have it installed yet, you need to install it now because it is the way to install Neos then.

curl -sS | php
mv composer.phar /usr/local/bin/composer

You may check your composer's version by typing “composer -V” ...

Please consult the offical documentation on how to install Composer on Windows.

#2. Check out the project (or start from scratch) 

Now, this part is different depending on whether you want to start from scratch, or you have an existing project you want to work on.

cd /your/htdocs/

Start from Scratch:

To create a new project, use the following commands, which will create the base directory structure and download all dependencies.

# with native Composer:
composer create-project neos/neos-base-distribution neos-example

# ALTERNATIVE, with Composer through Docker:
docker run -v .:/app -it --rm composer create-project neos/neos-base-distribution neos-example

We furthermore strongly recommend to directly create a new Git repository for making the installation reproducible:

cd neos-example
git init
git add .
git commit -m "TASK: Initial Commit"
# optionally, also run "git remote add ..." and "git push"

Start with a good boilerplate:

The Neos-Skeleton provides an easy and powerful start for new projects - beginner-friendly and highly scalable. It is frontend tooling agnostic.

On top, it adds well-tested community packages to provide everything you need for an amazing website.


  • A powerful best practice layout rendering mechanism
  • Best practice folder and naming structure
  • A well-rounded set of packages to build typical websites

-> Steps to get started

Check out an existing project:

To check out an existing project, simply clone it and run composer install to install all dependencies.

git clone http://YOUR-PROJECT-URL-HERE your-project
cd your-project

# with native Composer:
composer install

# ALTERNATIVE, with Composer through Docker:
docker run -v .:/app -it --rm composer install

#3. Virtual domain/host

Next set up a virtual domain/host in your webserver configuration

Set up a virtual host inside your Apache configuration. Set the DocumentRoot to the Web directory inside the Neos installation. Set the directive AllowOverride to ALL to allow access to .htaccess

Apache Configuration
NameVirtualHost *:80 # if needed

<VirtualHost *:80>
  DocumentRoot "/your/htdocs/Neos/Web/"
  # enable the following line for production context
  #SetEnv FLOW_CONTEXT Production
  ServerName neos.demo

<Directory /your/htdocs/Neos/Web>
  AllowOverride All

Make sure that the mod_rewrite module is loaded and restart apache. For further information on how to set up a virtual host with apache please refer to the Apache Virtual Host documentation.

Set up a server block inside your NginX configuration. Set the root to the Web directory inside the Neos installation.

NginX Configuration

server {
  listen [::]:80;
  listen 80;

  root   /your/htdocs/Neos/Web/;
  index index.php;
  location ~ /_Resources/ {
    access_log off;
    log_not_found off;
    expires max;

    if (!-f $request_filename) {
      rewrite "/_Resources/Persistent/([a-z0-9]{40})/.+\.(.+)" /_Resources/Persistent/$1.$2 break;
      rewrite "/_Resources/Persistent(?>/[a-z0-9]{5}){8}/([a-f0-9]{40})/.+\.(.+)" /_Resources/Persistent/$1.$2 break;

  location / {
    try_files $uri $uri/ /index.php?$args;

  # Pass the PHP scripts to FastCGI server listening on
  location ~ \.php$ {
    include        /usr/local/etc/nginx/fastcgi_params;
    try_files      $uri =404;
    fastcgi_pass   unix:/var/run/php-fpm/php-fpm.socket;
    fastcgi_index  index.php;
    fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param  PATH_INFO         $fastcgi_path_info;
    fastcgi_param  FLOW_REWRITEURLS  1;
    fastcgi_param  FLOW_CONTEXT      Development;
    fastcgi_param  X-Forwarded-For   $proxy_add_x_forwarded_for;
    fastcgi_param  X-Forwarded-Port  $proxy_port;
    fastcgi_param  REMOTE_ADDR       $remote_addr;
    fastcgi_param  REMOTE_PORT       $remote_port;
    fastcgi_param  SERVER_ADDR       $server_addr;
    fastcgi_param  SERVER_NAME       $http_host;
    fastcgi_split_path_info ^(.+\.php)(.*)$;
    fastcgi_read_timeout         300;
    fastcgi_buffer_size          128k;
    fastcgi_buffers              256 16k;
    fastcgi_busy_buffers_size    256k;
    fastcgi_temp_file_write_size 256k;

For further information on how to set up a virtual domain with nginx please refer to the nginx documentation.

Add an entry to /etc/hosts to make your virtual host reachable:

/etc/hosts	neos.demo

Make sure to use the same name you defined in ServerName in the virtual host configuration above.

#4. Set file permissions

Set file permissions as needed so that the installation is read- and writeable by the webserver’s user and group:

sudo ./flow core:setfilepermissions john www-data www-data

Replace john with your current username and www-data with the webserver’s user and group.

For detailed instructions on setting the needed permissions see Flow File Permissions.

Setting file permissions is not necessary and not possible on Windows machines. For Apache to be able to create symlinks, you need to use Windows Vista (or newer) and Apache needs to be started with Administrator privileges.

#5. Visit the setup

Now, go to http://neos.demo/setup in your browser, and you get redirected to the setup tool.