Docker Setup using DDEV and Docker (all Platforms)

For Windows, Mac OS and Linux, using ddev can be a good way to move to a dockerized setup.

Written by
Kay Strobach

What is ddev?

Ddev provides an easy to use and fast to setup development environment, based on docker and docker-compose.

Not yet tested on Windows

We did not get around yet to test these instructions on Windows. We try to do so as soon as possible; but if you want to help out, check the bottom of the page on how we can be reached. Any help is appreciated :-).

Step by Step Instructions

1. Install ddev

Please follow the getting started guide to install drud/ddev.

To use ddev together with Neos or Flow you need to configure ddev first:

ddev config

Normally, you would now start up ddev and test your application. Sadly this will result in slow execution times (esp. on Mac and Windows) as Flow does some very resource intensive tasks involving lots of file IO. This includes scanning all the files and building various caches.

This tutorial describes how to put some parts of these caches inside the docker containers created by ddev, so that the execution times are very acceptable.

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.

Start from Scratch:

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

mkdir neos-example
ddev config
  • Give the project a name
  • as Docroot Location, enter Web. Choose to auto-create it.
  • as Project Type, choose php.

Now, create the project structure with the following command:

ddev composer create neos/neos-base-distribution

Confirm that any existing contents in the project root will be removed, and grab a cup of tea while all the dependencies will be downloaded.

Now, it's the right time to create a new Git repository for your project and add everything to it.

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

Check out an existing project:

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

git clone http://YOUR-PROJECT-URL-HERE your-project
cd your-project
ddev config
  • Give the project a name
  • as Docroot Location, enter Web. Choose to auto-create it.
  • as Project Type, choose php.

Now, run composer by running the following command:

ddev composer install

3. Adjust some ddev settings for performance

The following environment variables speed up Neos and configure it correctly - storing temporary files inside the container.

version: '3.6'

      - FLOW_CONTEXT=Development/Ddev

On Mac OS, you can enable webcache for a way better performance at runtime, trading in a slower initial startup time (this is sadly not supported on Windows yet, but will be soon). For this, open .ddev/config.yaml and switch webcache_enabled to true:

# only on Mac OS, not supported on Windows yet!
webcache_enabled: true

Webcache is still considered experimental

Webcache is still considered experimental as there are a few bugs in this area. Future versions of ddev might switch to an NFS-based approach.

4. Start ddev

It's time to start ddev. After the command has run through, you can open your website for the first time. It may take some time to load for the first hit as Neos needs to fill all the caches and the webcache (if enabled) needs to sync all files.

ddev start

# if you use the web cache feature from above, use the following command
# to check whether the initial file sync has completed - look for a line
# starting with:
# "Synchronization complete at ..."
ddev logs -s bgsync -f

# now, you are ready to access your web site :-)

Now, you are ready to access the Neos instance in your browser and you will be redirected to the setup tool on the first run.

5. Go through the setup tool

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

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

How to fine tune the setup?

Improving performance by freezing packages

Do not forget to use the freeze command shipped with flow to gain even more speed.

# freeze all packages
./flow package:freeze

# unfreeze every single package you are working on
./flow package:unfreeze <PackageName>

Connecting to the container

Please use the following command to open an ssh connection to the container:

ddev ssh

Using custom settings only for ddev

When running the install tool, settings are written to the global Configuration/Settings.yaml of your project. However, Neos supports so-called Contexts, which helps to separate different sets of settings for different environments. The instructions above set up Neos to run in context Development/Ddev, so you can place a settings file like in Configuration/Development/Ddev/Settings.yaml, that only applies in the DDEV Development context:

    driver: Imagick
        driver: pdo_mysql
        dbname: db
        user: db
        password: db
        host: db

    # The following is necessary to allow ddev to act as a proxy on your local machine
        proxies: "*"

Using xdebug

If you want to use xdebug, you can enable and disable it easily with the following two commands:

ddev exec enable_xdebug
ddev exec disable_xdebug 

Using post start commands

You can set start up hooks in ddev to speed up the first run and avoid any problems or solve them easier .ddev/config.yaml:

  - exec: composer install
  - exec: ./flow neos.flow:package:rescan
  - exec: ./flow database:setcharset
  - exec: ./flow doctrine:migrate

Working with older Neos/Flow versions

If you are using Flow 5.x, you are fine with the defaults for the PHP project type. If you are using Flow 4.x or lower you may need to adjust the PHP version in .ddev/config.yaml to 7.1 or 7.0 - use the one your hosting provider supports!

Written by