Magento 2 Docker

Yet another composition of Docker containers to run Magento 2.

Features

• Support development and production environments
• Use official containers if possible
• Use Alpine Linux if possible
• Follow best practices from Docker
• Closely follow the installation guide from Magento 2
• Configure SMTP server via environment variables to enable two-factor authentication (2FA) right from the start (no need to disable it)
• Easy deployment

Containers

• PHP: zsoerenm/magento2-php based on php:fpm-alpine
• MariaDB: mariadb
• Nginx: zsoerenm/magento2-nginx based on nginx:alpine
• Redis: redis:alpine
• Cron: zsoerenm/magento2-php based on php:fpm-alpine
• Varnish: zsoerenm/magento2-varnish based on varnish:alpine
• Opensearch: opensearchproject/opensearch
• SSL / TLS Termination: hitch

Getting Started

Prerequisites

HTTPS during local development

Yes, this repository supports HTTPS for local development. This follows the best practice of keeping the development environment as close to the production environment as possible. Also, web browsers behave in subtly different ways on HTTP vs. HTTPS pages. The main difference: On an HTTPS page, all requests to load JavaScript from an HTTP URL are blocked [see Let's Encrypt: Certificates for localhost].

The easiest way to create your own certificates is to use mkcert. Generate a certificate for localhost and / or a named URL like magento.local in the certs directory:

mkcert -key-file certs/key.pem -cert-file certs/cert.pem magento.local localhost

and concatenate them to a single file together with the dhparams.pem (which already exists in the certs folder):

cat certs/key.pem certs/cert.pem certs/dhparams.pem > certs/composedcert.pem

The composedcert.pem will be used by the SSL / TLS termination in local development by hitch.

If you'd like to use a named URL like magento.local also make sure to add an entry to your hosts file (located at /etc/hosts):

127.0.0.1  magento.local

Get your source code into the container

By default, the php container already ships with the Magento 2 source code. In order to be able to modify the code outside the container, I use a neat little trick explained here. Basically a named volume is used to get the source code onto the host, but the files are made available in the ./src folder by directing Docker to use this folder instead of an internal folder. The magic bit in docker-compose.yml file is:

appdata:
  driver: local
  driver_opts:
    type: none
    device: "./src"
    o: bind

There might be some issues with permissions, though. All the source files are owned by the user id 1000. If you happen to have the same id on your host, then everything is fine. You can check with id in your command line. For me it returns something like

uid=1000(schoenbrod) gid=1000(schoenbrod)

If you don't have the id 1000, two options come into my mind:

1. If you use VSCode for development, you could use an extension for VSCode to actually code inside the container: https://code.visualstudio.com/docs/devcontainers/containers
2. Change the permissions to something like sudo chmod -R 777 ./src. Don't worry before going to production the docker build will care about the permissions anyway.

Install packages via Composer

The docker-compose.yml file also ships with a Composer service. You can use it to install packages via Composer:

docker-compose run composer require <package>

Production

For the production environment it is instead recommended copying the source code into the container and omit the mount from host to container. Moreover, this repository implements the suggested pipeline deployment from Magento. It enables a fast deployment with a very short offline interval compared to the conventional deployment process. See the section "From development to production environment" below for further details.

Usage

In a development environment simply run

docker-compose up

and head to http://localhost/. You should automatically be redirected to HTTPS.

Environment Variables

PHP

Magento will be installed the first time you start the container. The installation can be configured by environment variables. You can find all configuration options here. Since environment variables are usually written in caps lock and with the underscore separator, the configuration keys are transformed. Hence, --db-host becomes DB_HOST and --admin-user becomes ADMIN_USER.

Most of the installation configuration options can also be changed after Magento has been installed (the Docker entry point will use php bin/magento setup:config:set internally). See this list for all configuration options.

Beyond that, you can also set any configuration which you would normally set in the admin backend. Here you will find more on how to set configurations using environment variables.

• Example: CONFIG__DEFAULT__GENERAL__STORE_INFORMATION__NAME=Foobar - Optional - sets config for general/store_information/name

Note: This is a great opportunity to get around the chicken-egg problem with two-factor authentication (2FA). Since v2.4.6 Magento ships with SMTP integration, and you can set the appropriate configuration options up front (see the docker-compose.yml file for more explanation).

If you'd like to set the language of the shop, you can do so by setting

LANGUAGE=en_US

You can list all installed languages with

docker-compose run --rm php bin/magento info:language:list

This should give a list similar to

If you'd like to set the currency of the shop, you can do so by setting

CURRENCY=EUR

You can list all available currencies with

docker-compose run --rm php bin/magento info:currency:list

This should give a list similar to

If you'd like to set the timezone of the shop, you can do so by setting

TIMEZONE=Europe/Berlin

You can list all available timezones with

docker-compose run --rm php bin/magento info:timezone:list

This should give a list similar to

Redis

Confirm that Redis is set up correctly:

docker-compose exec redis redis-cli monitor

You should see an output similar to experienceleague.adobe.com (see Verify Redis connection)

Database

• MYSQL_ROOT_PASSWORD - Optional, Required on first run
• MYSQL_DATABASE - Optional, Required on first run
• MYSQL_USER - Optional, Required on first run
• MYSQL_PASSWORD - Optional, Required on first run

Web

• BACKEND_HOST - Required - Must be set to the php host
• SERVER_NAME - Required - Server name must be identical to the name of the container

SSL Proxy

• BACKEND_HOST - Required - Must be set to the varnish host
• SERVER_NAME - Required - The server name that you'd like to type in the browser

Renovate

The dependencies within this repository are automatically updated by Renovate. To ensure compatibility with dependencies like Redis, MariaDB, Varnish, etc., I wrote a little script (update-dependency-version.sh) that gets the latest compatibility list from https://experienceleague.adobe.com/en/docs/commerce-operations/installation-guide/system-requirements and passes it to the Renovate configuration renovate.json. This should keep the repository up to date while still maintaining compatibility.

Backup MySQL database

Linux and Mac:

docker-compose exec db /usr/bin/mysqldump -u magento2 --password=magento2 magento2 > backup.sql

Replace magento2 for user, password and database with whatever you've set in the docker-compose file.

From development to production environment

This is still WIP!

This repository implements the recommended deployment process from Magento with the help of Docker containers. The process is as follows:

1. Dump your configuration on the development machine:

docker-compose exec php bin/magento app:config:dump

2. Copy the app/etc/config.php to your development host

docker cp $(docker-compose ps -q php):/var/www/html/app/etc/config.php ./src/app/etc/config.php

3. Build the php container for production

docker build -f php/Dockerfile -t magento2-php-prod .

4. Build the nginx container for production

docker build -f nginx/Dockerfile -t magento2-nginx-prod .

Note: The nginx Dockerfile refers to magento2-php-prod to copy some files. So make sure that you name the php image magento2-php-prod. 5. Move the php and nginx image to your production environment 6. Run the following on your production machine

docker-compose up -f prod.docker-compose.yml

Q&A

• The following error is thrown when php container for production is build

+ php bin/magento setup:static-content:deploy -f

Deploy using quick strategy

  [DomainException]
  Default website is not defined

Answer: Make sure you have run app:config:dump (example: docker-compose exec php bin/magento app:config:dump) and copied app/etc/config.php to the host.

• When building the php container I get the following error:

You cannot run this command because modules are not enabled. You can enable modules by running the 'module:enable --all' command.

Answer: Put your config.php into src/app/etc/. If you run Magento 2 locally you can do that in the following way:

docker cp $(docker-compose ps -q php):/var/www/html/app/etc/config.php ./src/app/etc/config.php

Todos

• Make Varnish optional (For PWA is does not really makes sense)
• Add Let's encrypt example for production
• Add Elasticsearch (since Magento 2.3 it will be supported by CE version)
• Add a periodic MySQL backup

License

This project is licensed under the MIT License - see the LICENSE.md file for details. Magento 2 is licensed under their official license.