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.

#What is ddev?

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

DDEV on GithubOfficial WebsiteDocumentation

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

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 and developing is fun.

#1. Install ddev

ddev is a command line tool that has to be installed first.
Please follow the getting started guide to install drud/ddev that has instructions for all common operating systems.

After that running the command ddev on your shell should give you a description of all available ddev commands.

#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 yes to auto-create it.
as Project Type, choose php.

If you're going to adjust ddev settings as shown in the next section 3. Adjust ddev settings, do it now, before creating 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.

If you're going to adjust ddev settings as shown in the next section 3. Adjust ddev settings, do it now, before running composer with the following command:

ddev composer install

#3. Adjust ddev settings

The generated .ddev/config.yaml should be checked to ensure that a
recent version of php and mariadb is used by ddev that matches the Neos requirements.

php_version: "7.3"
mariadb_version: "10.4"

Learn more about the Neos System requirements

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

web_environment:
 - FLOW_CONTEXT=Development/Ddev
 - FLOW_PATH_TEMPORARY_BASE=/tmp/Flow
 - FLOW_REWRITEURLS=1

#4. Adjust Neos settings

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.

By putting the the following Configuration file into the path Configuration/Development/ddev/Settings.yaml the necessary configuration to run Neos with ddev is added:

Neos:
  Imagine:
    driver: Imagick
  Flow:
    persistence:
      backendOptions:
        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
    http:
      trustedProxies:
        proxies: "*"

  # The following is optional, but will redirect all mails directly to ddev's MailHog
  SwiftMailer:
    transport:
      type: 'Swift_SmtpTransport'
      options:
        host: 'localhost'
        port: 1025
        encryption: ~

Learn more about Neos Contexts

#5. Optimize performance for MacOS and Windows

On linux ddev/docker can use the host filesystem directly but on other systems filesystem operations in docker tend to be very slow.

That is the reason why you have to take special measures to avoid slow execution times 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.

The ddev documentation has a dedicated section about performance optimization that describes the necessary preparations for macOS and Windows to circumvent those problems.

Learn more about optimizing ddev performance

Ddev supports mutagen and nfs syncing of the filesystem with the web container. You can enable both by using a local config.override.yaml file. This way coworkers without the need to use NFS, f.e. those working on linux, do not need to change the config file of ddev.

# enable mutagen sync of the filesystem into the web container
mutagen_enabled: true

# enable mounting the filesystem via nfs to avoid docker io performance issues
nfs_mount_enabled: true

#6. 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

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.

#How to fine tune the setup?

#Connecting to the container

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

ddev ssh

#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

Xdebug usage is precisly described in the documentation of ddev.

#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:

hooks:
  post-start:
  - 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 Kay Strobach