Setting up Magento 2 by hand is a puzzle. Learn how to install and configure Docker for Magento 2, step by step, for a clean dev environment.
On this page
Magento2 is a powerhouse for eCommerce, but setting up its development environment can feel like solving a puzzle. You need to install and configure multiple services like Apache/Nginx, MySQL, PHP, Elasticsearch, and Redis – each with its own quirks. This manual process is time-consuming and prone to errors.
Enter Docker, the ultimate solution for simplifying Magento2 development. Docker allows you to create an isolated, pre-configured environment in minutes, so you can focus on building your store instead of wrestling with configurations. In this guide, we’ll walk you through installing Docker for Magento2, step by step.
Why Use Docker for Magento2?
At Raulji Technologies, we swear by Docker for Magento2 development. As Yuvraj Raulji, our Magento2 expert, puts it: “Docker eliminates the frustration of manual setups and ensures consistency across all environments.” Here’s why Docker is a game-changer
- Faster Setup: Get a Magento2 store running in minutes, not hours.
- Environment Consistency: Avoid the dreaded “it works on my machine” problem.
- Easy Scaling: Add or remove services like Redis or Elasticsearch with a single command.
- Less Configuration: Prebuilt Docker images save time and reduce errors.
Step 1: Install Docker & Docker Compose
Before we dive into Magento2, let’s install Docker and Docker Compose on your system. Docker Compose is a tool that helps you manage multiple containers (like PHP, MySQL, and Nginx) as a single service.
For Windows & macOS
- Download Docker Desktop from the https://www.docker.com
- Run the installer and follow the setup instructions.
- For Windows users, enable the WSL 2 Backend for better performance.
- Verify the installation by opening a terminal and running:docker –version
docker-compose –version - You should see the installed versions of Docker and Docker Compose.
For Linux (Ubuntu/Debian-based systems)
- Open your terminal and run the following commands:sudo apt update
sudo apt install -y docker.io docker-compose
sudo systemctl start docker
sudo systemctl enable docker - Verify the installation:docker –version
docker-compose –version
Step 2: Set Up Magento2 with Docker
Now that Docker is installed, let’s set up a basic Magento2 environment using Docker Compose.
Create a New Directory for Magento2
Open your terminal and run:
mkdir magento-docker && cd magento-dockerCreate a docker-compose.yml File
This file defines all the services your Magento2 store needs. Create a file named docker-compose.yml and add the following content:
version: ‘3.7’
services:
app:
image: magento/magento2
ports:
– “80:80”
environment:
MYSQL_HOST: db
MYSQL_USER: magento
MYSQL_PASSWORD: magento
MYSQL_DATABASE: magento
volumes:
– ./app:/var/www/html
db:
image: mysql:5.7
environment:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: magento
MYSQL_USER: magento
MYSQL_PASSWORD: magentoStart the Docker Containers
Run the following command to start the containers:
docker-compose up -d- This will download the necessary Docker images and start the Magento 2 and MySQL containers.
Step 3: Access Magento 2 in Your Browser
Once the setup is complete, open your browser and go to:
You should see your Magento2 store up and running!
What’s Happening Under the Hood?
Magento2 Container:
This container runs the Magento 2 application using PHP and Nginx.
MySQL Container:
This container handles the database for your Magento 2 store.
Volumes:
The ./app:/var/www/html line ensures that your Magento 2 files are stored on your local machine, so they persist even if the container is restarted.
Environment Variables:
These are used to configure database credentials and other settings.
Advanced Tips for Docker and Magento2
- Add More Services: Need Redis for caching or Elasticsearch for advanced search? Just add them to your docker-compose.yml file. For exampleredis:
image: redis:latest
elasticsearch:
image: elasticsearch:7.9.3 - Use Custom Docker Images: If you need specific PHP extensions or configurations, create a custom Docker image. Here’s an example Dockerfile:FROM php:7.4-fpm
RUN docker-php-ext-install pdo_mysql - Optimize Performance: Use Docker’s resource limits to allocate CPU and memory to your containers. For exampleapp:
image: magento/magento2
deploy:
resources:
limits:
cpus: ‘2’
memory: 4G - Backup Your Data: Use Docker volumes to back up your Magento2 database and files. For example:docker-compose exec db mysqldump -u magento -pmagento magento > backup.sql
Conclusion
Congratulations! You’ve successfully installed Docker and set up Magento2 in a containerized environment. This setup ensures that your Magento2 development is faster, more reliable, and free from configuration issues.
At Raulji Technologies, we use Docker to enhance our Magento2 development process, and we highly recommend it to every Magento developer. Stay tuned for more guides from Yuvraj Raulji on optimizing and deploying Magento2 with Docker.
Frequently Asked Questions
Answers to the questions we hear most often.
Are the versions in this installation guide still current?
Update them before you install. Magento Open Source 2.4.9 became generally available on 12 May 2026, and Adobe's supported stack for that release 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 is the one that still lists PHP 8.3 and 8.4 alongside Elasticsearch 8. Decide which release you are targeting first, then pin every image tag to match it. Installing against an unsupported combination is the single most common cause of a failed first setup.
Do I need Docker Desktop or just Docker Engine?
On Linux you only need Docker Engine and the Compose plugin, both open source and free. On Windows and macOS, Docker Desktop is the practical choice because it supplies the Linux virtual machine, the file sharing layer and the networking that containers need. Remember the licence: Docker Desktop is free for personal use, education, open source and small businesses under 250 employees and under 10 million dollars in annual revenue, and requires a paid subscription above that. Alternatives such as Colima, Rancher Desktop and Podman exist if licensing is a blocker.
Is docker-compose still a separate command?
No, and this trips people up when following older guides. Compose is now a plugin built into the Docker CLI, invoked as docker compose with a space, not the standalone docker-compose binary written in Python. The old v1 command reached end of life and is no longer supported or installed by default. If a tutorial tells you to install docker-compose separately, it predates the change. The file format is compatible, so your compose file works either way, but write scripts and documentation against docker compose so they keep working.
Why does Magento need Composer authentication keys?
Magento's own packages are distributed from repo.magento.com, which is authenticated even for Magento Open Source. You generate a public and private key pair from your Adobe Commerce Marketplace account and store them in auth.json. Inside Docker, that file has to be readable by the container user running Composer, which is why installs often fail with a 401 the first time. Mount it in or pass the keys as environment variables. Never commit auth.json to a public repository, because those keys identify your account and can be used by anyone who finds them.
What does the first Magento install actually do inside the container?
Composer downloads the codebase and its dependencies, then bin/magento setup:install writes the env.php configuration, creates roughly 500 database tables, sets the admin user and base URL, and registers the search engine connection. After that you still need to compile dependency injection, deploy static content and reindex before the storefront renders properly. This is why a first run takes many minutes rather than seconds, and why it is worth snapshotting the resulting database and generated files so subsequent environment rebuilds restore instead of reinstalling.
Why is my Magento site slow or unresponsive right after installing?
Almost always because it is in developer mode with caches disabled and static content generated on demand. Every page request is then compiling less files and generating static assets in real time. Switch to production mode, or at least run setup:static-content:deploy and enable caching, and the same environment becomes usable. The second common cause is an under-resourced Docker allocation, where OpenSearch and MySQL are competing for memory. Check container stats before assuming the code is at fault.
Why do I get permission denied errors on var, generated or pub/static?
Because the container's web server user and your host user have different numeric IDs, so files written by one are unwritable by the other. On Linux this is the number one Docker Magento frustration. Fixes include building the PHP image with a user whose UID and GID match your host account, running Magento's file permission commands after install, or using a setup such as docker-magento that handles the mapping for you. Do not solve it with a blanket 777, because that permission set is unsafe and Magento will warn about it.
Why does the container exit immediately after starting?
A container runs exactly one foreground process and stops when that process stops. If your PHP or nginx container exits at once, the command it was given finished or crashed. Read the logs with docker compose logs for that service rather than guessing. OpenSearch is a frequent offender: it fails on an insufficient memory allocation or on the host's vm.max_map_count being too low, and it dies quietly. Databases can also exit if a mounted data volume was created by a different major version of MySQL or MariaDB.
Why does image pulling fail with a toomanyrequests error?
You have hit Docker Hub's pull limit. Unauthenticated pulls are capped at 100 per six hours per IPv4 address or IPv6 slash 64 subnet, a free Docker Personal account raises that to 200 per six hours, and paid subscriptions are unlimited. An office behind one public IP, or CI that rebuilds from scratch on every push, exhausts that quota faster than you would expect. Run docker login before pulling, keep a local image cache, and consider a pull-through registry mirror for build agents.
How do I run Magento CLI commands inside Docker?
Execute them in the PHP container rather than on your host, because the host has no Magento dependencies. Use docker compose exec, target the PHP service, and run bin/magento as the same user that owns the files. Wrapping this in a short shell alias or a bin script in your repository saves a lot of typing and prevents the classic mistake of running a command as root, which leaves root-owned files in var and generated that the web server can no longer write.
How do I set up Xdebug in a Magento Docker environment?
Install the extension in the PHP image, then configure it in step debug mode pointing back at your host. On Docker Desktop the host is reachable as host.docker.internal, while on Linux you usually add a host gateway mapping. Set an IDE key your editor expects and listen on the standard port. Keep Xdebug switched off by default and enable it per request or per CLI command, because leaving it always on slows Magento noticeably. Most maintained Magento Docker setups already ship a toggle command for this.
How do I reset a broken Magento Docker environment?
Stop the stack and remove its volumes, which deletes the database and search indexes, then start again from your setup script. This is the advantage of a scripted environment: a broken state is a five minute rebuild rather than an afternoon of archaeology. Keep a database dump of a known good install so you can restore rather than reinstall. Be deliberate about it though, since removing volumes destroys any local data you have not exported, including test orders and admin users.
