magento2-docker

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

magento2-docker

★ 18 Open GitHub ↗

A composition of Docker containers for development and production

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
- Closely follow the installation guide from [Magento 2](https://experienceleague.adobe.com/en/docs/commerce-operations/installation-guide/overview)
- 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: magento2-php based on [php:fpm-alpine](https://hub.docker.com/_/php/)
- MariaDB: [mariadb](https://hub.docker.com/_/mariadb/)
- Nginx: magento2-nginx based on [nginxinc/nginx-unprivileged:alpine](https://hub.docker.com/r/nginxinc/nginx-unprivileged)
- Redis: [redis:alpine](https://hub.docker.com/_/redis/)
- Cron: magento2-php based on [php:fpm-alpine](https://hub.docker.com/_/php/)
- Varnish: magento2-varnish based on [varnish:alpine](https://hub.docker.com/_/varnish)
- Opensearch: [opensearchproject/opensearch](https://hub.docker.com/r/opensearchproject/opensearch)
- SSL / TLS Termination: [caddy:alpine](https://hub.docker.com/_/caddy)
- Autoheal: [willfarrell/autoheal](https://hub.docker.com/r/willfarrell/autoheal) - Automatically restarts unhealthy containers

## 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](https://letsencrypt.org/docs/certificates-for-localhost/)].

The easiest way to create your own certificates is to use [mkcert](https://github.com/FiloSottile/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
```

The SSL / TLS termination is handled by Caddy, which will automatically use the `certs/key.pem` and `certs/cert.pem` files for HTTPS in development.

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
```

#### HTTPS in Production

For production deployments, this repository uses Let's Encrypt for automatic HTTPS certificate management. Caddy handles certificate provisioning and renewal automatically. The default Caddyfile is configured for production use with Let's Encrypt.

**Configuration:**

1. Set environment variables for Let's Encrypt in your production environment:

```bash
   export CADDY_EMAIL=your-email@example.com  # Required for Let's Encrypt notifications
   export DOMAIN=yourdomain.com                # Your production domain
   ```

2. Ensure your domain's DNS A record points to your server's IP address.

3. Deploy normally - Caddy will automatically obtain and renew certificates from Let's Encrypt.

**Note:**

- Port 80 must be accessible from the internet for Let's Encrypt HTTP-01 challenge validation.
- For local development, docker-compose.override.yml automatically uses Caddyfile.dev with mkcert certificates.

#### Download Magento source files

```shell
wget -qO- https://github.com/magento/magento2/archive/refs/tags/$(cat .magento-version).tar.gz \
	| tar xzfo - --strip-components=1 -C src/ \
	&& docker compose run --rm composer install
```

The composer container will automatically install required PHP extensions defined in the composer file.

#### Secrets Management

This setup uses Docker secrets to securely manage sensitive information like passwords. Create the following files in the `secrets/` directory:

- `secrets/db_password.txt` - Database password for Magento user
- `secrets/mysql_root_password.txt` - MySQL root password
- `secrets/admin_password.txt` - Magento admin password
- `secrets/smtp_password.txt` - SMTP server password

These secrets are automatically mounted into containers at `/run/secrets/` and used by the application.

##### Install packages via Composer

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

```shell
docker compose run --rm composer require <package>
```

![Environments](https://github.com/zsoerenm/magento2-docker/raw/master/manual/environments.svg?sanitize=true)

##### 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](https://devdocs.magento.com/guides/v2.2/config-guide/deployment/pipeline/technical-details.html) 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

```shell
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](https://experienceleague.adobe.com/en/docs/commerce-operations/tools/cli-reference/commerce-on-premises#setupinstall).
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](https://experienceleague.adobe.com/en/docs/commerce-operations/tools/cli-reference/commerce-on-premises#setupconfigset) list for all configuration options.

Beyond that, you can also set any configuration which you would normally set in the admin backend. [Here](https://experienceleague.adobe.com/en/docs/commerce-operations/configuration-guide/deployment/examples/example-environment-variables) 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`

**Secrets Support**: For sensitive data like passwords, you can use the `_FILE` suffix to read values from Docker secrets:

- `DB_PASSWORD_FILE=/run/secrets/db_password` - Read database password from secret file
- `ADMIN_PASSWORD_FILE=/run/secrets/admin_password` - Read admin password from secret file
- `CONFIG__DEFAULT__SYSTEM__SMTP__PASSWORD_UNENCRYPTED_FILE=/run/secrets/smtp_password` - Read SMTP password from secret file

_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 using secrets (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

```bash
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

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

This should give a list similar to

<details>
<summary>
Currencies
</summary>
+---------------------------------------------+------+
| Currency                                    | Code |
+---------------------------------------------+------+
| Afghan Afghani (AFN)                        | AFN  |
| Albanian Lek (ALL)                          | ALL  |
| Algerian Dinar (DZD)                        | DZD  |
| Angolan Kwanza (AOA)                        | AOA  |
| Argentine Peso (ARS)                        | ARS  |
| Armenian Dram (AMD)                         | AMD  |
| Aruban Florin (AWG)                         | AWG  |
| Australian Dollar (AUD)                     | AUD  |
| Azerbaijani Manat (1993–2006) (AZM)         | AZM  |
| Azerbaijani Manat (AZN)                     | AZN  |
| Bahamian Dollar (BSD)                       | BSD  |
| Bahraini Dinar (BHD)                        | BHD  |
| Bangladeshi Taka (BDT)                      | BDT  |
| Barbadian Dollar (BBD)                      | BBD  |
| Belarusian Ruble (BYN)                      | BYN  |
| Belize Dollar (BZD)                         | BZD  |
| Bermudan Dollar (BMD)                       | BMD  |
| Bhutanese Ngultrum (BTN)                    | BTN  |
| Bolivian Boliviano (BOB)                    | BOB  |
| Bosnia-Herzegovina Convertible Mark (BAM)   | BAM  |
| Botswanan Pula (BWP)                        | BWP  |
| Brazilian Real (BRL)                        | BRL  |
| British Pound (GBP)                         | GBP  |
| Brunei Dollar (BND)                         | BND  |
| Bulgarian Lev (BGN)                         | BGN  |
| Burmese Kyat (BUK)                          | BUK  |
| Burundian Franc (BIF)                       | BIF  |
| CFP Franc (XPF)                             | XPF  |
| Cambodian Riel (KHR)                        | KHR  |
| Canadian Dollar (CAD)                       | CAD  |
| Cape Verdean Escudo (CVE)                   | CVE  |
| Cayman Islands Dollar (KYD)                 | KYD  |
| Chilean Peso (CLP)                          | CLP  |
| Chinese Yuan (CNY)                          | CNY  |
| Colombian Peso (COP)                        | COP  |
| Comorian Franc (KMF)                        | KMF  |
| Congolese Franc (CDF)                       | CDF  |
| Costa Rican Colón (CRC)                     | CRC  |
| Croatian Kuna (HRK)                         | HRK  |
| Cuban Peso (CUP)                            | CUP  |
| Czech Koruna (CZK)                          | CZK  |
| Danish Krone (DKK)                          | DKK  |
| Djiboutian Franc (DJF)                      | DJF  |
| Dominican Peso (DOP)                        | DOP  |
| East Caribbean Dollar (XCD)                 | XCD  |
| Egyptian Pound (EGP)                        | EGP  |
| Equatorial Guinean Ekwele (GQE)             | GQE  |
| Eritrean Nakfa (ERN)                        | ERN  |
| Estonian Kroon (EEK)                        | EEK  |
| Ethiopian Birr (ETB)                        | ETB  |
| Euro (EUR)                                  | EUR  |
| Falkland Islands Pound (FKP)                | FKP  |
| Fijian Dollar (FJD)                         | FJD  |
| Gambian Dalasi (GMD)                        | GMD  |
| Georgian Kupon Larit (GEK)                  | GEK  |
| Georgian Lari (GEL)                         | GEL  |
| Ghanaian Cedi (GHS)                         | GHS  |
| Gibraltar Pound (GIP)                       | GIP  |
| Guatemalan Quetzal (GTQ)                    | GTQ  |
| Guinean Franc (GNF)                         | GNF  |
| Guyanaese Dollar (GYD)                      | GYD  |
| Haitian Gourde (HTG)                        | HTG  |
| Honduran Lempira (HNL)                      | HNL  |
| Hong Kong Dollar (HKD)                      | HKD  |
| Hungarian Forint (HUF)                      | HUF  |
| Icelandic Króna (ISK)                       | ISK  |
| Indian Rupee (INR)                          | INR  |
| Indonesian Rupiah (IDR)                     | IDR  |
| Iranian Rial (IRR)                          | IRR  |
| Iraqi Dinar (IQD)                           | IQD  |
| Israeli New Shekel (ILS)                    | ILS  |
| Jamaican Dollar (JMD)                       | JMD  |
| Japanese Yen (JPY)                          | JPY  |
| Jordanian Dinar (JOD)                       | JOD  |
| Kazakhstani Tenge (KZT)                     | KZT  |
| Kenyan Shilling (KES)                       | KES  |
| Kuwaiti Dinar (KWD)                         | KWD  |
| Kyrgystani Som (KGS)                        | KGS  |
| Laotian Kip (LAK)                           | LAK  |
| Latvian Lats (LVL)                          | LVL  |
| Lebanese Pound (LBP)                        | LBP  |
| Lesotho Loti (LSL)                          | LSL  |
| Liberian Dollar (LRD)                       | LRD  |
| Libyan Dinar (LYD)                          | LYD  |
| Lithuanian Litas (LTL)                      | LTL  |
| Macanese Pataca (MOP)                       | MOP  |
| Macedonian Denar (MKD)                      | MKD  |
| Malagasy Ariary (MGA)                       | MGA  |
| Malawian Kwacha (MWK)                       | MWK  |
| Malaysian Ringgit (MYR)                     | MYR  |
| Maldivian Rufiyaa (MVR)                     | MVR  |
| Mauritanian Ouguiya (1973–2017) (MRO)       | MRO  |
| Mauritian Rupee (MUR)                       | MUR  |
| Mexican Peso (MXN)                          | MXN  |
| Moldovan Leu (MDL)                          | MDL  |
| Mongolian Tugrik (MNT)                      | MNT  |
| Moroccan Dirham (MAD)                       | MAD  |
| Mozambican Metical (MZN)                    | MZN  |
| Myanmar Kyat (MMK)                          | MMK  |
| Namibian Dollar (NAD)                       | NAD  |
| Nepalese Rupee (NPR)                        | NPR  |
| Netherlands Antillean Guilder (ANG)         | ANG  |
| New Taiwan Dollar (TWD)                     | TWD  |
| New Zealand Dollar (NZD)                    | NZD  |
| Nicaraguan Córdoba (1988–1991) (NIC)        | NIC  |
| Nicaraguan Córdoba (NIO)                    | NIO  |
| Nigerian Naira (NGN)                        | NGN  |
| North Korean Won (KPW)                      | KPW  |
| Norwegian Krone (NOK)                       | NOK  |
| Omani Rial (OMR)                            | OMR  |
| Pakistani Rupee (PKR)                       | PKR  |
| Panamanian Balboa (PAB)                     | PAB  |
| Papua New Guinean Kina (PGK)                | PGK  |
| Paraguayan Guarani (PYG)                    | PYG  |
| Peruvian Sol (PEN)                          | PEN  |
| Philippine Peso (PHP)                       | PHP  |
| Polish Zloty (PLN)                          | PLN  |
| Qatari Riyal (QAR)                          | QAR  |
| Rhodesian Dollar (RHD)                      | RHD  |
| Romanian Leu (1952–2006) (ROL)              | ROL  |
| Romanian Leu (RON)                          | RON  |
| Russian Ruble (RUB)                         | RUB  |
| Rwandan Franc (RWF)                         | RWF  |
| Salvadoran Colón (SVC)                      | SVC  |
| Samoan Tala (WST)                           | WST  |
| Saudi Riyal (SAR)                           | SAR  |
| Serbian Dinar (RSD)                         | RSD  |
| Seychellois Rupee (SCR)                     | SCR  |
| Sierra Leonean Leone (1964—2022) (SLL)      | SLL  |
| Singapore Dollar (SGD)                      | SGD  |
| Slovak Koruna (SKK)                         | SKK  |
| Solomon Islands Dollar (SBD)                | SBD  |
| Somali Shilling (SOS)                       | SOS  |
| South African Rand (ZAR)                    | ZAR  |
| South Korean Won (KRW)                      | KRW  |
| Sri Lankan Rupee (LKR)                      | LKR  |
| St. Helena Pound (SHP)                      | SHP  |
| Sudanese Pound (SDG)                        | SDG  |
| Surinamese Dollar (SRD)                     | SRD  |
| Swazi Lilangeni (SZL)                       | SZL  |
| Swedish Krona (SEK)                         | SEK  |
| Swiss Franc (CHF)                           | CHF  |
| Syrian Pound (SYP)                          | SYP  |
| São Tomé & Príncipe Dobra (1977–2017) (STD) | STD  |
| Tajikistani Somoni (TJS)                    | TJS  |
| Tanzanian Shilling (TZS)                    | TZS  |
| Thai Baht (THB)                             | THB  |
| Tongan Paʻanga (TOP)                        | TOP  |
| Trinidad & Tobago Dollar (TTD)              | TTD  |
| Tunisian Dinar (TND)                        | TND  |
| Turkish Lira (1922–2005) (TRL)              | TRL  |
| Turkish Lira (TRY)                          | TRY  |
| Turkmenistani Manat (1993–2009) (TMM)       | TMM  |
| US Dollar (USD)                             | USD  |
| Ugandan Shilling (UGX)                      | UGX  |
| Ukrainian Hryvnia (UAH)                     | UAH  |
| United Arab Emirates Dirham (AED)           | AED  |
| Uruguayan Peso (UYU)                        | UYU  |
| Uzbekistani Som (UZS)                       | UZS  |
| Vanuatu Vatu (VUV)                          | VUV  |
| Venezuelan Bolívar (1871–2008) (VEB)        | VEB  |
| Venezuelan Bolívar (2008–2018) (VEF)        | VEF  |
| Vietnamese Dong (VND)                       | VND  |
| WIR Euro (CHE)                              | CHE  |
| WIR Franc (CHW)                             | CHW  |
| West African CFA Franc (XOF)                | XOF  |
| Yemeni Rial (YER)                           | YER  |
| Zambian Kwacha (1968–2012) (ZMK)            | ZMK  |
| Zimbabwean Dollar (1980–2008) (ZWD)         | ZWD  |
+---------------------------------------------+------+
</details>

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

```bash
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:

```bash
docker-compose exec redis redis-cli monitor
```

You should see an output similar to
[experienceleague.adobe.com](https://experienceleague.adobe.com/en/docs/commerce-operations/configuration-guide/cache/redis/redis-pg-cache) (see Verify Redis connection)

##### Health Monitoring & Auto-healing

This setup includes comprehensive health monitoring and automatic healing capabilities:

**Health Checks**: All services have health checks configured:

- **PHP**: Monitors PHP-FPM process status
- **Database**: Checks MySQL connectivity and initialization
- **Redis**: Verifies Redis server response
- **Nginx**: Tests HTTP response on port 8080
- **Caddy**: Validates port connectivity on 80 and 443
- **Varnish**: Depends on healthy web service

**Auto-healing**: The `autoheal` service automatically restarts any container that fails its health check, ensuring high availability and reducing manual intervention.

You can monitor container health status with:

```bash
docker-compose ps
```

Healthy containers show "healthy" status, while problematic ones show "unhealthy".

##### 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

### PHP Extension Management

PHP extensions required by Magento are automatically installed during Docker build based on `src/composer.json` requirements. The build process:

1. Parses composer.json for `ext-*` entries
2. Maps extensions to Alpine Linux packages
3. Installs extensions with `docker-php-ext-install`
4. Validates all extensions loaded successfully

When upgrading Magento versions, extension requirements are automatically synchronized. No manual Dockerfile updates needed.

See [docs/PHP_EXTENSIONS.md](docs/PHP_EXTENSIONS.md) for details.

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

```bash
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](https://devdocs.magento.com/guides/v2.2/config-guide/deployment/pipeline/technical-details.html) process from Magento with the help of Docker containers.
The process is as follows:

1. Dump your configuration on the development machine:

```bash
docker-compose exec php bin/magento app:config:dump scopes themes
```

3. Build the php container for production

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

4. Build the nginx container for production

```bash
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

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

## Q&A

- How do I find the admin URI?

```bash
docker-compose exec php php bin/magento info:adminuri
```

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

```bash
+ 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 scopes themes` (example: `docker-compose exec php bin/magento app:config:dump scopes themes`).

## Hyvä Theme Support

This setup includes Node.js in the PHP container to support frontend build tools like the [Hyvä theme](https://hyva.io)'s Tailwind CSS compiler.

### Installing Hyvä

#### Option A: Install from Hyvä Private Packagist (recommended)

Register at [hyva.io](https://hyva.io) and create a free key from your account dashboard. This also gives access to compatibility modules.

```bash
docker compose run --rm composer config --auth http-basic.hyva-themes.repo.packagist.com token yourLicenseKey
docker compose run --rm composer config repositories.private-packagist composer https://hyva-themes.repo.packagist.com/yourProjectName/
docker compose run --rm composer require hyva-themes/magento2-default-theme
```

#### Option B: Install from GitHub

No account needed — configure the required repositories directly:

```bash
for repo in magento2-theme-module magento2-default-theme magento2-default-theme-csp \
  magento2-base-layout-reset magento2-compat-module-fallback magento2-luma-checkout \
  magento2-theme-fallback magento2-order-cancellation-webapi magento2-email-module \
  magento2-mollie-theme-bundle; do
  docker compose run --rm composer config repositories.hyva-themes/$repo git https://github.com/hyva-themes/$repo.git
done
docker compose run --rm composer require "hyva-themes/magento2-default-theme:^1.3.21"
docker compose exec php bin/magento setup:upgrade
```

Then activate the `hyva/default` theme in **Content → Design → Configuration**.

### Building Tailwind CSS

A `tailwind` helper script is included that automatically detects all installed themes with a Tailwind setup and runs `npm ci` + the appropriate build command.

In **developer mode**, the Tailwind watcher starts automatically on container boot when Hyvä is detected — no manual steps needed. During **production builds**, Tailwind CSS is compiled automatically in the Docker build stage.

### Automatic Configuration

When the PHP container starts, it automatically detects if the `Hyva_Theme` module is installed and disables Magento's legacy JS/CSS bundling and minification (which conflicts with Hyvä's Tailwind CSS approach). This includes disabling JS merge/bundle/minify, CSS merge/minify, HTML minification, and legacy captcha.

No manual configuration needed — just install the theme and restart the container.

See the [Hyvä documentation](https://docs.hyva.io/hyva-themes/getting-started/index.html) for the full setup guide.

## Todos

- Add Let's encrypt example for production
- Add a periodic MySQL backup

## License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
Magento 2 is licensed under their [official license](https://github.com/magento/magento2/blob/2.3-develop/LICENSE.txt).

magento2-docker

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README