<h1 align="center">markshust/docker-magento</h1>
<div align="center">
<p>Mark Shust's Docker Configuration for Magento</p>
<img src="https://img.shields.io/badge/magento-2.X-brightgreen.svg?logo=magento&longCache=true" alt="Supported Magento Versions" />
<a href="https://hub.docker.com/r/markoshust/magento-php/" target="_blank"><img src="https://img.shields.io/docker/pulls/markoshust/magento-php.svg?label=php%20docker%20pulls" alt="Docker Hub Pulls - PHP" /></a>
<a href="https://hub.docker.com/r/markoshust/magento-nginx/" target="_blank"><img src="https://img.shields.io/docker/pulls/markoshust/magento-nginx.svg?label=nginx%20docker%20pulls" alt="Docker Hub Pulls - Nginx" /></a>
<a href="https://github.com/markshust/docker-magento/graphs/commit-activity" target="_blank"><img src="https://img.shields.io/badge/maintained%3F-yes-brightgreen.svg" alt="Maintained - Yes" /></a>
<img src="https://img.shields.io/badge/apple%20silicon%20support-yes-brightgreen" alt="Apple Silicon Support" />
<a href="https://opensource.org/licenses/MIT" target="_blank"><img src="https://img.shields.io/badge/license-MIT-blue.svg" /></a>
</div>
## Table of contents
- [Docker Hub](#docker-hub)
- [Free Course](#free-course)
- [Usage](#usage)
- [Prerequisites](#prerequisites)
- [Setup](#setup)
- [Updates](#updates)
- [Custom CLI Commands](#custom-cli-commands)
- [Misc Info](#misc-info)
- [Known Issues](#known-issues)
- [Alternatives](#alternatives)
- [Credits](#credits)
- [License](#license)
## Docker Hub
View Dockerfiles for the latest tags:
- [markoshust/magento-nginx (Docker Hub)](https://hub.docker.com/r/markoshust/magento-nginx/)
- [`1.18`, `1.18-8`](images/nginx/1.18)
- [`1.22`, `1.22-0`](images/nginx/1.22)
- [`1.24`, `1.24-1`](images/nginx/1.24)
- [`1.26`, `1.26-0`](images/nginx/1.26)
- [`1.28`, `1.28-0`](images/nginx/1.28)
- [markoshust/magento-php (Docker Hub)](https://hub.docker.com/r/markoshust/magento-php/)
- [`8.1-fpm`, `8.1-fpm-9`](images/php/8.1) · [`8.1-fpm-xdebug`, `8.1-fpm-xdebug-9`](images/php/8.1)
- [`8.2-fpm`, `8.2-fpm-9`](images/php/8.2) · [`8.2-fpm-xdebug`, `8.2-fpm-xdebug-9`](images/php/8.2)
- [`8.3-fpm`, `8.3-fpm-7`](images/php/8.3) · [`8.3-fpm-xdebug`, `8.3-fpm-xdebug-7`](images/php/8.3)
- [`8.4-fpm`, `8.4-fpm-2`](images/php/8.4) · [`8.4-fpm-xdebug`, `8.4-fpm-xdebug-2`](images/php/8.4)
- [`8.5-fpm`, `8.5-fpm-0`](images/php/8.5) · [`8.5-fpm-xdebug`, `8.5-fpm-xdebug-0`](images/php/8.5)
- [markoshust/magento-opensearch (Docker Hub)](https://hub.docker.com/r/markoshust/magento-opensearch/)
- [`1.2`, `1.2-0`](images/opensearch/1.2)
- [`2.5`, `2.5-1`](images/opensearch/2.5)
- [`2.12`, `2.12-0`](images/opensearch/2.12)
- [`3`, `3-0`](images/opensearch/3)
- [markoshust/magento-elasticsearch (Docker Hub)](https://hub.docker.com/r/markoshust/magento-elasticsearch/)
- [`7.16`, `7.16-0`](images/elasticsearch/7.16)
- [`7.17`, `7.17-1`](images/elasticsearch/7.17)
- [`8.4`, `8.4-0`](images/elasticsearch/8.4)
- [`8.5`, `8.5-0`](images/elasticsearch/8.5)
- [`8.7`, `8.7-0`](images/elasticsearch/8.7)
- [`8.11`, `8.11-0`](images/elasticsearch/8.11)
- [`8.13`, `8.13-0`](images/elasticsearch/8.13)
- [markoshust/magento-rabbitmq (Docker Hub)](https://hub.docker.com/r/markoshust/magento-rabbitmq/)
- [`3.9`, `3.9-0`](images/rabbitmq/3.9)
- [`3.11`, `3.11-1`](images/rabbitmq/3.11)
- [`3.12`, `3.12-0`](images/rabbitmq/3.12)
- [`3.13`, `3.13-0`](images/rabbitmq/3.13)
- [`4.1`, `4.1-0`](images/rabbitmq/4.1)
- [`4.2`, `4.2-0`](images/rabbitmq/4.2)
- [markoshust/magento-varnish (Docker Hub)](https://hub.docker.com/r/markoshust/magento-varnish/)
- [`7.7`, `7.7-0`](images/varnish/7.7)
- [markoshust/ssh (Docker Hub)](https://hub.docker.com/r/markoshust/magento-ssh/)
- [`latest`](images/ssh)
## Free Course
This course is sponsored by <a href="https://m.academy" target="_blank">M.academy</a>, the simplest way to learn Magento.
<a href="https://m.academy" target="_blank"><img src="docs/macademy-logo.png" alt="M.academy"></a>
A free screencast course is available (which was fully refreshed in December 2021), which details the basic usage of this project:
<a href="https://m.academy/courses/magento-2-development-environment-docker/" target="_blank">
<img src="docs/magento-2-development-environment-docker-og.png" alt="Magento 2 Development Environment with Docker" width="400"><br/>
Magento 2 Development Environment with Docker
</a>
### Course Curriculum
#### Intro
<table>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/meet-instructor-course-docker/" target="_blank"><img src="https://image.mux.com/Iz5ChvUVCWQ2UQBdZn5XSW02utamqadbos3uEDWJRs6w/thumbnail.jpg?time=22&width=400&quality=80" alt="Meet your instructor and course" width="240"></a><br/><a href="https://m.academy/lessons/meet-instructor-course-docker/" target="_blank">Meet your instructor and course</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/understand-course-format-docker/" target="_blank">Understand the course format</a></td>
</tr>
</table>
#### Initial project setup
<table>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/install-desktop-configure-preferences-docker/" target="_blank"><img src="https://image.mux.com/zYwIi00ZGVA6nFIZAE1RIQ4cHbWSvRq15N02K1rVhHeFc/thumbnail.jpg?time=105&width=400&quality=80" alt="Install Docker Desktop and configure preferences" width="240"></a><br/><a href="https://m.academy/lessons/install-desktop-configure-preferences-docker/" target="_blank">Install Docker Desktop and configure preferences</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/set-up-magento-automated-onelinesetup-script-docker/" target="_blank"><img src="https://image.mux.com/VSWcOfJDYTIXM008gAbMeHahzDQU9TSogfx01auv02MmpE/thumbnail.jpg?time=226&width=400&quality=80" alt="Set up Magento with the automated onelinesetup script" width="240"></a><br/><a href="https://m.academy/lessons/set-up-magento-automated-onelinesetup-script-docker/" target="_blank">Set up Magento with the automated onelinesetup script</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/set-up-magento-manually-from-custom-git-branch-docker/" target="_blank"><img src="https://image.mux.com/TlT00Tv1aNwNNNrnn2IV02e005EXsGYqnN01CCY02NFDqlbc/thumbnail.jpg?time=226&width=400&quality=80" alt="Set up Magento manually from a custom Git branch" width="240"></a><br/><a href="https://m.academy/lessons/set-up-magento-manually-from-custom-git-branch-docker/" target="_blank">Set up Magento manually from a custom Git branch</a></td>
</tr>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/set-up-existing-magento-project-docker/" target="_blank"><img src="https://image.mux.com/AZ4ycBHWCVHEQL84pca13uNGvnyT4wFZ4kFIsy8Cp7A/thumbnail.jpg?time=240&width=400&quality=80" alt="Set up Docker for an existing Magento project" width="240"></a><br/><a href="https://m.academy/lessons/set-up-existing-magento-project-docker/" target="_blank">Set up Docker for an existing Magento project</a></td>
</tr>
</table>
#### The basics of docker-magento
<table>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/execute-magento-helper-scripts-docker/" target="_blank"><img src="https://image.mux.com/C02TpQWbuXvyy4VJKis02deOF01Pj01aeKo3CxiSctAzF2U/thumbnail.jpg?time=102&width=400&quality=80" alt="Execute docker-magento helper scripts" width="240"></a><br/><a href="https://m.academy/lessons/execute-magento-helper-scripts-docker/" target="_blank">Execute docker-magento helper scripts</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/start-stop-restart-check-container-status-docker/" target="_blank"><img src="https://image.mux.com/Mp2VNohzPhovnxbL01b9vH6uT3F01CBTh8Lti8bV402fGo/thumbnail.jpg?time=53&width=400&quality=80" alt="Start, stop, restart, and check container status" width="240"></a><br/><a href="https://m.academy/lessons/start-stop-restart-check-container-status-docker/" target="_blank">Start, stop, restart, and check container status</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/execute-bin-magento-composer-within-containers-docker/" target="_blank"><img src="https://image.mux.com/0194T7F00sWnvgVfhsvnuz4JeP6PnRcmlVppzx00a7ducE/thumbnail.jpg?time=58&width=400&quality=80" alt="Execute bin/magento and Composer within Docker containers" width="240"></a><br/><a href="https://m.academy/lessons/execute-bin-magento-composer-within-containers-docker/" target="_blank">Execute bin/magento and Composer within Docker containers</a></td>
</tr>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/install-magento-sample-data-docker/" target="_blank"><img src="https://image.mux.com/BwIy8jYvrcILjFdacmw01mUPCXgj01uzm2nJcGQ7LAUak/thumbnail.jpg?time=45&width=400&quality=80" alt="Install Magento sample data" width="240"></a><br/><a href="https://m.academy/lessons/install-magento-sample-data-docker/" target="_blank">Install Magento sample data</a></td>
</tr>
</table>
#### Docker filesystem & data volumes
<table>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/understand-volumes-host-bind-mounts-docker/" target="_blank"><img src="https://image.mux.com/QhWFTFvNgbqoiXNxQQvfIJMWpi01o00eEn6AMJcH8xahE/thumbnail.jpg?time=88&width=400&quality=80" alt="Understand Docker volumes and host bind mounts" width="240"></a><br/><a href="https://m.academy/lessons/understand-volumes-host-bind-mounts-docker/" target="_blank">Understand Docker volumes and host bind mounts</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/manage-files-folders-within-containers-docker/" target="_blank"><img src="https://image.mux.com/noyySlTiUkdDlbuHP37Ui4DrBQScK01IMFs64NHhYU7A/thumbnail.jpg?time=121&width=400&quality=80" alt="Manage files and folders within Docker containers" width="240"></a><br/><a href="https://m.academy/lessons/manage-files-folders-within-containers-docker/" target="_blank">Manage files and folders within Docker containers</a></td>
</tr>
</table>
#### PhpStorm
<table>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/set-up-magento-project-phpstorm-docker/" target="_blank"><img src="https://image.mux.com/wGpX402APyQjkn3O5E9onBeteEzGsKfgEAR00Rpl004zA00/thumbnail.jpg?time=115&width=400&quality=80" alt="Set up a docker-magento project in PhpStorm and Docker" width="240"></a><br/><a href="https://m.academy/lessons/set-up-magento-project-phpstorm-docker/" target="_blank">Set up a docker-magento project in PhpStorm and Docker</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/set-up-magento-phpstorm-plugin-docker/" target="_blank"><img src="https://image.mux.com/gZPHr9vg00S7UON00676qQjRyxuLevsjKeb8DDZbVVhlI/thumbnail.jpg?time=97&width=400&quality=80" alt="Set up the Magento PhpStorm plugin" width="240"></a><br/><a href="https://m.academy/lessons/set-up-magento-phpstorm-plugin-docker/" target="_blank">Set up the Magento PhpStorm plugin</a></td>
</tr>
</table>
#### Code quality tools
<table>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/configure-phpcs-magento-docker/" target="_blank"><img src="https://image.mux.com/pAZ3J4kwyvSCUXXZOjvz2H8bPzfXFlD9PXT33MhJvGc/thumbnail.jpg?time=73&width=400&quality=80" alt="Configure PHPCS for Magento" width="240"></a><br/><a href="https://m.academy/lessons/configure-phpcs-magento-docker/" target="_blank">Configure PHPCS for Magento</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/configure-phpcsf-magento-docker/" target="_blank"><img src="https://image.mux.com/zibDqiUoV5CsOmVnXXq1t1oTZa89bpyzx00xZbbuBQZo/thumbnail.jpg?time=73&width=400&quality=80" alt="Configure PHPCSF for Magento" width="240"></a><br/><a href="https://m.academy/lessons/configure-phpcsf-magento-docker/" target="_blank">Configure PHPCSF for Magento</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/configure-phpmd-magento-docker/" target="_blank"><img src="https://image.mux.com/KlaX02700eTqe9rDhlcIdPDz023KJDzAtxfepuix81zs5k/thumbnail.jpg?time=78&width=400&quality=80" alt="Configure PHPMD for Magento" width="240"></a><br/><a href="https://m.academy/lessons/configure-phpmd-magento-docker/" target="_blank">Configure PHPMD for Magento</a></td>
</tr>
</table>
#### Xdebug
<table>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/install-xdebug-helper-browser-plugin-chrome-phpstorm-docker/" target="_blank"><img src="https://image.mux.com/huugRCqa00L7D8Ua6uV7jObMrjhT36vlryNnSBnFyO8A/thumbnail.jpg?time=59&width=400&quality=80" alt="Install the Xdebug helper browser plugin for Chrome and PhpStorm" width="240"></a><br/><a href="https://m.academy/lessons/install-xdebug-helper-browser-plugin-chrome-phpstorm-docker/" target="_blank">Install the Xdebug helper browser plugin for Chrome and PhpStorm</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/configure-phpstorm-xdebug-connections-docker/" target="_blank"><img src="https://image.mux.com/ta4K4uHoR00f9JTLFPLF391bXmj01tDOy9024jByC1PgCI/thumbnail.jpg?time=70&width=400&quality=80" alt="Configure PhpStorm for Xdebug connections" width="240"></a><br/><a href="https://m.academy/lessons/configure-phpstorm-xdebug-connections-docker/" target="_blank">Configure PhpStorm for Xdebug connections</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/trigger-xdebug-breakpoint-phpstorm-docker/" target="_blank"><img src="https://image.mux.com/V02OLZiJfIPrKV01VNhEf02Rxn00FUmaVC016nUoSkYdQrk4/thumbnail.jpg?time=55&width=400&quality=80" alt="Trigger an Xdebug breakpoint in PhpStorm with Docker" width="240"></a><br/><a href="https://m.academy/lessons/trigger-xdebug-breakpoint-phpstorm-docker/" target="_blank">Trigger an Xdebug breakpoint in PhpStorm with Docker</a></td>
</tr>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/trigger-xdebug-breakpoint-cli-commands-phpstorm-docker/" target="_blank"><img src="https://image.mux.com/h3INelvEFhYvZieGxtqZ9PpgeTlpC1eKBS020201o4q3sM/thumbnail.jpg?time=59&width=400&quality=80" alt="Trigger an Xdebug breakpoint for CLI commands in PhpStorm with Docker" width="240"></a><br/><a href="https://m.academy/lessons/trigger-xdebug-breakpoint-cli-commands-phpstorm-docker/" target="_blank">Trigger an Xdebug breakpoint for CLI commands in PhpStorm with Docker</a></td>
</tr>
</table>
#### Customize server configurations
<table>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/understand-compose-application-structure-docker/" target="_blank"><img src="https://image.mux.com/eUVT02qgmxDElsrAhzWuERTJQzSujA16D8XCsg012AxpI/thumbnail.jpg?time=143&width=400&quality=80" alt="Understand the docker-compose application structure" width="240"></a><br/><a href="https://m.academy/lessons/understand-compose-application-structure-docker/" target="_blank">Understand the docker-compose application structure</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/increase-php-memory-limit-php-ini-docker/" target="_blank"><img src="https://image.mux.com/gwBdn2r1bJlo2Eu1YD9J02LoVfpGvw01GQktweG1D84zo/thumbnail.jpg?time=166&width=400&quality=80" alt="Increase the PHP memory limit in php.ini for Docker" width="240"></a><br/><a href="https://m.academy/lessons/increase-php-memory-limit-php-ini-docker/" target="_blank">Increase the PHP memory limit in php.ini for Docker</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/increase-nginx-request-timeout-nginx-conf-docker/" target="_blank"><img src="https://image.mux.com/3kV1ZXGAbrGeXdgQP02M9Yf8In3eNPKM00zD8sHY476Y00/thumbnail.jpg?time=141&width=400&quality=80" alt="Increase the Nginx request timeout in nginx.conf for Docker" width="240"></a><br/><a href="https://m.academy/lessons/increase-nginx-request-timeout-nginx-conf-docker/" target="_blank">Increase the Nginx request timeout in nginx.conf for Docker</a></td>
</tr>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/increase-mysql-buffer-pool-size-command-or-my-cnf-docker/" target="_blank"><img src="https://image.mux.com/hv4gbjls001huhtXU00U1Y9Yya7bpelxeUW00JXLxMumlk/thumbnail.jpg?time=104&width=400&quality=80" alt="Increase the MySQL buffer pool size with a command or my.cnf" width="240"></a><br/><a href="https://m.academy/lessons/increase-mysql-buffer-pool-size-command-or-my-cnf-docker/" target="_blank">Increase the MySQL buffer pool size with a command or my.cnf</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/install-new-php-extension-by-building-custom-image-docker/" target="_blank"><img src="https://image.mux.com/jz02JrG2cYmqqZuKM01TACLglSG8kacEtUphcae00lLXlk/thumbnail.jpg?time=116&width=400&quality=80" alt="Install a new PHP extension by building a custom Docker image" width="240"></a><br/><a href="https://m.academy/lessons/install-new-php-extension-by-building-custom-image-docker/" target="_blank">Install a new PHP extension by building a custom Docker image</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/configure-multi-store-instances-nginx-docker/" target="_blank"><img src="https://image.mux.com/zBqzMlirT02eOZEDg00d9D023rc5bYgLRh6mFSBPOXb02CE/thumbnail.jpg?time=294&width=400&quality=80" alt="Configure multi-store instances in Docker with Nginx" width="240"></a><br/><a href="https://m.academy/lessons/configure-multi-store-instances-nginx-docker/" target="_blank">Configure multi-store instances in Docker with Nginx</a></td>
</tr>
</table>
#### Grunt
<table>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/understand-what-grunt-docker/" target="_blank"><img src="https://image.mux.com/HYHkbtaCdOfMvuKzQ8ty02g6iL2kJbjWlfnp3Ohhempw/thumbnail.jpg?time=66&width=400&quality=80" alt="Understand what Grunt is" width="240"></a><br/><a href="https://m.academy/lessons/understand-what-grunt-docker/" target="_blank">Understand what Grunt is</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/install-configure-grunt-docker/" target="_blank"><img src="https://image.mux.com/3GHRMkeEoXnjJ17GG7iTSM28p1iz2oxlJb6bvP6837o/thumbnail.jpg?time=128&width=400&quality=80" alt="Install and configure Grunt" width="240"></a><br/><a href="https://m.academy/lessons/install-configure-grunt-docker/" target="_blank">Install and configure Grunt</a></td>
<td width="33%" valign="top"><a href="https://m.academy/lessons/run-grunt-commands-magento-docker/" target="_blank"><img src="https://image.mux.com/EYuM77laXeN1jCagJ72vTXQ1VhVEVY00z00Q01oqlCbzlg/thumbnail.jpg?time=274&width=400&quality=80" alt="Run Grunt commands in Magento with Docker" width="240"></a><br/><a href="https://m.academy/lessons/run-grunt-commands-magento-docker/" target="_blank">Run Grunt commands in Magento with Docker</a></td>
</tr>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/use-grunt-livereload-docker/" target="_blank"><img src="https://image.mux.com/Y5AECMJithTaLFn9800DVWmrokfHkSOhmsGVWah4pxFo/thumbnail.jpg?time=136&width=400&quality=80" alt="Use Grunt with LiveReload" width="240"></a><br/><a href="https://m.academy/lessons/use-grunt-livereload-docker/" target="_blank">Use Grunt with LiveReload</a></td>
</tr>
</table>
#### Conclusion
<table>
<tr>
<td width="33%" valign="top"><a href="https://m.academy/lessons/wrap-up-course-explore-recommended-lessons-docker/" target="_blank">Wrap up the Docker course and explore recommended lessons</a></td>
</tr>
</table>
## Usage
This configuration is intended to be used as a Docker-based development environment for Magento 2.
Folders:
- `images`: Docker images for nginx and php
- `compose`: sample setups with Docker Compose
> The Magento 1 version of this development environment has been deprecated and is no longer supported. PHP 5 was used as it's base, and that version has reached end-of-life. If you still wish to use this setup, please reference [compose/magento-1 on tag 20.1.1](https://github.com/markshust/docker-magento/tree/20.1.1/compose/magento-1), but please be aware these images are no longer maintained.
## Prerequisites
This setup assumes you are running Docker on a computer with at least 6GB of RAM allocated to Docker, a dual-core, and an SSD hard drive. [Download & Install Docker Desktop](https://www.docker.com/products/docker-desktop).
This configuration has been tested on Mac & Linux. Windows is supported through the use of Docker on WSL.
## Setup
### Automated Setup (New Project)
```bash
# Create your project directory then go into it:
mkdir -p ~/Sites/magento
cd $_
# Run this automated one-liner from the directory you want to install your project.
curl -s https://raw.githubusercontent.com/markshust/docker-magento/master/lib/onelinesetup | bash -s -- magento.test mageos 3.0.0
```
The `magento.test` above defines the hostname to use, `mageos` is the edition (Mage-OS, the default), and `3.0.0` defines the version to install. Pass `community 2.4.9` (or another edition/version pair) instead to install Adobe Commerce / Magento Open Source. Note that since we need a write to `/etc/hosts` for DNS resolution, you will be prompted for your system password during setup.
After the one-liner above completes running, you should be able to access your site at `https://magento.test`.
#### Install sample data and development modules
After the above installation is complete, you can initialize the development environment with sample data and dev-related modules with:
```bash
bin/init
```
### Manual Setup
Same result as the one-liner above. Just replace `magento.test` references with the hostname that you wish to use.
#### New Projects
```bash
# Create your project directory then go into it:
mkdir -p ~/Sites/magento
cd $_
# Download the Docker Compose template:
curl -s https://raw.githubusercontent.com/markshust/docker-magento/master/lib/template | bash
# Download the version of Magento (or Mage-OS) you want to use with:
bin/download mageos 3.0.0
# You can also specify the edition (mageos, community, enterprise) and version (3.0.0, 2.4.9, etc.)
# bin/download community 2.4.9
# If no arguments are passed in, the edition defaults to "mageos"
# If no version is specified, it defaults to the most recent version defined in `bin/download`
# or for Magento core development:
# bin/start --no-dev
# bin/setup-composer-auth
# bin/cli git clone git@github.com:magento/magento2.git .
# bin/cli git checkout 2.4-develop
# bin/composer install
# Run the setup installer for Magento:
bin/setup magento.test
# Initialize development environment with sample data and dev-related modules:
bin/init
open https://magento.test
```
#### Existing Projects
```bash
# Create your project directory then go into it:
mkdir -p ~/Sites/magento
cd $_
# Download the Docker Compose template:
curl -s https://raw.githubusercontent.com/markshust/docker-magento/master/lib/template | bash
# Take a backup of your existing database:
bin/mysqldump > ~/Sites/existing/magento.sql
# Replace with existing source code of your existing Magento instance:
cp -R ~/Sites/existing src
# or: git clone git@github.com:myrepo.git src
# Start some containers, copy files to them and then restart the containers:
bin/start --no-dev
bin/copytocontainer --all ## Initial copy will take a few minutes...
# If your vendor directory was empty, populate it with:
bin/composer install
# Import existing database:
bin/mysql < ../existing/magento.sql
# Update database connection details to use the above Docker database credentials:
# Also note: creds for the database server (MariaDB by default) are defined at startup from env/db.env
# vi src/app/etc/env.php
# Import app-specific environment settings:
bin/magento app:config:import
# Create a DNS host entry and setup Magento base url
bin/setup-domain yoursite.test
bin/restart
open https://magento.test
```
### Elasticsearch vs OpenSearch
OpenSearch is set as the default search engine when setting up this project. Follow the instructions below if you want to use Elasticsearch instead:
1. Comment out or remove the `opensearch` container in both the [`compose.yaml`](https://github.com/markshust/docker-magento/blob/master/compose/compose.yaml#L69-L84) and [`compose.healthcheck.yaml`](https://github.com/markshust/docker-magento/blob/master/compose/compose.healthcheck.yaml#L36-L41) files
2. Uncomment the `elasticsearch` container in both the [`compose.yaml`](https://github.com/markshust/docker-magento/blob/master/compose/compose.yaml#L86-L106) and [`compose.healthcheck.yaml`](https://github.com/markshust/docker-magento/blob/master/compose/compose.healthcheck.yaml#L43-L48) files
3. Update the `bin/setup-install` command to use the Elasticsearch rather than OpenSearch. Change:
```
--opensearch-host="$OPENSEARCH_HOST" \
--opensearch-port="$OPENSEARCH_PORT" \
```
to:
```
--elasticsearch-host="$ES_HOST" \
--elasticsearch-port="$ES_PORT" \
```
## Updates
To update your project to the latest version of `docker-magento`, run:
```
bin/update
```
We recommend keeping your docker config files in version control, so you can monitor the changes to files after updates. After reviewing the code updates and ensuring they updated as intended, run `bin/restart` to restart your containers to have the new configuration take effect.
It is recommended to keep your root docker config files in one repository, and your Magento code setup in another. This ensures the Magento base path lives at the top of one specific repository, which makes automated build pipelines and deployments easy to manage, and maintains compatibility with projects such as Magento Cloud.
### Persisting local compose changes across updates
Files shipped by the template (`compose.yaml`, `compose.dev.yaml`, `compose.healthcheck.yaml`) are overwritten by `bin/update`. To keep local Docker Compose tweaks that survive updates, create a `compose.override.yaml` file in your project root. If present, `bin/docker-compose` will automatically include it last in the `-f` chain so its values take precedence.
For example, if port `3306` is already in use on your host and you want to expose the `db` container on `3307` instead:
```yaml
# compose.override.yaml
services:
db:
ports:
- "3307:3306"
```
`bin/update` will not touch `compose.override.yaml`, so your customizations stick around.
### Auto-detected service image versions
When you install Magento or Mage-OS via `bin/download` (or directly through the onelinesetup script), `bin/detect-versions` runs first and pins the PHP, nginx, OpenSearch, database, RabbitMQ, and cache images that match the chosen edition/version. The pins are written to a generated `compose.versions.yaml` that loads after `compose.yaml`/`compose.dev.yaml` so its image tags override the defaults.
Load order (later wins):
```
compose.yaml
compose.healthcheck.yaml
compose.dev.yaml (unless --no-dev)
compose.versions.yaml (auto-generated — gitignored)
compose.override.yaml (your hand-edited overrides — still wins)
```
The source of truth for which images map to which Magento/Mage-OS versions is `compose/lib/versions.tsv` (in this repo's template). One row per supported major.minor; the row's `version` column is a boundary-aware prefix matched against your installed version so all patches roll up to the same row.
**Regenerating manually.** If you upgrade Magento in-place (e.g. `composer require magento/product-community-edition:^2.4.9`), the existing `compose.versions.yaml` may drift from the new version. `bin/start` runs `bin/detect-versions --check` as a non-fatal pre-flight and prints a warning if the file is missing or stale. To regenerate:
```
bin/detect-versions
```
**Hand-edited `compose.yaml` pins.** Because `compose.versions.yaml` loads after `compose.yaml`, a generated pin will override any image you hand-edited in `compose.yaml`. If you have customized image tags in `compose.yaml` and want to keep them, either:
1. don't run `bin/detect-versions` (and `rm compose.versions.yaml` if it was previously generated), or
2. move your image overrides into `compose.override.yaml`, which loads last and wins.
**Backwards compatibility.** `compose.versions.yaml` is optional. Without one on disk, `bin/docker-compose` behaves exactly as it did before — the auto-detect feature only kicks in for new installs or when you explicitly run `bin/detect-versions`. To roll back, delete the file: `rm compose.versions.yaml`.
## Custom CLI Commands
- `bin/analyse`: Run `phpstan analyse` within the container to statically analyse code, passing in directory to analyse. Ex. `bin/analyse app/code`
- `bin/bash`: Drop into the bash prompt of your Docker container. The `phpfpm` container should be mainly used to access the filesystem within Docker.
- `bin/blackfire`: Disable or enable Blackfire. Accepts argument `disable`, `enable`, or `status`. Ex. `bin/blackfire enable`
- `bin/cache-clean`: Access the [cache-clean](https://github.com/mage2tv/magento-cache-clean) CLI. Note the watcher is automatically started at startup in `bin/start`. Ex. `bin/cache-clean config full_page`
- `bin/check-dependencies`: Provides helpful recommendations for dependencies tailored to the chosen Magento version. Reads from `compose/lib/versions.tsv` for currently-supported versions so it stays in sync with `bin/detect-versions`.
- `bin/detect-versions`: Generate a `compose.versions.yaml` that pins service image tags (PHP, nginx, OpenSearch, db, RabbitMQ, cache) to match your installed Magento/Mage-OS version. Run with no args to auto-resolve from `src/composer.json`, or pass `[edition] [version]` explicitly. Add `--check` for a read-only drift check (used as a pre-flight in `bin/start`). See the "Auto-detected service image versions" section above for the load order and override semantics.
- `bin/cli`: Run any CLI command without going into the bash prompt. Ex. `bin/cli ls`
- `bin/clinotty`: Run any CLI command with no TTY. Ex. `bin/clinotty chmod u+x bin/magento`
- `bin/cliq`: The same as `bin/cli`, but pipes all output to `/dev/null`. Useful for a quiet CLI, or implementing long-running processes.
- `bin/composer`: Run the composer binary. Ex. `bin/composer install`
- `bin/configure-linux`: Adds the Docker container's IP address to the system's `/etc/hosts` file if it's not already present. Additionally, it prompts the user to open port 9003 for Xdebug if desired.
- `bin/copyfromcontainer`: Copy folders or files from container to host. Ex. `bin/copyfromcontainer vendor`
- `bin/copytocontainer`: Copy folders or files from host to container. Ex. `bin/copytocontainer --all`
- `bin/create-user`: Create either an admin user or customer account.
- `bin/cron`: Start or stop the cron service. Ex. `bin/cron start`
- `bin/debug-cli`: Run a CLI command inside the `phpfpm-xdebug` container, with Xdebug enabled. Ex. `bin/debug-cli bin/magento indexer:reindex`
- `bin/deploy`: Runs the standard Magento deployment process commands. Pass extra locales besides `en_US` via an optional argument. Ex. `bin/deploy nl_NL`
- `bin/dev-test-run`: Facilitates running PHPUnit tests for a specified test type (e.g., integration). It expects the test type as the first argument and passes any additional arguments to PHPUnit, allowing for customization of test runs. If no test type is provided, it prompts the user to specify one before exiting.
- `bin/dev-urn-catalog-generate`: Generate URN's for PhpStorm and remap paths to local host. Restart PhpStorm after running this command.
- `bin/devconsole`: Alias for `bin/n98-magerun2 dev:console`
- `bin/docker-compose`: Support V1 (`docker-compose`) and V2 (`docker compose`) docker compose command, and use custom configuration files such as `compose.yaml` and `compose.dev.yaml`. Automatically includes `compose.override.yaml` if present, which is a convenient place for local tweaks that should survive `bin/update`.
- `bin/docker-start`: Start the Docker application (either Orbstack or Docker Desktop)
- `bin/docker-stats`: Display container name and container ID, status for CPU, memory usage(in MiB and %), and memory limit of currently-running Docker containers.
- `bin/download`: Download a specific Magento/Mage-OS version from Composer to the container, with optional arguments of the type ("mageos" [default], "community", or "enterprise") and version ([default] is defined in `bin/download`). Ex. `bin/download` (Mage-OS 3.0.0) or `bin/download community 2.4.9`
- `bin/ece-patches`: Run the Cloud Patches CLI. Ex: `bin/ece-tools apply`
- `bin/fixowns`: This will fix filesystem ownerships within the container.
- `bin/fixperms`: This will fix filesystem permissions within the container.
- `bin/get-theme`: Auto-detects a Hyvä theme by finding the single `web/tailwind` folder under `src/app/design/frontend`. Used by `bin/hyva-build`, `bin/hyva-watch`, and `bin/setup-hyva` when no theme directory is passed explicitly; exits non-zero with a message if zero or multiple themes are found.
- `bin/grunt`: Run the grunt binary. Ex. `bin/grunt exec`
- `bin/hyva-build`: Build minified Hyvä/Tailwind CSS for a theme, inside the container. Auto-detects the theme via `bin/get-theme`, or pass a theme directory explicitly. Ex. `bin/hyva-build app/design/frontend/Vendor/Theme`
- `bin/hyva-watch`: Watch and rebuild Hyvä/Tailwind CSS for a theme on change, inside the container. Auto-detects the theme via `bin/get-theme`, or pass a theme directory explicitly.
- `bin/init`: Initialize development environment with sample data and dev-related modules.
- `bin/install-php-extensions`: Install PHP extension in the container. Ex. `bin/install-php-extensions sourceguardian`
- `bin/log`: Monitor the Magento log files. Pass no params to tail all files. Ex. `bin/log debug.log`
- `bin/magento`: Run the Magento CLI. Ex: `bin/magento cache:flush`
- `bin/magento-version`: Determine the Magento version installed in the current environment.
- `bin/mftf`: Run the Magento MFTF. Ex: `bin/mftf build:project`
- `bin/mysql`: Run the MySQL CLI with database config from `env/db.env`. Ex. `bin/mysql -e "EXPLAIN core_config_data"` or`bin/mysql < magento.sql`
- `bin/mysqldump`: Backup the Magento database. Ex. `bin/mysqldump > magento.sql`
- `bin/n98-magerun2`: Access the [n98-magerun2](https://github.com/netz98/n98-magerun2) CLI. Ex: `bin/n98-magerun2 dev:console`
- `bin/node`: Run the node binary. Ex. `bin/node --version`
- `bin/npm`: Run the npm binary. Ex. `bin/npm install`
- `bin/phpcbf`: Auto-fix PHP_CodeSniffer errors with Magento2 options. Ex. `bin/phpcbf <path-to-extension>`
- `bin/phpcs`: Run PHP_CodeSniffer with Magento2 options. Ex. `bin/phpcs <path-to-extension>`
- `bin/phpcs-json-report`: Run PHP_CodeSniffer with Magento2 options and save to `report.json` file. Ex. `bin/phpcs-json-report <path-to-extension>`
- `bin/pwa-studio`: (BETA) Start the PWA Studio server. Note that Chrome will throw SSL cert errors and not allow you to view the site, but Firefox will.
- `bin/redis`: Run a command from the redis container. Ex. `bin/redis redis-cli monitor`
- `bin/remove`: Remove all containers.
- `bin/removeall`: Remove all containers, networks, volumes, and images, calling `bin/stopall` before doing so.
- `bin/removenetwork`: Remove a network associated with the current directory's name.
- `bin/removevolumes`: Remove all volumes.
- `bin/restart`: Stop and then start all containers.
- `bin/root`: Run any CLI command as root without going into the bash prompt. Ex `bin/root apt-get install nano`
- `bin/rootnotty`: Run any CLI command as root with no TTY. Ex `bin/rootnotty chown -R app:app /var/www/html`
- `bin/setup`: Run the Magento setup process to install Magento from the source code, with optional domain name. Defaults to `magento.test`. Ex. `bin/setup magento.test`
- `bin/setup-composer-auth`: Setup authentication credentials for Composer.
- `bin/setup-domain`: Setup Magento domain name. Ex: `bin/setup-domain magento.test`
- `bin/setup-grunt`: Install and configure Grunt JavaScript task runner to compile .less files
- `bin/setup-hyva`: Install npm dependencies (`npm ci`) for a Hyvä theme's Tailwind build. Auto-detects the theme via `bin/get-theme`, or pass a theme directory explicitly.
- `bin/setup-install`: Automates the installation process for a Magento instance.
- `bin/setup-integration-tests`: Script to set up integration tests.
- `bin/setup-nginx`: Update Magento's `nginx.conf` so cookie-triggered Xdebug routing works. Auto-run by `bin/setup`; existing projects can re-run it once to opt in.
- `bin/setup-pwa-studio`: (BETA) Install PWA Studio (requires NodeJS and Yarn to be installed on the host machine). Pass in your base site domain, otherwise the default `master-7rqtwti-mfwmkrjfqvbjk.us-4.magentosite.cloud` will be used. Ex: `bin/setup-pwa-studio magento.test`.
- `bin/setup-pwa-studio-sampledata`: This script makes it easier to install Venia sample data. Pass in your base site domain, otherwise the default `master-7rqtwti-mfwmkrjfqvbjk.us-4.magentosite.cloud` will be used. Ex: `bin/setup-pwa-studio-sampledata magento.test`.
- `bin/setup-ssl`: Generate an SSL certificate for one or more domains. Ex. `bin/setup-ssl magento.test foo.test`
- `bin/setup-ssl-ca`: Generate a certificate authority and copy it to the host.
- `bin/spx`: Disable or enable output compression to enable or disable SPX. Accepts params `disable` (default) or `enable`. Ex. `bin/spx enable`
- `bin/start`: Start all containers, good practice to use this instead of `docker-compose up -d`, as it may contain additional helpers.
- `bin/status`: Check the container status.
- `bin/stop`: Stop all project containers.
- `bin/stopall`: Stop all docker running containers
- `bin/test/unit`: Run unit tests for a specific path. Ex. `bin/test/unit my-dir`
- `bin/test/unit-coverage`: Generate unit tests coverage reports, saved to the folder `dev/tests/unit/report`. Ex. `bin/test/unit-coverage my-dir`
- `bin/test/unit-xdebug`: Run unit tests with Xdebug. Ex. `bin/test/unit-xdebug my-dir`
- `bin/update`: Update your project to the most recent version of `docker-magento`.
- `bin/xdebug`: _Deprecated._ Xdebug now runs in a dedicated `phpfpm-xdebug` container and is triggered by the `XDEBUG_SESSION` cookie — no toggle script is needed. See the Xdebug sections below for setup.
## Misc Info
### Install fails because project directory is not empty
The most common issue with a failed docker-magento install is getting this error:
```
Project directory "/var/www/html/." is not empty error
```
This message occurs when _something_ fails to execute correctly during an install, and a subsequent install is re-attempted. Unfortunately, when attempting a second (or third) install, it's possible the `src` directory is no longer empty. This prevents Composer from creating the new project because it needs to create new projects within an empty directory.
The workaround to this is that once you have fixed the issue that was initially preventing your install from completing, you will need to completely remove the assets from the previously attempted install before attempting a subsequent install.
You can do this by running:
```
bin/removeall
cd ..
rm -rf yourproject
```
Then, create your new project directory again so you can attempt the install process again. The `bin/removeall` command removes all previous Docker containers & volumes related to the specific project directory you are within. You can then attempt the install process again.
### Accessing the Magento Backend
After successfully installing the Magento environment, you can access the backend by following these steps:
1. Open your web browser and go to the following URL: `https://magento.test/admin/`.
2. Use the following default credentials to log in:
- **Username:** `john.smith`
- **Password:** `password123`
3. Upon logging in, you might be prompted to configure Two-Factor Authentication (2FA). This emails you a code to log in with (which you can check with Mailcatcher by visiting `http://{yourdomain}:1080`). By default, the email address used for this purpose is:
- **Email:** `john.smith@gmail.com`
If you are testing in a local development environment and wish to disable 2FA, you can do so by installing [Mark's DisableTwoFactorAuth module](https://github.com/markshust/magento2-module-disabletwofactorauth).
### Caching
For an improved developer experience, caches are automatically refreshed when related files are updated, courtesy of [cache-clean](https://github.com/mage2tv/magento-cache-clean). This means you can keep all of the standard Magento caches enabled, and this script will only clear the specific caches needed, and only when necessary.
To disable this functionality, uncomment the last line in the `bin/start` file to disable the watcher.
### Database
The default database image is MariaDB (`mariadb:11.4` in `compose.yaml`); MySQL is optional (see comments in that file).
The hostname of each service is the name of the service within the `compose.yaml` file. The database service hostname is `db` (not `localhost`) when accessing it from within a Docker container. The `bin/mysql` and `bin/mysqldump` scripts work with MariaDB and MySQL. Elasticsearch's hostname is `elasticsearch`.
To connect to the database CLI tool of the Docker instance, run:
```
bin/mysql
```
You can use the `bin/mysql` script to import a database, for example a file stored in your local host directory at `magento.sql`:
```
bin/mysql < magento.sql
```
You also can use `bin/mysqldump` to export the database. The file will appear in your local host directory at `magento.sql`:
```
bin/mysqldump > magento.sql
```
> Getting an "Access denied, you need (at least one of) the SUPER privilege(s) for this operation." message when running one of the above lines? Try running it as root with:
> ```
> bin/clinotty mysql -hdb -uroot -pmagento magento < src/backup.sql
> ```
> You can also remove the DEFINER lines from the MySQL backup file with:
> ```
> sed 's/\sDEFINER=`[^`]*`@`[^`]*`//g' -i src/backup.sql
> ```
### Composer Authentication
First setup Magento Marketplace authentication (details in the [DevDocs](https://experienceleague.adobe.com/en/docs/commerce-operations/installation-guide/prerequisites/authentication-keys)).
Copy `src/auth.json.sample` to `src/auth.json`. Then, update the username and password values with your Magento public and private keys, respectively. Finally, copy the file to the container by running `bin/copytocontainer auth.json`.
### Email / Mailcatcher
View emails sent locally through Mailcatcher by visiting [http://{yourdomain}:1080](http://{yourdomain}:1080). In order to use mailcatcher, set the mailserver host to `mailcatcher` and set port to `1025`. Note that this port (`1025`) is different from the mailcatcher interface to read the emails (`1080`).
### Redis
Redis is now the default cache and session storage engine, and is automatically configured & enabled when running `bin/setup` on new installs.
Use the following lines to enable Redis on existing installs:
**Enable for Cache:**
`bin/magento setup:config:set --cache-backend=redis --cache-backend-redis-server=redis --cache-backend-redis-db=0`
**Enable for Full Page Cache:**
`bin/magento setup:config:set --page-cache=redis --page-cache-redis-server=redis --page-cache-redis-db=1`
**Enable for Session:**
`bin/magento setup:config:set --session-save=redis --session-save-redis-host=redis --session-save-redis-log-level=4 --session-save-redis-db=2`
You may also monitor Redis by running: `bin/redis redis-cli monitor`
For more information about Redis usage with Magento, <a href="https://devdocs.magento.com/guides/v2.4/config-guide/redis/redis-session.html" target="_blank">see the DevDocs</a>.
### PhpMyAdmin
PhpMyAdmin is built into the `compose.dev.yaml` file. Simply open `http://localhost:8080` in a web browser.
These credentials can be used to log in to PhpMyAdmin:
- **Username:** `magento`
- **Password:** `magento`
### Xdebug & VS Code
Install and enable the PHP Debug extension from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug).
Otherwise, this project now automatically sets up Xdebug support with VS Code. If you wish to set this up manually, please see the [`.vscode/launch.json`](https://github.com/markshust/docker-magento/blame/master/compose/.vscode/launch.json) file.
### Xdebug & VS Code in a WSL2 environment
Install and enable the PHP Debug extension from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug).
Otherwise, this project now automatically sets up Xdebug support with VS Code. If you wish to set this up manually, please see the [`.vscode/launch.json`](https://github.com/markshust/docker-magento/blame/master/compose/.vscode/launch.json) file.
1. In VS Code, make sure that it's running in a WSL window, rather than in the default window.
2. Install the [`PHP Debug`](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug) extension on VS Code.
3. Create a new configuration file inside the project. Go to the `Run and Debug` section in VS Code, then click on `create a launch.json file`.
4. Attention to the following configs inside the file:
* The port must match the `xdebug.client_port` defined in the xdebug container's config. To inspect it, run:
```bash
bin/debug-cli cat /usr/local/etc/php/conf.d/php-xdebug.ini
```
```ini
xdebug.mode = ${XDEBUG_MODE}
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003
xdebug.start_with_request = yes
xdebug.output_dir = /var/www/html/var/profile
xdebug.profiler_output_name = cachegrind.out.%t.%p
```
* The pathMappings should have the same folder path as the project inside the Docker container.
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for XDebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
},
"hostname": "localhost"
}
]
}
```
5. Run the following command in the Windows Powershell. It allows WSL through the firewall, otherwise breakpoints might not be hitten.
```powershell
New-NetFirewallRule -DisplayName "WSL" -Direction Inbound -InterfaceAlias "vEthernet (WSL)" -Action Allow
```
### Xdebug & PhpStorm
Xdebug runs in a dedicated `phpfpm-xdebug` container. Nginx routes requests to it whenever the `XDEBUG_SESSION` cookie is present, so debugging is triggered per-request rather than via a CLI toggle.
1. First, install the [Chrome Xdebug helper](https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc). After installed, right click on the Chrome icon for it and go to Options. Under IDE Key, select PhpStorm from the list to set the IDE Key to "PHPSTORM", then click Save.
2. Open `PhpStorm > Preferences > PHP` and configure:
* `CLI Interpreter`
* Create a new interpreter from the `From Docker, Vagrant, VM...` list.
* Select the Docker Compose option.
* For Server, select `Docker`. If you don't have Docker set up as a server, create one and name it `Docker`.
* For Configuration files, add both the `compose.yaml` and `compose.dev.yaml` files from your project directory.
* For Service, select `phpfpm`, then click OK.
* Name this CLI Interpreter `phpfpm`, then click OK again.
* `Path mappings`
* There is no need to define a path mapping in this area.
3. Open `PhpStorm > Preferences > PHP > Debug` and ensure Debug Port is set to `9000,9003`.
4. Open `PhpStorm > Preferences > PHP > Servers` and create a new server:
* For the Name, set this to **`magento`** — this must match the `PHP_IDE_CONFIG` `serverName` value in `compose/env/phpfpm-xdebug.env` so Xdebug auto-matches this server entry.
* For the Host, set this to the value of your domain name (ex. `magento.test`).
* Keep port set to `80`.
* Check the "Use path mappings" box and map `src` to the absolute path of `/var/www/html`.
5. Go to `Run > Edit Configurations` and create a new `PHP Remote Debug` configuration.
* Set the Name to whatever you like (ex. `magento.test`).
* Check the `Filter debug connection by IDE key` checkbox, select the Server you just setup.
* For IDE key, enter `PHPSTORM`. This value should match the IDE Key value set by the Chrome Xdebug Helper.
* Click OK to finish setting up the remote debugger in PHPStorm.
6. Open up `pub/index.php` and set a breakpoint near the end of the file.
* Start the debugger with `Run > Debug 'magento.test'`, then open up a web browser.
* Ensure the Chrome Xdebug helper is enabled by clicking on it and selecting Debug. The icon should turn bright green.
* Navigate to your Magento store URL, and Xdebug should now trigger the debugger within PhpStorm at the toggled breakpoint.
### SSH
Since version `40.0.0`, this project supports connecting to Docker with SSH/SFTP. This means that if you solely use either PhpStorm or VSCode, you no longer need to selectively mount host volumes in order to gain bi-directional sync capabilities from host to container. This will enable full speed in the native filesystem, as all files will be stored directly in the `appdata` container volume, rather than being synced from the host. This is especially useful if you'd like to sync larger directories such as `generated`, `pub` & `vendor`.
Copy `compose.dev-ssh.yaml` to `compose.dev.yaml` before installing Magento to take advantage of this setup. Then, create an SFTP connection at Preferences -> Build, Execution, Deployment -> Deployment. Connect to `localhost` and use `app` for the username & password. You can set additional options for working with Magento in PhpStorm at Preferences -> Build, Execution, Deployment -> Deployment -> Options.
Note that you must use your IDE's SSH/SFTP functionality, otherwise changes will not be synced. To re-sync your host environment at any time, run:
```
bin/copyfromcontainer --all
```
### Linux
Running Docker on Linux should be pretty straight-forward. Note that you need to run some [post install commands](https://docs.docker.com/install/linux/linux-postinstall/) as well as [installing Docker Compose](https://docs.docker.com/compose/install/) before continuing. These steps are taken care of automatically with Docker Desktop, but not on Linux.
Copy `compose.dev-linux.yaml` to `compose.dev.yaml` before installing Magento to take advantage of this setup.
#### Install necessary dependencies
To ensure proper functionality, the docker-magento setup requires a few system dependencies to be installed on Linux. To install these dependencies, please execute the following command from the terminal:
```
sudo apt install curl libnss3-tools unzip rsync
```
#### The host.docker.internal hostname
The `host.docker.internal` hostname is used on Docker for Mac/Windows to reference the Docker daemon. On Linux, this hostname does not exist.
This hostname is [hard-coded in the php.ini file](images/php/8.1/conf/php.ini#L8). To make this hostname resolve, add `"host.docker.internal:172.17.0.1"` to the `app.extra_hosts` parameter of `compose.yaml`, replacing `172.17.0.1` with the result of:
```
docker run --rm alpine ip route | awk 'NR==1 {print $3}'
```
You must also create a new entry in your `/etc/hosts` file using the same IP:
```
172.17.0.1 host.docker.internal
```
#### Extra settings
To enable Xdebug on Linux, you may also need to open port 9003 on the firewall by running:
```
sudo iptables -A INPUT -p tcp --dport 9003 -j ACCEPT
```
You may also have to increase a virtual memory map count on the host system which is required by [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/vm-max-map-count.html).
Add the following line to the `/etc/sysctl.conf` file on your host:
```
vm.max_map_count=262144
```
### Multi-storefront / multi-domain setup
Magento supports running multiple storefronts from a single codebase by setting `MAGE_RUN_CODE` and `MAGE_RUN_TYPE` per request. There are two common ways to do this locally; pick whichever matches how your production environment is wired. Both rely on the [`compose.override.yaml`](#persisting-local-compose-changes-across-updates) mechanism so your customizations survive `bin/update`.
#### Option 1: nginx `map` (recommended for most setups)
Map each hostname to a run code in an nginx snippet, then mount it into the `app` container via `compose.override.yaml`:
```nginx
# store.map.conf
map $http_host $MAGE_RUN_CODE {
store1.example.test store1_view;
store2.example.test store2_view;
default default;
}
```
```yaml
# compose.override.yaml
services:
app:
volumes:
- ./store.map.conf:/etc/nginx/conf.d/store.map.conf:cached
```
Add the hostnames to `/etc/hosts` and run `bin/setup-ssl store1.example.test store2.example.test`.
#### Option 2: `magento-vars.php` (Adobe Commerce Cloud parity)
If your production environment runs on Adobe Commerce Cloud, it likely uses a `magento-vars.php` file at the project root that's loaded via PHP's `auto_prepend_file`. To mirror that locally, create `src/magento-vars.php` and `src/php.ini`, then wire them up with `compose.override.yaml`:
```php
// src/magento-vars.php
<?php
function isHttpHost(string $host): bool {
return ($_SERVER['HTTP_HOST'] ?? '') === $host;
}
if (isHttpHost('store1.example.test')) {
$_SERVER['MAGE_RUN_CODE'] = 'store1_view';
$_SERVER['MAGE_RUN_TYPE'] = 'store';
}
```
```ini
; src/php.ini
auto_prepend_file = /app/magento-vars.php
```
```yaml
# compose.override.yaml
services:
app:
volumes:
- ./src:/app:cached
- ./src/php.ini:/usr/local/etc/php/conf.d/local-php.ini:cached
phpfpm:
volumes:
- ./src:/app:cached
- ./src/php.ini:/usr/local/etc/php/conf.d/local-php.ini:cached
```
The nginx `map` approach is simpler and provider-agnostic; the `magento-vars.php` approach is worth the extra setup only if you specifically need to match Adobe Commerce Cloud's request lifecycle.
### Varnish
Varnish is disabled by default. Enable it when you want to test a production-like full-page cache setup, tag-based invalidation, or reverse-proxy behavior.
Once enabled, requests flow through Varnish before reaching nginx/PHP:
```text
browser -> nginx :8443 -> varnish :80 -> nginx :8080 -> phpfpm
```
**Enable Varnish:**
1. In `compose.yaml`, uncomment the `varnish` service, the `configs` entry on the `app` service, and the top-level `configs` block at the bottom of the file.
2. In `compose.healthcheck.yaml`, uncomment the `varnish` healthcheck.
3. Configure Magento and restart:
```bash
bin/restart
bin/magento setup:config:set --http-cache-hosts=varnish:80
bin/magento config:set system/full_page_cache/caching_application 2
bin/magento cache:flush
```
**Verify caching:**
```bash
curl -skI https://magento.test/ | grep -i x-magento-cache-debug
```
The first request should return `MISS`; subsequent requests should return `HIT`.
Varnish is also available on port `6081`, and you can inspect requests with:
```bash
bin/docker-compose exec varnish varnishlog
```
The VCL is based on Magento's `varnish7.vcl` template and is located at `template/varnish/default.vcl`. Customize it there and run `bin/restart` to apply changes.
> **Note:** Cache hits bypass PHP, so Xdebug and `cache-clean` only run on cache misses.
**Disable Varnish:**
1. Switch Magento back to the built-in full-page cache:
```bash
bin/magento config:set system/full_page_cache/caching_application 1
```
2. Remove the `http_cache_hosts` entry from `src/app/etc/env.php`, otherwise Magento keeps sending purge requests to the missing `varnish` host on every cache flush.
3. Re-comment the Varnish configuration in `compose.yaml` and `compose.healthcheck.yaml`, then run `bin/restart`.
### Blackfire.io
These docker images have built-in support for Blackfire.io. The Blackfire probe is already installed in the PHP image; the Blackfire agent runs as a separate sidecar container.
To enable it:
1. Uncomment the `blackfire` service in `compose.yaml`.
2. Add your server credentials to `env/blackfire.env`:
```
BLACKFIRE_SERVER_ID={YOUR_SERVER_ID}
BLACKFIRE_SERVER_TOKEN={YOUR_SERVER_TOKEN}
```
3. Add your client credentials to `env/phpfpm.env`:
```
BLACKFIRE_CLIENT_ID={YOUR_CLIENT_ID}
BLACKFIRE_CLIENT_TOKEN={YOUR_CLIENT_TOKEN}
```
4. Restart the containers with `bin/restart`.
After doing so, everything is configured and you can use a browser extension to profile your Magento store with Blackfire.
### Cloudflare Tunnel
These docker images have built-in support for Cloudflare Tunnel. It can be useful for testing implementations that require some third-party integrations involving allow-listing domains. Since your local app cannot be allow-listed by other services, you can use Cloudflare Tunnel to get a public hostname that can be allow-listed on the other service.
To use it:
- First, create a tunnel in Cloudflare Zero Trust and add the token to `env/cloudflare.env`.
- Next, uncomment Cloudflare Tunnel section in main `compose.yaml`.
- Finally, restart the containers with `bin/restart`.
In Cloudflare Tunnel configuration, configure the service URL to use type `HTTPS` and a URL of `{name of app container}:{HTTPS port of app container}`. For examplem, `demo-app-1:8443`. Enable the `No TLS Verify` option, since our local certificates are self-signed. You should now be able to access your app via the public hostname defined in Cloudflare Tunnel.
NOTE: Do not leave instances with Cloudflare Tunnel enabled running long-term, as your instance is publicly available to the world. You should ideally turn off tunnel container once testing is finished.
### MFTF
To work with MFTF you will need to first enable the `selenium` image in the `compose.dev.yaml` file. Then, you will need to run the following.
1. Run mftf build process `bin/mftf build:project`. This should build the basic setup for mftf in your project.
2. Update the `extra_host` values to match your Magento URL and IP in `compose.dev.yaml`.
3. Update the values in `src/dev/tests/acceptance/.env`, including adding the new line `SELENIUM_HOST=selenium` to define the host Codeception should connect to.
4. Run a sample test `bin/mftf run:test AdminLoginSuccessfulTest`.
5. Update your `nginx.conf` file to allow access to the dev section with the following, before the final `deny all` section:
```
location ~* ^/dev/tests/acceptance/utils($|/) {
root $MAGE_ROOT;
location ~ ^/dev/tests/acceptance/utils/command.php {
fastcgi_pass fastcgi_backend;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
```
For debugging, you can connect to the selenium image using a VCN client.
- Connect with the VCN option and `127.0.0.1:5900`, (default password: `secret`)
- Run `bin/mftf doctor` to validate all sections are setup correctly.
Find more info [here](https://devdocs.magento.com/mftf/docs/getting-started.html) about mftf configuration.
### Grunt + LiveReload for Frontend Development
#### Create a new theme and make it active
Create your new theme at `app/design/frontend/VendorName/theme-name`, with the related `composer.json`, `registration.php` and `theme.xml` files.
Make your new theme active at Admin > Content > Design > Configuration. Click the Edit button next to Global Scope, and set the Applied Theme to your new theme name, and click Save Configuration.
#### Load the LiveReload client file
To create a connection to LiveReload, you'll need to insert the LiveReload script into your theme. You can do this by creating a file in your theme at `Magento_Theme/layout/default_head_blocks.xml` with the contents:
```xml
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
<head>
<script defer="true" src="/livereload.js?port=443" src_type="url"/>
</head>
</page>
```
The "?port=443" parameter is important, otherwise the `livereload.js` script won't work.
While we're at it, let's also create an initial LESS file so we have something to test. Create a new file in your theme at `web/css/source/_extend.less` with the contents:
```css
body {
background: white;
}
```
You'll need to clear the Magento cache to enable your module, and make sure this layout XML update is properly loaded.
Your new theme should now be active at `https://yourdomain.test`. Since this is a new theme, it should appear the same as the parent theme defined in your theme.xml file, which is usually Blank.
#### Set up Grunt
Run `bin/setup-grunt`. This will set up the Grunt configuration files for your new theme. It's important to run this step after setting up your new theme, not before.
#### Start the Grunt watcher
Grunt can watch for filesystem changes by running `bin/grunt watch`. You can optionally pass in the `--verbose` or `-v` flag to toggle verbose mode on. This will let you know what's going on under the hood, so you can be sure it is compiling & watching the correct files, and updating them as changes are made.
#### LiveReload Browser extension
Running the `grunt watch` process also spawns the LiveReload server. Your browser needs to connect to this server, and this is done by installing the [LiveReload browser extension](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei?hl=en).
In your browser, be sure to also open the Google Chrome Dev Tools, go to the Network tab, and click "Disable cache". This will ensure the browser does not long-cache static file assets, such as JavaScript & CSS files, which is important during development.
Ensure the LiveReload browser icon has been toggled on, and refresh the page. We can confirm the LiveReload script is loaded by going to the Network tab and ensuring the `livereload.js` file is loaded, and that it also spawns off a new websocket request to `/livereload`.
#### Test LiveReload
Since this is all set, let's update the CSS file to a different background color:
```css
body {
background: blue;
}
```
Upon saving this file, we will see the Grunt watcher detect the changes, and your browser should automatically load the new style without you needing to refresh the page, and without a full browser refresh.
### Hyvä + Tailwind for Frontend Development
[Hyvä](https://hyva.io) themes (e.g. scaffolded from `hyva-themes/magento2-default-theme`) build their CSS with Tailwind rather than Grunt/LESS. A Hyvä theme's Tailwind project lives at `<theme>/web/tailwind`, and its `hyva.config.json` typically scans `vendor/hyva-themes/...` for classes to generate. Since `vendor/` is only present inside the `phpfpm` container, always build with these commands rather than running `npm`/`npx` on the host — a host build reads a stale or missing `vendor/` snapshot and produces incomplete CSS.
#### Install npm dependencies
Run `bin/setup-hyva`. This installs the theme's npm dependencies (`npm ci`, for a reproducible install matching `package-lock.json`) inside the container. Run it once, and again whenever `package-lock.json` changes.
#### One-off build
Run `bin/hyva-build` to generate a minified `web/css/styles.css` for a one-off build, e.g. before a deploy.
#### Watch for changes
Run `bin/hyva-watch` to rebuild `web/css/styles.css` automatically as you edit `web/tailwind/theme/*.css` or `web/tailwind/components/*.css`.
#### Multiple themes
`bin/hyva-build`, `bin/hyva-watch`, and `bin/setup-hyva` all auto-detect the theme directory via `bin/get-theme`, which looks for a single `web/tailwind` folder under `src/app/design/frontend`. If your project has more than one Hyvä theme, pass the theme directory explicitly as the first argument, e.g. `bin/hyva-build app/design/frontend/Vendor/Theme`.
### PHP-SPX
The images also have additional profiler-tracers built-in to the <a href="https://github.com/NoiseByNorthwest/php-spx/tree/master#web-ui" target="_blank">Web UI.</a>
To access the control panel, just open the following URL: `https://magento.test/?SPX_UI_URI=/`
**Suggested Configuration**
- Enabled: Checked
- Automatic start: Checked
- Profile internal functions: Unchecked
- Sampling: 5ms
- Max profiling depth: Unlimited
- Additional metrics: Unselected
Changing any options on this page set cookies for the domain for these settings. After then visiting a page on the frontend, you can navigate back to the GUI and scroll to the bottom of the page, and click the related request to view the trace of the request & response.
Profiling is also possible via command line, or curl:
```
SPX_REPORT=full SPX_ENABLED=1 SPX_SAMPLING_PERIOD=5000 bin/magento {command_name}
curl --cookie "SPX_REPORT=full; SPX_ENABLED=1; SPX_SAMPLING_PERIOD=5000" https://magento.test/
```
Additional information of how to work with SPX is available at https://www.youtube.com/watch?v=xk-JiBLsKfA
## Known Issues
There are currently no large known issues or workarounds needed to use docker-magento with your Magento project. If you find any, please [report them](https://github.com/markshust/docker-magento/issues)!
## Alternatives
### Mappia
If you love using `docker-magento` for local development and are starting to think about how to run Magento in production, [Mappia](https://www.mappia.io/) may be a great next step.
[Mappia](https://www.mappia.io/) is a production-grade tool for deploying Magento onto Kubernetes. It takes the same container-first approach you’re already using locally and extends it to scalable, secure, and repeatable deployments in the cloud—without forcing you to re-architect your application.
If `docker-magento` helps you build Magento locally, [Mappia](https://www.mappia.io/) helps you operate it confidently in production—using the same container mindset, just at production scale.
## Credits
### M.academy
This course is sponsored by <a href="https://m.academy" target="_blank">M.academy</a>, the simplest way to learn Magento.
<a href="https://m.academy" target="_blank"><img src="docs/macademy-logo.png" alt="M.academy"></a>
### Mark Shust
My name is Mark Shust and I'm the creator of this repo. I'm a <a href="https://www.credly.com/users/mark-shust/badges" target="_blank">6X Adobe Commerce Certified Developer</a> and have been involved with Magento since the early days (v0.8!). I create technical education courses full-time for my company, <a href="https://m.academy" target="_blank">M.academy</a>.
- <a href="https://m.academy/courses" target="_blank">🖥️ See my Magento lessons & courses</a>
- <a href="https://m.academy/articles" target="_blank">📖 Read my technical articles</a>
- <a href="https://youtube.com/markshust" target="_blank">🎥 Watch my YouTube videos</a>
- <a href="https://www.linkedin.com/in/MarkShust/" target="_blank">🔗 Connect on LinkedIn</a>
- <a href="https://twitter.com/MarkShust" target="_blank">🐦 Follow me on X</a>
- <a href="mailto:mark@m.academy">💌 Contact me</a>
## License
[MIT](https://opensource.org/licenses/MIT)