Creating a Magento2 Docker Environment: A Complete Guide

Pick the version before you write a line of the compose file, because it decides every image tag. Magento Open Source 2.4.9 reached general availability on 12 May 2026 and Adobe's supported stack for it is PHP 8.5, Composer 2.10, MySQL 8.4 or MariaDB 12.3, OpenSearch 3, Valkey 9, RabbitMQ 4.3, Varnish 8 and nginx 1.30. The 2.4.8 line still covers PHP 8.3 and 8.4 with Elasticsearch 8. Building an environment that mixes versions from two different matrices produces failures that look like Magento bugs but are not.

Keep the environment beside the application, not inside it. A common layout is a docker folder holding the Dockerfiles and service configuration, a compose file at the repository root, an env file for values that differ per developer, and the Magento source in its own directory that gets bind mounted. That separation means you can update nginx configuration or a PHP extension in a reviewable commit without touching store code, and a new developer can read the whole environment in one place before running anything.

The compose file describes the shape of the environment and is identical for everyone. The env file holds the values that legitimately vary or must not be committed: exposed port numbers, the project name, database credentials for local use, and Composer authentication keys. Commit an example env file with safe placeholder values so newcomers know what to fill in, and add the real one to gitignore. Anything secret that reaches production belongs in a proper secret store, not in either file.

Because latest is a moving target. An image tagged latest can change under you between two builds, so a colleague who joins the project next month gets a different database or PHP release than you are running, and Magento's supported matrix is strict about both. Pinning to explicit versions makes the environment reproducible and makes upgrades a deliberate, reviewable change. It also makes a bisect possible when something breaks, because you can point at the commit where the version moved.

Bind mount the source so your editor changes appear immediately and your version control runs on the host. Use named volumes for the things containers own: database files, search indexes and message broker state. The only nuance is performance on Windows and macOS, where bind mounted source crosses a virtualisation boundary. Keep the project inside the WSL2 filesystem on Windows, and use VirtioFS or a synced volume mode on macOS, and the difference becomes small enough to ignore.

Start the containers, then run Composer inside the PHP container to create the project from repo.magento.com using your Adobe authentication keys, then run bin/magento setup:install pointing the database host at the service name and the search host at the OpenSearch service. Follow with dependency injection compilation, static content deployment and a reindex. Doing all of this from inside the container matters, because the host has none of the required PHP extensions and will produce misleading errors.

Because Magento validates the search connection during installation and refuses to continue without it. Either the OpenSearch container is not running, or you pointed Magento at localhost instead of the service name, or the container started and then died from insufficient memory. Check the search container's own logs first. Magento only reports that it could not connect, which tells you nothing about why, and people lose hours editing Magento configuration when the real problem is that the service exited seconds after boot.

They clone the repository, copy the example env file, and run one setup script. That script should build the images, start the stack, install dependencies and either install Magento or import a shared database dump. If any step needs a wiki page to explain it, put it in the script instead. The measure of a good containerised environment is that a new developer reaches a working storefront on their first morning without asking anyone a question.

Commit a sanitised one, or store it where the team can fetch it, but never a raw production dump. Production databases contain customer names, addresses, order history and hashed credentials, and copying them onto laptops turns every developer machine into a data protection liability. Magento ships a sanitisation module for exactly this reason, and there are community tools that strip customer and order data during export. Sanitise once, share the safe artefact, and refresh it on a schedule.

Give them their own container running the same PHP image as the application, with a command that runs Magento's cron or a specific consumer in the foreground. Do not add cron to the web container, because a container should run one process and you want to be able to stop cron independently while debugging. Many developers leave cron off by default and start it only when testing indexing, order emails or scheduled imports, since it otherwise produces log noise on every save.

Stop the stack and remove its volumes, which destroys the database, the search indexes and any queued messages, then run the setup script again. Because everything is scripted, a wrecked environment is a rebuild rather than an investigation. Be aware of what you lose: local admin users, test orders and any configuration you set through the admin panel but never wrote down. Anything you want to survive a reset should be in the repository as a setup script or a data patch.

Yes, and it is one of the strongest arguments for this approach. Give each project a distinct compose project name so container names and networks do not collide, and map each to different host ports or use a shared reverse proxy that routes by hostname. Memory is the real limit, since each stack runs its own database and search engine. Stop the projects you are not actively working on and a normal development laptop handles two or three comfortably.