PHP Magento Docker development environment

    Working with PHP projects usually requires to have a local development environment. In this article we will show you how a typical docker-based environment for Magento 2.

    Some containers will be based on the official Magento Cloud Docker images.

Step 1: Prepare folders structure for the project

Create folders docker, html and mgdb in your project root.

docker - this folder will contain all containers Dockerfiles and configuration files.

html -  app root (contains the source code)

mgdb - stores DB files and mounted as /var/lib/mysql for MariaDB service

The final structure can look like this:

├── docker
├── html
└── mgdb

Step 2: Create the custom docker network

    TIP: Check the Magento 2.4 technology stack requirements page to find the latest information about Magento tech stack.

For small PHP projects it's usually enough to have a php-apache container to start development, but not for  Magento 2; we need to install additional php libraries and set up services like Elasticsearch, Redis or RabbitMQ.  

The easiest way to do this is to define all services in docker-compose.yml file under the docker directory.

Our example structure looks like this:

├── app
│ ├── apache-config.conf
│ ├── auth.json
│ ├── Dockerfile
│ ├── msmtprc
│ ├── php-dev.ini
│ └── www
├── elasticsearch
│ ├── docker-entrypoint.sh
│ └── Dockerfile
├── mariadb
│ └── Dockerfile
├── rabbitmq
│ ├── definitions.json
│ └── rabbitmq.conf
├── redis
│ ├── Dockerfile
│ └── redis.conf
├── router
│ ├── ssl
│ └── templates
└── varnish
│ ├── default.vcl
│ └── Dockerfile
├── .env
└── docker-compose.yml

We can build custom containers from Dockerfiles or pull already pre-built images from Docker Hub, everything depends on your preferences. If we need a custom container like an application, it's better to take a base image and install required libraries there (in our case it is php:7.4-apache)

Step 3: Prepare the containers

It's recommended to put the containers into the docker network and make them linked via aliases.

The Application - is needed to execute PHP and make your app working.
We based our application container on php:7.4-apache image and installed additional dependencies as 
in php/7.4-fpm/Dockerfile from Magento Cloud Docker repository because that Dockerfile already contains all dependencies needed from the requirement stack.
We used php-apache image instead php-fpm to simplify virtual hosts configuration and to have everything we need in one container for development purposes.
Additionally we installed git, msmtp, NodeJS, PHP-SPX profiler and yarn;

The ENV variables are passed to the container via .env file.
The app root folder is mounted under /var/www/html and the composer cache folder is also mounted to user machine along with PHP, APACHE and SMTP configuration files.

Mounting helps to save container state; it prevents data from losing in case of container's recreation.
When config wiles are also mounted to the user's machine it simplifies editing of config (just restart the container without rebuilding it).

WARNING: mounting folders with huge number of files affects the environment performance, so the apps with large codebase (like Magento 2) may work slowly on non-Linux OS. Consider using docker volumes and different approaches of syncing files between your machine and the docker container if you are using Windows or Mac OS.

The Database - contains the DB data

The Elasticsearch - is required to make Magento catalog work (see the removal info)

The Varnish - we recommend to have this service in case you need to test FPC Magento feature with Varnish. Check our VCL config.

The Router - an nginx service used to route requests to the Varnish or the Application containers. It allows us to add more services accessible via 80 or 443 port in the browser by routing them based on server name or other rules (e.g. use different php version, fpm-worker or PWA app)

In our example we are routing all storefront requests to app through Varnish and all requests to custom admin URL directly to the application container

The Redis - a cache service

The RabbitMQ - a queue manager

The MailHog - GUI for mailbox, needed to view emails caught by msmtprc

The complete network: https://github.com/WebMageic/docker-dev/tree/main/docker

Step 4: Run and use

Open the docker folder

$ cd docker

run all services

$ docker compose up

We added the run.sh script to simplify the environment startup. It stops all running docker containers, performs docker compose up -d command and automatically connects to application container as www-data user.

Check the initial environment functionality by acceding the index.php file with the phpinfo() function in /var/www/html/pub via links in your browser:

http://magento.local/

http://pa.magento.local/

(make sure these domains added to the hosts file)

If everything works well we will see this output, then we can move to magento 2 installation step. 

 

The example project can be found on GitHub: https://github.com/WebMageic/docker-dev

Have a good development experience!