Clone and `bin/dev up`. Quickly start of developing locally with Nginx, PHP, Blackfire, Percona, Mailhog and Redis.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
build Make sure magento doesn't become the run code Dec 10, 2018
conf.d/mysql Added some useful options from issue #61 Jul 27, 2018
workspace Added .composer home directory for composer caching inside /workspace. Mar 31, 2017
.gitignore Updated .gitignore Jul 27, 2018
LICENSE Processed good suggestions for naming Sep 4, 2018
docker-compose-linux.yml Updated to version 3 of docker-compose Dec 10, 2018
docker-compose-osx.yml Updated to version 3 of docker-compose Dec 10, 2018
docker-sync.yml Updated to version 3 of docker-compose Dec 10, 2018 - Issues in progress

Docker Development stack

Docker-compose-development aims to be a plug 'n play setup for you to quickly start developing locally with services as NGINX, PHP, Blackfire, Percona, MailHog and more!

Also, it contains different configurations for use with Symfony, Silex, Magento 1 & 2, on PHP5 / PHP7 and with XDEBUG enabled.

We follow a Code of Conduct.

Table of Contents


Before continuing you must have the following installed and working correctly:

OSX users should also install:

  • Docker Sync and its dependencies

  • Coreutils using Homebrew brew install coreutils

  • Make sure that port 80/443 and 3306 are not being used by other services. sudo netstat -tupln|egrep '80|443|3306'

WSL users

# ssh-agent configuration
if [ -z "$(pgrep ssh-agent)" ]; then
    rm -rf /tmp/ssh-*
    eval $(ssh-agent -s) > /dev/null
    export SSH_AGENT_PID=$(pgrep ssh-agent)
    export SSH_AUTH_SOCK=$(find /tmp/ssh-* -name agent.*)

if [ "$(ssh-add -l)" == "The agent has no identities." ]; then

How to get started

Make sure that you have the prerequisites installed and running correctly before proceeding.

1). Configure your environment

  1. Clone this repository:
git clone development
  1. Run bin/dev setup This will automaticly create a root user with a random password and adds your user with restricted rights.
  • persistant MySQL on a location of your choice. If you were already using this repository before (or want a local directory), you can map the existing volume with:
mkdir -p mysql;
docker volume create -o 'type=none' -o 'device='${PWD}'/mysql' -o 'o=bind' dockerdev-mysql-volume

Or, if you are on OSX:

docker-sync start

A optional, but recommended, step to take is to add the provided .bin/dev command to your system so you can use its commands anywhere you like.

  1. Run ./bin/dev profile from the development folder.
  2. Copy the output into ~/.bashrc ~/.bash_aliases ~/.zshrc, on your own preference.
  3. Log out and log back in for this to take effect. You could also just source the new files in your current terminal . ~/.bashrc.

If succeeded you can now use dev <command> from anywhere. You can also just type cdw which will take you to your workspace directory.

2). Configure your hostnames...

There are several ways of configuring hostnames.

By using DNSMASQ (preferred)

Only applies if you have DNSMASQ installed, otherwiste continue to use the hostfile instead.

Create a file /etc/dnsmasq.d/dev.conf and copy the following as its content: address=/.localhost/

For Windows

Use Acrylic DNS Proxy. For more information check the website

Or by using the hostfile

Add a hostname entry for each of your projects manually to /etc/hosts, e.g.: mail.localhost test.project.localhost

You should now be able to browse to http://test.project.localhost/info.php and get a phpinfo() output.

3). Now, setup your projects!

Inside the development folder you will find a folder called workspace. The folders follow a certain structure, as described below: customer/project/htdocs


Docker for Windows automatically mounts to C:\workspace. You'll find your workspace there. To change this, update docker-compose-wsl.yml

You will notice that this has a 1-on-1 relation to the hostname provided in your hostfile: workspace/test/project/htdocs => https://test.project.localhost/

Other examples are:

  • workspace/iwant/coffee/htdocs =>
  • workspace/iwant/beer/htdocs =>
  • workspace/nomore/soup4you/htdocs => https://nomore.soup4you.localhost/

To be compatible with various projects, we have included the following definitions as webroots:

  • htdocs
  • httpdocs
  • public
  • pub
  • web
  • magento

You can read more about project webroots in the Hosts and File structure documentation.


Xdebug is enabled with support for remote debugging on your local machine. It will try to connect to the host by default. Make sure to add a file mapping in your IDE: ./workspace/customer/project => /data/customer/project

Update your existing installation

To update your existing installation, follow these steps:

  • go to the development directory
  • git pull origin master
  • bin/dev rebuild
  • bin/dev setup

But wait, there is more!