Magento 2 Docker Setup Tutorial
Docker allows developers to package applications into lightweight, portable containers that run virtually anywhere. This makes deployment much easier. With Docker, you avoid “works on my machine” problems since the containers include everything needed to run the application. Magento 2 Docker Configuration can help make this process even smoother for Magento developers, as it allows them to easily create and manage Magento 2 environments in a containerized setup.
Magento 2 includes official Docker images to simplify local development and testing. You can configure Docker to run Magento 2 with MySQL, Elasticsearch, and other services required. This provides an environment identical to production for building and testing modules, themes, and customizations.
In this comprehensive guide, we will cover how to install Docker and use it for Magento 2 development.
Prerequisites
Before starting, make sure you have the following:
1. Docker – Docker allows you to run applications and services in isolated containers. Install Docker Community Edition (CE) for your operating system:
2. Docker Compose – Used to configure relationships between containers and networking. This is included in Docker for Mac and Windows installs. For Linux, follow these instructions.
3. Magento Code – You’ll need the Magento 2 code base to mount into your Docker containers. You can get this via:
- Downloading a Magento release
- Cloning the Magento 2 GitHub repository
- Your own existing Magento project code base
How to Configure Magento 2 Docker: A Step-by-Step Guide
Follow the steps below to configure Magento 2 Docker:
- Setup Docker Network
- MySQL Container
- PHP Container
- Nginx Web Server
- Test It Out
- Finish Installation
- Elasticsearch Container
- Connect Magento to Elasticsearch
- Redis for Cache and Sessions
- Configure Redis in Magento
- MailHog for Email Catching
- RabbitMQ for Message Queuing
- Deploy Static Assets
- Finalizing Configuration
Step 1 – Setup Docker Network
We need to create a Docker network that allows all the containers to communicate with each other. This assigns IP addresses to each container on a private network.
Run the following to create a network called m2net:
docker network create m2net
Step 2 – MySQL Container
Magento requires MySQL or MariaDB so we need to run one in a Docker container.
Use the following docker run command to start a MySQL container with some custom configuration:
docker run -d --name mysql \
-v mysql:/var/lib/mysql \
-e MYSQL_ROOT_PASSWORD=magento2 \
-e MYSQL_DATABASE=magento2 \
--network m2net \
-p 3306:3306 \
mysql:5.7
- -d – Run the container in detached mode (in the background)
- –name mysql – Names the container mysql for easy reference
- -v mysql:/var/lib/mysql – Mounts a volume for persisting database data after container stops
- -e MYSQL_ROOT_PASSWORD=magento2 – Sets a root password for MySQL
- -e MYSQL_DATABASE=magento2 – Creates a magento2 database
- –network m2net – Connects the container to our Docker network
- -p 3306:3306 – Exposes port 3306 to host machine for external connections
- mysql:5.7 – Uses the mysql image tagged 5.7 from Docker Hub
Step 3 – PHP Container
Next we’ll create a PHP-FPM container. This handles processing PHP requests for Magento.
docker run -d --name php \
-v ~/your/magento/code:/var/www/html \
--network m2net \
-p 9000:9000 \
php:7.2-fpm
- -d – Detached mode
- –name php – Container name
- -v ~/your/magento/code:/var/www/html – Mounts the host machine Magento code into the container
- –network m2net – Connects to our network
- -p 9000:9000 – Exposes FastCGI port 9000
- php:7.2-fpm – Uses official PHP 7.2 FPM image
This gives PHP a way to access the Magento codebase. We don’t have a web server yet, so PHP won’t receive any requests.
Step 4 – Nginx Web Server
To serve the Magento site and handle requests, we need a web server. For Docker, we’ll use Nginx.
docker run -d --name nginx \
-v ~/your/magento/code:/var/www/html:ro \
--network m2net \
-p 8080:80 \
nginx:stable-alpine
- -d – Detached
- –name nginx – Name
- -v ~/your/magento/code:/var/www/html:ro – Mount Magento code read-only
- –network m2net – Connect to network
- -p 8080:80 – Expose port 80 to host as 8080
- nginx:stable-alpine – Use Nginx image
Now we have a way to handle HTTP requests to serve pages. Nginx will pass PHP requests to the PHP-FPM container.
Step 5 – Test It Out
At this point, we have 3 containers running:
- MySQL – Database
- PHP – Processing PHP code
- Nginx – Web server
To test it out, go to http://localhost:8080 on your host machine. You should see the Magento installation page.
We don’t have integration with Elasticsearch up and running yet, so some things may not work fully. But the basic LAMP services are now running our Magento site via Docker.
Step 6 – Finish Installation
The Magento installation can be finished directly from the web page. But we need to configure it to use our Docker MySQL container.
In the Installation Wizard in the web browser, use the following for your database configuration:
- Host – mysql
- Username – root
- Password – magento2
- Database – magento2
After finishing the installation, Magento should now be fully running on Docker containers.
Step 7 – Elasticsearch Container
For full functionality, Magento 2 requires Elasticsearch. This provides searching, indexing, and advanced analytics.
Docker Hub has an official Elasticsearch image we can use:
docker run -d --name elasticsearch \
-e "discovery.type=single-node" \
--network m2net \
-p 9200:9200 -p 9300:9300 \
elasticsearch:7.6.2
- -d – Detached
- –name elasticsearch – Container name
- -e “discovery.type=single-node” – Configure as single node cluster
- –network m2net – Join network
- -p 9200:9200 -p 9300:9300 – Expose ports for API and nodes
- elasticsearch:7.6.2 – Use Elasticsearch 7.6.2 image
This will provide a full Elasticsearch instance in a container.
Step 8 – Connect Magento to Elasticsearch
Now that the Elasticsearch container is up and running, we need to configure Magento to use it for catalog search.
- Login to the Magento Admin and navigate to Stores > Configuration > Catalog > Catalog > Catalog Search.
- In the Elasticsearch section:
- Set Enable Elasticsearch to Yes.
- For Elasticsearch Server Hostname, enter elasticsearch.
- Set Elasticsearch Server Port to 9200.
- Click Test Connection to verify connectivity.
- When testing succeeds, click Save Config at the top to apply the changes.
Magento is now configured to use the Elasticsearch container for catalog search functionality including suggestions, relevance matching, and advanced filtering.
Step 9 – Redis for Cache and Sessions
Redis provides fast in-memory storage that can be used for caching and session storage.
Run a Redis container:
docker run -d --name redis \
--network m2net \
-p 6379:6379 \
redis:5.0-alpine
- -d – Detached
- –name redis – Name
- –network m2net – Connect to network
- -p 6379:6379 – Expose port 6379
redis:5.0-alpine – Use Alpine-based Redis 5.0 image
Step 10 – Configure Redis in Magento
To configure Magento to use the Redis container:
- In Magento admin, go to Stores > Configuration > Advanced > System > Cache Management
- Set “Caching Application” to Redis
- Configure the following Redis settings:
- Redis Server: redis
- Redis Port: 6379
- Go to Stores > Configuration > Advanced > System > Session Storage Management
- Set “Use Redis Session Storage” to Yes
- Configure the Redis server and port the same as previous step
- Click “Save Config”
Now Magento will utilize Redis for caching and session storage for better performance.
Step 11 – MailHog for Email Catching
When testing Magento, it can be useful to catch all outgoing email instead of actually sending it.
MailHog provides a fake SMTP server that catches email and displays it through a web interface.
Run a MailHog container:
docker run -d --name mailhog \
--network m2net \
-p 1025:1025 -p 8025:8025 \
mailhog/mailhog
To configure Magento to send email via MailHog:
- Go to Stores > Configuration > Advanced > System > Mail Sending Settings
- Set “Disable Email Communications” to No
- Set “Set Return-Path” to Yes
- Set “Set Return-Path Email” to any valid email address
- Set “SMTP Host” to mailhog
- Set “SMTP Port” to 1025
Step 12 – RabbitMQ for Message Queuing
Magento utilizes RabbitMQ for managing queued jobs like indexers, email sending, cron jobs, etc.
docker run -d --hostname rabbitmq --name rabbitmq \
--network m2net \
-p 5672:5672 -p 15672:15672 \
rabbitmq:3-management
- -d – Detached
- –hostname rabbitmq – Hostname
- –name rabbitmq – Container name
- –network m2net – Connect to network
- -p 5672:5672 -p 15672:15672 – Expose ports
- rabbitmq:3-management – RabbitMQ with management plugin
In Magento admin:
- Go to Stores > Configuration > Advanced > System > MQ
- Set “Enable MQ” to Yes
- Set the following values:
- Transport Type: AMQP
- AMQP Host: rabbitmq
- AMQP Port: 5672
- AMQP User: guest
- AMQP Password: guest
docker exec -it nginx bash
cd /var/www/html
bin/magento setup:static-content:deploy
This connects to the running Nginx container and deploys assets from the mounted Magento code.
Assets are now served directly by Nginx for maximum performance.
Step 14 – Finalizing Configuration
Some final steps to complete the Docker setup:
- Set proper permissions on mounted code directories
- Configure a cron job or scheduler to run Magento cron
- Configure xDebug if needed for debugging
- Enable SSL with a reverse proxy
- Configure Nginx for caching and compression
- Implement optimal performance best practices
Final Thoughts
Magento 2 Docker Configuration is a powerful tool for developers and businesses looking to streamline their Magento 2 deployment process. By containerizing the application and its dependencies, it simplifies the setup, ensures consistency across environments, and improves scalability.
The ability to easily spin up and tear down environments allows for more efficient testing and deployment, ultimately saving time and resources. As Magento 2 continues to evolve, the importance of Magento 2 Docker Configuration will only grow, making it an essential part of any modern Magento 2 development and deployment workflow.
Embracing this technology can provide a significant competitive advantage for organizations seeking to optimize their Magento 2 operations.
FAQs
Here are some sample FAQs related to Magento 2 Docker configuration:
What are the benefits of using Docker for Magento 2?
Docker provides portability, speed of setup, and standardization for Magento 2 environments. Containers make development, testing, and deployment more efficient.
What core components need Docker configurations?
Magento 2 application, MySQL database, PHP-FPM, Varnish cache, Elasticsearch, and other services need Docker Compose files, Dockerfiles, and configuration.
How can I optimize Magento 2 performance with Docker?
Use separate containers for each process, utilize layer caching in Dockerfiles, and leverage Docker volume mounts for configurable performance gains.
What Docker base images work best for Magento 2?
Official PHP, Nginx, MySQL, and Elasticsearch images from Docker Hub work well. You can also extend them with customizations.
How do I manage credentials and secrets with Docker containers?
Use Docker secrets and configs to securely inject sensitive data, such as passwords, into containers at runtime. Avoid baking secrets into Docker images.
What troubleshooting tips help debug Magento on Docker?
Use Docker logs and exec commands to inspect running containers. Make sure file permissions are set properly. Enable developer mode for verbose logging.
