Local environment with Docker4PHP

Docker4PHP is an open-source project (GitHub page) that provides pre-configured compose.yml file with images to spin up local environment on Linux, Mac OS X and Windows.

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 the corresponding line under db server's volumes: in your compose.yml and update the host path to your data directory.

1. Download docker4php.tar.gz from the latest stable release and unpack to your PHP project root
2. Make sure NGINX_SERVER_ROOT (or APACHE_DOCUMENT_ROOT) is set to your project public directory with index.php (by default /var/www/html/public)
3. Ensure database credentials match in your database config and .env files
4. Configure domains
5. Optional: import existing database
6. Optional: uncomment lines in the compose file to run redis, elasticsearch, kibana, etc
7. Optional: macOS users please read this
8. Optional: Windows users please read this
9. Run containers: make up or docker compose up -d
10. Your php application should be up and running at http://php.docker.localhost:8000
11. You can see status of your containers and their logs via portainer: http://portainer.php.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 feel free to delete traefik.yml that come within docker4php.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

Docker4PHP uses traefik container 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 php.docker.localhost, you can change it in .env file.

Add 127.0.0.1 php.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://php.docker.localhost:8000
pma	http://pma.php.docker.localhost:8000
adminer	http://adminer.php.docker.localhost:8000
mailpit	http://mailpit.php.docker.localhost:8000
solr	http://solr.php.docker.localhost:8000
kibana	http://kibana.php.docker.localhost:8000
node	http://front.php.docker.localhost:8000
varnish	http://varnish.php.docker.localhost:8000
portainer	http://portainer.php.docker.localhost:8000
webgrind	http://webgrind.php.docker.localhost:8000

Mail sending

By default mailpit service enabled to catch all outbound emails, you can switch to opensmtpd (uncomment corresponding service in the compose file) if you need to actually delivery emails. OpenSMTPD can be used together with a third-party SMTP service for guaranteed email delivery by providing RELAY_ environment variables

If you want to use OpenSMTPD replace the following env vars:

MSMTP_HOST: opensmtpd
MSMTP_PORT: 25

Xdebug

Xdebug troubleshooting

Enable xdebug logs to get more information by adding $PHP_XDEBUG_REMOTE_LOG=/tmp/php-xdebug.log environment variable to PHP container.

Debugging web requests

Make sure you have PHP_EXTENSIONS_DISABLE env var overridden in your compose file to enable Xdebug (default value is xdebug,xhprof).

1. Uncomment these lines for PHP service in your compose.yml file (environment variables changed since xdebug 3.x)

   PHP_XDEBUG_MODE: debug
   

2. Restart containers (make)
3. Start debugging in IDE
4. 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_START_WITH_REQUEST: "yes"

Debugging CLI requests

1. Enable Xdebug as described in the previous section
2. Uncomment the following environment variables for PHP service in your composer file

   PHP_IDE_CONFIG: serverName=my-ide
   

3. Configure your IDE
4. Restart containers (make)

Also, you might need to update your hosts file.

IDE configuration

You must additionally configure your IDE to debug CLI requests.

PHPStorm

1. Open Run > Edit Configurations from the main menu, choose Defaults > PHP Web Page in the left sidebar
2. Click to [...] to the right of Server and add a new server
   • Enter name my-ide (as specified in PHP_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)
3. Choose newly created server in "Server" for PHP Web Page
4. Save settings

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/11

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

docker compose exec mariadb sh -c 'exec mysqldump --all-databases -uroot -p"root-password"' > databases.sql

Exporting a specific database:

docker compose exec mariadb sh -c 'exec mysqldump -uroot -p"root-password" my-db' > my-db.sql

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

We provide Makefile that contains commands to simplify the work with your local environment. You can run make [COMMAND] to execute the following commands:

Usage: make COMMAND

Commands:
    help            List available commands and their description 
    up              Start up all container from the current compose.yml 
    start           Start stopped containers 
    stop            Stop all containers for the current compose.yml (docker compose stop) 
    down            Same as stop
    prune [service] Stop and remove containers, networks, images, and volumes (docker compose down)
    ps              List container for the current project (docker ps with filter by name)
    shell [service] Access a container via shell as a default user (by default [service] is php)
    logs [service]  Show containers logs, use [service] to show logs of specific service
    mutagen         Start mutagen container and runs mutagen project

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.

First, we must install mutagen and mutagen-compose. Mutagen Compose requires Mutagen v0.13.0+.

brew install mutagen-io/mutagen
brew install mutagen-io/mutagen/mutagen-compose

1. Modify your compose.yml as following:
   • at the end of the file uncomment x-mutagen: and volumes: fields
   • replace volumes definitions under services that needs to be synced with the ones marked as "Mutagen"
2. Make sure ids of defaultOwner and defaultGroup under x-mutagen: match ids of the image you're using, e.g. uid 501 and gid 20 for -dev-macos image by default
3. Start mutagen via mutagen-compose up

Now when you change your code on the host machine Mutagen will sync your data to containers that use the synced volumed.

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 compose.yml file:

  php:
    user: root
    command: "php-fpm -R"
    environment:
      PHP_FPM_USER: root
      PHP_FPM_GROUP: root

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:

1. Download traefik.yml file (part of docker4x.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
2. Now we need to provide traefik names of docker networks of our projects. Let's say projects directories with compose.yml named foo and bar. Docker Compose will create default docker networks for these projects called foo_default and bar_default. Update external networks names accordingly in traefik.yml
3. In compose.yml of your projects comment out traefik service and make sure traefik.http.* labels have ${PROJECT_NAME}_ prefix
4. Make sure$PROJECT_BASE_URL and $PROJECT_NAME (in .env file) differ, both hosts point to 127.0.0.1 in /etc/hosts
5. Run your projects: make (or docker compose up -d)
6. Run stand-alone traefik: docker compose -f traefik.yml up -d
7. 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 your compose.yml files differ
• traefik.http.* labels have ${PROJECT_NAME}_ prefix
• $PROJECT_BASE_URL and $PROJECT_NAME (in .env file) differ, both hosts point to 127.0.0.1 in /etc/hosts