Magento2 Development in Docker: The Ultimate Guide

Match Adobe's supported matrix for the release you are building against. Magento Open Source 2.4.9 reached general availability on 12 May 2026 and is supported on 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. Developing on a PHP version your production host does not run is a reliable way to ship code that passes locally and fails on deployment.

Developer mode, almost always. It disables static content caching, shows real exceptions instead of a generic error page with a report ID, and regenerates compiled code as you work. Production mode exists to be fast, not to be diagnosable, and debugging in it means every change requires a compile and deploy cycle. The exception is when you are specifically testing performance or reproducing a bug that only appears in production mode, in which case switch deliberately and switch back.

Install the extension in the PHP image, set it to step debug mode, and point the client host back at your machine. On Docker Desktop that is host.docker.internal, and on Linux you add a host gateway entry. Set the IDE key your editor listens for and map the container path to your local path in the IDE, which is the step people miss and the reason breakpoints show as unverified. Keep Xdebug off by default and enable it per request, since always-on Xdebug slows Magento considerably.

The same debugger works, but you have to trigger it explicitly for the CLI process rather than relying on a browser cookie. Set the Xdebug trigger environment variable when you run the command inside the container, and start listening in your IDE first. This is how you debug indexers, data patches, cron jobs and consumers, which is where the genuinely difficult Magento bugs live. Debugging a consumer also means running it in the foreground rather than under the supervisor that normally restarts it.

Work through the layers in order. Magento's own caches, then generated code in the generated folder, then static content in pub/static, then OPcache holding a stale compiled file, then Varnish if it is running. In developer mode most of those are handled for you, which is why developer mode exists. If a change genuinely will not appear after flushing caches, check that you edited the file inside the bind mounted path the container sees, not a copy somewhere else on your machine.

Only when the thing you are testing depends on it, which is more often than people expect. Indexer updates on schedule, order confirmation emails, scheduled imports, admin notifications and several third party integrations only happen when cron runs. Give cron its own container so it can be started and stopped independently, and leave it off while doing template work to keep the logs quiet. Then turn it on before you conclude a feature works, because plenty of bugs only appear on the cron path.

In a dedicated container running in the foreground, one process per consumer group you care about, rather than relying on cron to spawn them. That makes their output visible and lets you restart a single consumer after a code change, which matters because consumers hold compiled code in memory and will keep running your old logic until restarted. Forgetting to restart a consumer after editing its class is one of the most common and most confusing wasted afternoons in Magento development.

Run it inside the PHP container, as the same user that owns the files, never as root. Composer writes into vendor, generated and var, and a root-owned file there produces a permission error later that looks completely unrelated to the command that caused it. Building the PHP image with a user whose numeric ID matches your host account solves it permanently on Linux. Keep auth.json mounted and readable by that user, otherwise Composer fails against repo.magento.com with an unhelpful authentication error.

Yes, and you should, because they need the same PHP version and extensions the application uses. Unit tests run against the code alone, while integration tests need a separate test database and a working search connection, which is exactly the kind of setup containers make repeatable. Running static analysis and code sniffing in the container too means the version everyone runs locally matches the version CI runs, so nobody has a pull request rejected by a tool that passed on their machine.

Give each project its own compose project name and its own stack, so a client on an older Magento release with Elasticsearch and PHP 8.2 coexists with one on 2.4.9 with OpenSearch 3 and PHP 8.5. Nothing is installed on your host, so there is no version to switch. Stop the stacks you are not using, because each runs a database and a search engine and memory is the real constraint. A shared reverse proxy routing by hostname avoids juggling port numbers.

Sanitise it before it leaves production. A raw dump contains customer names, addresses, order history and hashed credentials, and copying it to laptops turns every developer machine into a data protection exposure. Magento ships a sanitisation module, and community tools can strip customer and sales data during export. Import the sanitised dump into your database container, reindex, and switch the base URLs to your local domain. Keep a refreshed sanitised dump somewhere the team can fetch rather than passing files around.

Almost always file sharing rather than PHP. Magento reads a very large number of small files per request, and every one of those reads crosses a virtualisation boundary when your source lives on a shared host folder. On Windows, move the project inside the WSL2 filesystem instead of under the C drive, which alone can transform performance. On macOS, use VirtioFS file sharing or a synced volume mode offered by setups such as docker-magento. Databases and search indexes should live in named volumes, never on a bind mount.