Docker and Docker-Compose Setup

Native Docker is a good way to get started on all platforms.

Docker is a good lightweight way to put your application inside Containers. With docker-compose, you can very easily spin up a development environment containing Neos and a matching MySQL Database.

For development, we need to be able to change files inside the Neos application container. Thus, we mount the local directory inside the container.

On Windows and OSX, mounting a directory with loads of files (like a Neos / Flow distribution) is quite slow. That is why this approach copies all Neos files into the container and then we selectively only mount the directories which we modify.

Step by Step Instructions

1. Install composer and Docker

Composer is the PHP dependency manager, similar to NPM for Node.js, or Maven for Java.

You'll only need PHP locally to run Composer - so e.g. the built-in PHP of Mac OS is totally fine. If you do not have a php executable available in your system, install it (through homebrew, APT, RPM). Then, install Composer:

curl -sS | php

By issuing this command, Composer will get downloaded as composer.phar to your working directory. We suggest to have composer installed globally, so you can simply move it to a directory within your $PATH environment:

mv composer.phar /usr/local/bin/composer

Please also install Docker on your operating system.

As installing Composer on Windows is some more work (install PHP, install Composer), here, we're demonstrating how you can use Composer through Docker as well.

In case you already have composer installed...

... then it's easiest to just use it.
Simply run "composer create-project neos/neos-base-distribution" in your directory of choice, and continue with step 2.

First, please install Docker for Windows.

After installing Docker, instead of running composer, you run the following command:

# instead of running "composer [sub-command]", run the following command:
docker run -v %cd%:/app -it --rm composer [sub-command]

On the first run, a notification pops up asking you for access to the drive – you need to press Share it here.

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.

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 %cd%:/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"

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 %cd%:/app -it --rm composer install

3. Set up docker-compose

In your project, you need to create a and a docker-compose.yml with the contents below:

FROM php:7.2-cli

RUN apt-get update \
    # install GraphicsMagick
    && apt-get install -y \
        libgraphicsmagick1-dev graphicsmagick --no-install-recommends \
    && pecl -vvv install gmagick-beta && docker-php-ext-enable gmagick \
    # pdo_mysql
    && docker-php-ext-install pdo_mysql \
    # redis
    && pecl install redis && docker-php-ext-enable redis \
    # cleanup
    && apt-get clean && rm -rf /var/lib/apt/lists/*


# copy everything in the project into the container. This is what
# makes this image so fast!
COPY . /app

# start the dev server
CMD [ "./flow", "server:run", "--host", "" ]
# For instructions how to use docker-compose, see
version: '3.5'
  # Neos CMS
      context: .
      FLOW_CONTEXT: 'Development/Docker'
      - ./composer.json:/app/composer.json:cached
      - ./composer.lock:/app/composer.lock:cached
      - ./Configuration/:/app/Configuration/:cached
      - ./DistributionPackages/:/app/DistributionPackages/:cached
      # if you work on other packages, you need to add them here.
      - ./Packages/Sites/:/app/Packages/Sites/:cached
      - 8081:8081
  # DB
    image: mariadb:10.4
      - db:/var/lib/mysql
      - 13306:3306


4. Build and Run

Now, it's time to build and start the container:

The command docker-compose build is creating the container (by executing everything in, and adds all the Neos files into the container.

The command docker-compose up -d starts the container and mounts the folders specified in docker-compose.yml section services.neos.volumes.

docker-compose build
docker-compose up -d

After a few seconds, you can access your site at

5. Go through the setup tool

When you visit your Neos instance for the first time and get redirected to the Setup Tool, you need the generated setup password. You can find it by executing the following command:

docker-compose exec neos cat /app/Data/SetupPassword.txt

When visiting the setup tool, use the following database credentials:

  • host: db
  • user: root
  • password: db
  • database: db
Following Guide: Running the Setup Tool

Docker-Compose Cheat Sheet


# composer install

# docker-compose build

# docker-compose up -d

# docker-compose exec neos /bin/bash

# docker-compose stop

# docker-compose rm -sfv

# docker-compose exec neos cat /app/Data/SetupPassword.txt

Important ports

Starting Neos

# ensure that all source code in the container matches the local directory
docker-compose build
# actually start the container
docker-compose up -d

Stopping Neos

docker-compose stop

Removing all containers

Removes the database and all data!

The following command removes the MySQL database including its content and also the uploaded files from Neos.
So you might want to do a Site export or a database dump beforehand.
docker-compose rm -sfv

Viewing Neos Logs

docker-compose exec neos tail -f /app/Data/Logs/System_Development.log

Entering the Container

docker-compose exec neos /bin/bash

Running a Flow command

Replace help in the command below with the Flow command you want to execute.

docker-compose exec neos /app/flow help

Installing a new package through composer

Run your composer command as usual, then stop the container, build it and start it again again (as explained above).