Running Magento2 with Docker Compose: A Step-by-Step Guide

Use docker compose with a space. Compose is now a plugin inside the Docker CLI, and the old standalone docker-compose binary written in Python is version 1, which reached end of life and is no longer shipped or supported. Any guide that tells you to install docker-compose separately predates that change. The compose file format itself did not break, so existing files keep working, but write your scripts, aliases and documentation against the plugin form or they will fail on a clean install.

No. The top level version field is obsolete and current versions of Compose ignore it, warning if it is present. It dates from the era when the file format was numbered and the tool chose behaviour from that number. Modern Compose reads the file as the current specification. Removing the line is safe and tidies up the warning noise on every command, which matters because real warnings get lost in a wall of ignorable ones.

Decide explicitly, then pin every image. Magento Open Source 2.4.9 became generally available on 12 May 2026 and Adobe's supported stack 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. If you are still on 2.4.8, that line covers PHP 8.3 and 8.4 with Elasticsearch 8. A compose file that quietly mixes services from both matrices will install and then fail in ways that look like application bugs.

Less than most people assume. By default it only controls start order, not readiness, so Magento can start before MySQL is accepting connections and the install fails on a refused connection. The fix is a health check on the database and search services plus a depends_on condition that waits for that health check to pass. This single change removes most of the flaky first-run failures that people work around by running the setup command twice.

Use Compose profiles. Tag Varnish, RabbitMQ, the mail catcher and anything else optional with a profile name, and they stay stopped unless you explicitly request that profile. One repository then serves a front end developer who wants four containers and a backend developer who wants eight, without maintaining two compose files. It is much better than commenting services out, because commented-out configuration rots and nobody notices until they uncomment it.

Compose automatically merges a compose.override file on top of the base one, which lets you keep shared configuration committed and personal adjustments local. Exposed ports, extra debugging settings and an editor specific mount belong there. It is the clean answer to the situation where one developer needs the database on a different port because something else on their machine already uses it, and they currently solve it by editing the shared file and remembering not to commit.

Stop halts the containers and leaves them, so starting again is quick and everything is preserved. Down removes the containers and the project network. Neither deletes named volumes unless you add the volumes flag, which is the command that wipes your database and search indexes. Knowing that distinction saves real work, because people reach for the most destructive form out of habit and then wonder why they are reinstalling Magento every few days.

By service name, not localhost. Compose puts every service on a private network and registers each under its name, so the database host is db or mysql and the search host is opensearch. Inside a container, localhost means that container. This is the single most common configuration error when someone moves a working manual installation into Compose, because the old env.php still says 127.0.0.1 and Magento reports a connection refused with no hint about why.

Something on your host is already listening on that port, often another Magento project's stack, a locally installed MySQL, or a previous run that did not shut down. Map the service to a different host port in your override file, or stop the conflicting stack. On a machine that runs several projects, the durable answer is to stop publishing database and search ports at all, since you rarely need them from the host, and to route web traffic through a single shared reverse proxy that dispatches by hostname.

Use docker compose exec against the PHP service, running as the file-owning user rather than root. Running bin/magento as root is a habit worth breaking, because it leaves root-owned files in var and generated that the web server user can then no longer write, producing permission errors that appear minutes later and look unrelated. Wrap the whole invocation in a short script inside your repository so everyone on the team runs it the same way.

Rarely for PHP, sometimes for consumers. Compose can start multiple instances of a service, which is genuinely useful for testing that queue consumers behave correctly when several run in parallel, a real source of production bugs. Scaling PHP FPM locally does little, because your bottleneck is a single developer's requests and your machine's memory, not concurrency. Treat scaling as a correctness testing tool locally, and leave real horizontal scaling to your production orchestrator.

Read its logs before changing anything. Compose can follow the output of one service or all of them, which usually names the problem outright: a database rejecting a data directory created by a different major version, a search engine exiting on memory, or PHP FPM failing to start because of a syntax error in a mounted configuration file. Magento's own exception log is the second place to look, not the first, because a dead dependency never reaches Magento's error handling at all.