Docker4Drupal is an open-source project (GitHub page) that provides pre-configured
docker-compose.yml
file with images to spin up local environment on Linux, Mac OS X and Windows. Create a Dockerfile with xdebug installation for the development, dont use this for production, it will slow down your performance. Build your-wordpress image from that Dockerfile. You might need to create the xdebug.ini file with your remote host details, i'm using phpstrom this is what my xdebug.ini looks like. Docker / PHP / XDebug / Mac (High Sierra) / Firewall / sloooooow After 2 weeks of slow(er) development on symfony/docker/mac I finally found my problem regarding the speed of my local application. We tweaked already the f.ck out of docker because the filesystem sync is.
Requirements¶
- Install Docker (Linux, Docker for Mac or Docker for Windows (10+ Pro))
- For Linux additionally install docker compose
Usage¶
Database data persistence
By default Docker will create a persistent volume for your DB data and unless you explicitly remove volumes the files will not be deleted. However, if you run
docker-compose down
(it's ok to use stop
though) these volumes will not be reattached when you run docker-compose up
. If you want to have your DB data all-time persistent and attached, we recommend using a bind mount. To use a bind mount uncomment to corresponding line under db server's volumes:
in your docker-compose.yml
and update the host path to your data directory.![Xdebug php docker Xdebug php docker](/uploads/1/2/9/2/129205052/571348947.jpg)
There are 2 options how to use docker4drupal – you can either run vanilla Drupal from the image or mount your own Drupal codebase:
Vanilla Drupal¶
- Clone docker4drupal repository and switch to the latest stable tag or download/unpack the source code from the latest release
- Optional: for Drupal 8 or 7 comment out corresponding
DRUPAL_TAG
andNGINX_VHOST_PRESET
in.env
file - From project root directory run
docker-compose up -d
ormake up
to start containers. Give it 10-20 seconds to initialize after the start - That's it! Proceed with Drupal installation at http://drupal.docker.localhost:8000. Default database user, password and database name are all
drupal
, database host ismariadb
- You can see status of your containers and their logs via portainer: http://portainer.drupal.docker.localhost:8000
Mount my codebase¶
- If you're starting a new project we recommend you to fork drupal-composer/drupal-project project
- Download and unpack
docker4drupal.tar.gz
from the latest stable release to your project root - Delete
docker-compose.override.yml
as it's used to deploy vanilla Drupal - Ensure
NGINX_SERVER_ROOT
(orAPACHE_DOCUMENT_ROOT
) is correct, by default set to/var/www/html/web
for composer-based projects where Drupal is inweb
subdirectory - Ensure database access settings in your
settings.php
corresponds to values in.env
file, e.g.: - Optional: for Drupal 8 or 7 update
NGINX_VHOST_PRESET
correspondingly in your.env
file - Optional: uncomment lines in the compose file to run redis, solr, varnish, etc
- Optional: import existing database
- Optional: macOS users please read this
- Optional: Windows users please read this
- Run containers:
make up
ordocker-compose up -d
- Your drupal website should be up and running at http://drupal.docker.localhost:8000
- You can see status of your containers and their logs via portainer: http://portainer.drupal.docker.localhost:8000
You can stop containers by executing
make stop
or docker-compose stop
.Optional files
If you don't need to run multiple projects and don't use mutagen to improve bind mounts performance on macOS feel free to delete
traefik.yml
and mutagen
that come within docker4drupal.tar.gz
Get updates
We release updates to images from time to time, you can find detailed changelog and update instructions on GitHub under releases page
Domains¶
Traefik container used for routing. By default, we use port
8000
to avoid potential conflicts but if port 80
is free on your host machine just replace traefik's ports definition in the compose file.By default
BASE_URL
set to drupal.docker.localhost
, you can change it in .env
file.Xdebug Docker For Mac High Sierra
Add
127.0.0.1 drupal.docker.localhost
to your /etc/hosts
file (some browsers like Chrome may work without it). Do the same for other default domains you might need from listed below:Service | Domain |
---|---|
nginx/apache | http://drupal.docker.localhost:8000 |
pma | http://pma.drupal.docker.localhost:8000 |
adminer | http://adminer.drupal.docker.localhost:8000 |
mailhog | http://mailhog.drupal.docker.localhost:8000 |
solr | http://solr.drupal.docker.localhost:8000 |
nodejs | http://nodejs.drupal.docker.localhost:8000 |
node | http://front.drupal.docker.localhost:8000 |
varnish | http://varnish.drupal.docker.localhost:8000 |
portainer | http://portainer.drupal.docker.localhost:8000 |
webgrind | http://webgrind.drupal.docker.localhost:8000 |
Xdebug¶
Xdebug troubleshooting
Vipnet client for mac os. Enable xdebug logs to get more information by adding
$PHP_XDEBUG_REMOTE_LOG=/tmp/php-xdebug.log
environment variable to PHP containerDebugging web requests¶
- Uncomment these lines for PHP service in your docker-compose file
- Restart containers (
make
) - Start debugging in IDE
- Start your browser debug helper plugin (Chrome or Firefox) and open the page you want to debug. Alternatively, enable auto start by adding
PHP_XDEBUG_REMOTE_AUTOSTART=1
Debugging CLI requests¶
- Enable Xdebug as described in the previous section
- Uncomment the following environment variables for PHP service in your composer file
- Perform configuration as described below depending on your OS and Docker version:
Linux, Docker¶
- Uncomment
PHP_XDEBUG_REMOTE_HOST: 172.17.0.1
for PHP service - Restart containers (
make
)
macOS, Docker¶
- Uncomment
PHP_XDEBUG_REMOTE_HOST: host.docker.internal
for PHP service (Docker 18.03+) - Restart containers (
make
)
Windows¶
- Uncomment
PHP_XDEBUG_REMOTE_HOST: host.docker.internal
for PHP service (Docker 18.03+) - Restart containers (
make
) - Allow listen connection for your IDE in
Windows Firewall > Allow an app .
Also, you might need to update your hosts file.
IDE configuration¶
You must additionally configure your IDE to debug CLI requests.
PHPStorm¶
- Open
Run > Edit Configurations
from the main menu, chooseDefaults > PHP Web Page
in the left sidebar - Click to
[..]
to the right ofServer
and add a new server- Enter name
my-ide
(as specified inPHP_IDE_CONFIG
) - Enter any host, it does not matter
- Check
Use path mappings
, select path to your project and enter/var/www/html
in the right column (Absolute path on the server)
- Enter name
- Choose newly created server in 'Server' for PHP Web Page
- Save settings
Crond¶
Crond enabled by default and runs every hour. The default command is:
You might need to change if your HTTP root is different. Runs from www-data
user.Database import and export¶
MariaDB¶
Known issues with indexes rebuild
Issues have been reported when MariaDB does not build indexes when dump imported using
mariadb-init
bind mount. For safety use the workaround described at https://github.com/wodby/mariadb/issues/11if you want to import your database, uncomment the line for
mariadb-init
bind mount in your compose file. Create the directory ./mariadb-init
in the same directory as the compose file and put there your .sql .sql.gz .sh
file(s). All SQL files will be automatically imported once MariaDB container has started.Exporting all databases: The sims download for mac os.
Exporting a specific database:
PostgreSQL¶
if you want to import your database, uncomment the line for
postgres-init
volume in your compose file. Create the volume directory ./postgres-init
in the same directory as the compose file and put there your .sql .sql.gz .sh
file(s). All SQL files will be automatically imported once Postgres container has started.Make commands¶
Basic:
We provide
Makefile
that contains commands to simplify the work with your local environment. You can run make [COMMAND]
to execute the following commands:Drupal-specific:
Docker for mac¶
There two major problems macOS users face with when using Docker for mac:
macOS permissions issues¶
To avoid any permissions issues caused by different user id (uid), group id (gid) between your host and a container use
-dev-macos
version of php image (uncomment the environment variables in .env
files) where the default user wodby
has 501:20
uid/gid that matches default macOS user. Bind mounts performance¶
By default, we use
:cached
option on bind mounts to improve performance on macOS (on Linux it behaves similarly to consistent
). You can find more information about this in docker blog. However, there's the synchronisation with Mutagen which is a faster alternative.Mutagen¶
The core idea of this project is to use an external volume that will sync your files with a file synchronizer tool.
- Uncomment Mutagen volume and service definitions in your compose file
- Replace codebase volumes definitions of services with the option below marked as 'Mutagen'
- Start the mutagen container
docker-compose up -d mutagen
- Start Mutagen:
mutagen project start -f mutagen/config.yml
(or just runmake mutagen
instead of steps 3 and 4) - Start other containers
docker-compose up -d
(ormake
) - When you no longer need mutagen run
mutagen project terminate
Now when you change your code on the host machine Mutagen will sync your data to php and nginx/apache containers.
For more information visit Mutagen project page.
Permissions issues¶
You might have permissions issues caused by non-matching uid/gid on your host machine and the default user in php container.
Linux¶
Since version 5.0 the default php container user
wodby
has uid/gid 1000
that matches the default uid/gid for most popular Linux distributions. macOS¶
Use
-dev-macos
version of php image where default wodby
user has 501:20
uid/gid that matches default macOS user.Windows¶
Since you can't change owner of mounted volumes in Docker for Win, the only solution is to run everything as root, add the following options to
php
service in your docker-compose file:Different uid/gid?¶
You can rebuild the base image wodby/php with custom user/group ids by using docker build arguments
WODBY_USER_ID
, WODBY_GROUP_ID
(both 1000
by default)Running multiple Projects¶
This project uses træfik to route traffic to different containers. Træfik is a modern HTTP reverse proxy and load balancer made to deploy microservices with ease. To understand the basics of Traefik it is suggested to check Træfik's documentation page: https://docs.traefik.io/
Image: Multi-domain set-up example(Source: traefik.io)
There are two ways how you can run multiple projects:
Single port¶
In this case you will run a stand-alone traefik that will be connected to docker networks of your projects:
- Download
traefik.yml
file (part ofdocker4x.tar.gz
archive). Place it separately from your projects, it will be a global traefik container that will route requests to your projects on a specified port - Now we need to provide traefik names of docker networks of our projects. Let's say projects directories with
docker-compose.yml
namedfoo
andbar
. Docker Compose will create default docker networks for these projects calledfoo_default
andbar_default
. Update external networks names accordingly intraefik.yml
- In
docker-compose.yml
of your projects comment outtraefik
service and make suretraefik.http.*
labels have${PROJECT_NAME}_
prefix - Make sure
$PROJECT_BASE_URL
and$PROJECT_NAME
(in.env
file) differ, both hosts point to127.0.0.1
in/etc/hosts
- Run your projects:
make
(ordocker-compose up -d
) - Run stand-alone traefik:
docker-compose -f traefik.yml up -d
- Now when you visit URL from
$PROJECT_BASE_URL
, traefik will route traffic to the corresponding docker networks
Different ports¶
Alternatively, instead of running a stand-alone traefik, you can just run default traefik containers on different ports. Just a few things to make sure:
- Ports of
traefik
service in yourdocker-compose.yml
files differ traefik.http.*
labels have${PROJECT_NAME}_
prefix$PROJECT_BASE_URL
and$PROJECT_NAME
(in.env
file) differ, both hosts point to127.0.0.1
in/etc/hosts
To use xdebug with macOS and docker is quite, let´s call it tricky ;)
The following steps need to be proceed to get it working:
Xdebug Docker.for.mac.localhost
- use the config from the xdebug.ini wihtin your docker web container. Important: set remote_connect_back to off
UPDATE
As mentioned by some comments (thanks for the feedback), it is not needed to configure the IP manually. Thus, the next step is optional and the configuration (xdebug.ini) is updated to use the dynamic IP.
- optional: set up an alias for your local interface (lo)
To bring up the alias at startup, you can either (sudo may be needed here):
- manually place the file
com.manuelselbach.docker_10254254254_alias.plist
into directory:/Library/LaunchDaemons/
- Or use the script
set_and_install_autorun_alias_for_lo.sh
Configure PhpStorm
After all that, just configure your PhpStorm:
- set port for xdebug
Preferences -> Languages & Frameworks -> PHP -> Debug | Xdebug: Debug port = 9005
- configure a configuration in the toolbar
- use PHP remote Debug
- add a server to your domain (without protocoll like http:// or https://)
- set port for http / https (not the xdebug port here)
- select Debugger: Xdebug
- if needed: set path mappings
Xdebug Docker For Mac Installer
- set Ide key (session id): to PHPSTORM
Xdebug Php Docker
Happy debugging with docker!