Magento 2 en Docker — lokale development setup die werkt

Magento 2 lokaal draaien zonder Docker kost je gemiddeld 4 uur per developer per week aan omgevingsproblemen. Met de juiste Docker-setup verdwijnt dat. Hoe je het correct inricht.

Magento 2 en Docker — lokale development setup die werkt

4 uur per week. Dat is wat een gemiddelde developer kwijt is aan omgevingsproblemen als Magento 2 lokaal draait zonder Docker. Verschillende PHP-versies, conflicterende Elasticsearch-instanties, een collega die een andere macOS-versie heeft — de lijst is eindeloos.

Docker lost dit op. Maar een slechte Docker-setup maakt alles juist trager. Op macOS is een naïeve Docker-configuratie 3-5x langzamer dan native Linux. Dit artikel legt uit hoe je het goed doet.

Wat je leert in dit artikel

De basisarchitectuur van een Magento 2 Docker-setup
Warden vs. een custom docker-compose aanpak
Performance-optimalisaties specifiek voor macOS
Debugging binnen containers

De basisarchitectuur

Een Magento 2 ontwikkelomgeving heeft de volgende services nodig:

PHP-FPM (7.4, 8.1 of 8.2 afhankelijk van je Magento-versie)
Nginx of Apache als webserver
MySQL 8.0 of MariaDB 10.4+
Elasticsearch 7.x of OpenSearch 2.x (verplicht vanaf Magento 2.4)
Redis voor sessies en cache
RabbitMQ als je message queues gebruikt

Dit is de minimale docker-compose.yml voor Magento 2.4:

yaml

version: '3.8'

services:
  nginx:
    image: nginx:1.25-alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./src:/var/www/html:cached
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - php

  php:
    build:
      context: ./docker/php
      args:
        PHP_VERSION: "8.2"
    volumes:
      - ./src:/var/www/html:cached
      - ~/.composer:/var/www/.composer:cached
    environment:
      - PHP_MEMORY_LIMIT=4G
      - XDEBUG_MODE=off

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: magento
      MYSQL_DATABASE: magento
      MYSQL_USER: magento
      MYSQL_PASSWORD: magento
    volumes:
      - mysql_data:/var/lib/mysql
    ports:
      - "3306:3306"

  elasticsearch:
    image: elasticsearch:7.17.9
    environment:
      - discovery.type=single-node
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
    volumes:
      - es_data:/usr/share/elasticsearch/data
    ports:
      - "9200:9200"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  mysql_data:
  es_data:

Warden vs. custom docker-compose

Er zijn twee populaire aanpakken voor Magento 2 met Docker: Warden (een CLI-tool van Alistair Shepherd) en een zelfgebouwde docker-compose setup.

Aspect	Warden	Custom docker-compose
Opstarttijd	Snel, alles voorgedefinieerd	Meer tijd om in te richten
Flexibiliteit	Beperkt, conventies verplicht	Volledig vrij
macOS performance	Mutagen ingebouwd	Handmatig configureren
Meerdere projecten	Automatisch via Traefik	Handmatig poortnummers beheren
Team-onboarding	Eén commando	Meer documentatie nodig

Warden is ideaal als je snel wilt starten en je team de Warden-conventies accepteert. Voor projecten met afwijkende requirements of complexe setups is een custom docker-compose flexibeler.

Warden installeren

bash

# Installeer Warden via Homebrew
brew install wardenenv/warden/warden

# Start de globale services (Traefik, DNS, CA)
warden svc up

# Initialiseer een nieuw Magento-project
cd ~/projects/mijnwinkel
warden env-init mijnwinkel magento2

# Start de omgeving
warden env up

Na warden env up draait je omgeving op https://app.mijnwinkel.test met een geldig lokaal SSL-certificaat.

Performance op macOS: het bindmount-probleem

Docker op macOS is traag. Niet een beetje traag — structureel traag. De oorzaak is de virtualisatielaag tussen macOS en de Linux-kernel waarop Docker draait. Elk bestandssysteem-I/O-verzoek gaat via deze laag.

Een bin/magento cache:flush duurt op een naïeve setup op macOS 45 seconden. Op Linux duurt hetzelfde commando 4 seconden.

Er zijn drie oplossingen:

1. Mutagen (aanbevolen voor macOS)

Mutagen synchroniseert bestanden asynchroon tussen je macOS-bestandssysteem en de Docker-volume. Het voelt als native snelheid.

yaml

# In je docker-compose.yml
services:
  php:
    volumes:
      - magento:/var/www/html  # Volume, geen bindmount

volumes:
  magento:
    driver: local
    driver_opts:
      type: none
      device: ${PWD}/src
      o: bind

Warden gebruikt Mutagen automatisch. Bij een custom setup installeer je het apart:

bash

brew install mutagen-io/mutagen/mutagen-compose
# Gebruik 'mutagen-compose up' in plaats van 'docker compose up'

2. :cached en :delegated flags

Voor Docker Desktop zonder Mutagen geef je bind mounts de :cached flag. Dit vertelt Docker dat de container authoritative is voor schrijfoperaties:

yaml

volumes:
  - ./src:/var/www/html:cached

Het scheelt 30-40% latency ten opzichte van de standaard mount.

3. Vendor-map buiten de mount houden

De /vendor map bevat tienduizenden kleine bestanden. Die op een bind mount zetten is traag. Gebruik een named volume voor vendor:

yaml

services:
  php:
    volumes:
      - ./src:/var/www/html:cached
      - vendor:/var/www/html/vendor  # Overschrijft de vendor-map met een snel volume

volumes:
  vendor:

Dit geeft de grootste performance-winst: tot 10x sneller voor Composer-operaties.

De PHP-container correct inrichten

Een standaard PHP-image bevat niet alles wat Magento nodig heeft. Bouw je eigen image:

dockerfile

# docker/php/Dockerfile
ARG PHP_VERSION=8.2
FROM php:${PHP_VERSION}-fpm-alpine

# Systeemafhankelijkheden
RUN apk add --no-cache \
    git \
    curl \
    libpng-dev \
    libjpeg-turbo-dev \
    libwebp-dev \
    libzip-dev \
    icu-dev \
    oniguruma-dev \
    freetype-dev

# PHP-extensies die Magento vereist
RUN docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp \
    && docker-php-ext-install -j$(nproc) \
        gd \
        intl \
        mbstring \
        opcache \
        pdo_mysql \
        soap \
        zip \
        bcmath \
        sockets

# PECL-extensies
RUN pecl install redis xdebug \
    && docker-php-ext-enable redis

# Composer
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

# Magento-specifieke PHP-instellingen
COPY php.ini /usr/local/etc/php/conf.d/magento.ini

De php.ini voor Magento:

ini

; docker/php/php.ini
memory_limit = 4G
max_execution_time = 1800
zlib.output_compression = On
opcache.enable = 1
opcache.memory_consumption = 512
opcache.max_accelerated_files = 60000
opcache.validate_timestamps = 1
opcache.revalidate_freq = 0
realpath_cache_size = 10M
realpath_cache_ttl = 7200

Xdebug instellen zonder alles te vertragen

Xdebug altijd aan laten staan is een veelgemaakte fout. Het vertraagt elke request met 30-50%. Gebruik de omgevingsvariabele XDEBUG_MODE om het aan en uit te zetten:

yaml

# In docker-compose.yml
services:
  php:
    environment:
      - XDEBUG_MODE=${XDEBUG_MODE:-off}  # Standaard uit

Zet het aan wanneer je debugt:

bash

XDEBUG_MODE=debug docker compose up -d php

Configureer Xdebug in de container:

ini

; docker/php/xdebug.ini
[xdebug]
xdebug.mode = ${XDEBUG_MODE}
xdebug.start_with_request = yes
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003
xdebug.idekey = PHPSTORM
xdebug.log_level = 0

In PhpStorm stel je de path mapping in: /var/www/html in de container staat gelijk aan je lokale src/ map.

Handige commando's voor dagelijks gebruik

bash

# Shell openen in de PHP-container
docker compose exec php bash

# Magento CLI-commando uitvoeren
docker compose exec php bin/magento cache:flush

# Composer install (met cache)
docker compose exec php composer install

# Magento installeren na eerste setup
docker compose exec php bin/magento setup:install \
  --base-url=https://magento.test \
  --db-host=mysql \
  --db-name=magento \
  --db-user=magento \
  --db-password=magento \
  --search-engine=elasticsearch7 \
  --elasticsearch-host=elasticsearch \
  --elasticsearch-port=9200 \
  --admin-firstname=Admin \
  --admin-lastname=User \
  [email protected] \
  --admin-user=admin \
  --admin-password=Admin123! \
  --language=nl_NL \
  --currency=EUR \
  --timezone=Europe/Amsterdam \
  --use-rewrites=1

# Logs bekijken
docker compose logs -f php nginx

Veelgemaakte fouten

Elasticsearch memory te laag — Docker Desktop heeft standaard 2GB RAM. Elasticsearch alleen al wil 1GB. Zet Docker Desktop op minimaal 6GB.
Geen aparte Redis-database per doel — Gebruik database 0 voor default cache, 1 voor page cache, 2 voor sessies. Anders spoel je bij een cache:flush ook je sessies door.
Geen .dockerignore — Zonder .dockerignore kopieert Docker de volledige node_modules en vendor naar de build-context. Dat maakt je builds onnodig traag.

# .dockerignore
node_modules
vendor
var/cache
var/page_cache
var/session
var/log
.git

Best practices

Practice	Waarom
Named volumes voor vendor en var	5-10x sneller dan bind mounts op macOS
Mutagen voor bestandssynchronisatie	Elimineert het macOS I/O-bottleneck
Xdebug standaard uitschakelen	30-50% snellere requests in development
`.env` bestand voor configuratie	Geen hardcoded credentials in docker-compose
Aparte Redis-databases per doel	Geen onbedoeld sessieverlies bij cache flush

Conclusie

Een goede Docker-setup voor Magento 2 is geen one-size-fits-all oplossing. Op macOS is het volume-beheer de grootste performance-factor. Warden is een uitstekend startpunt, maar voor specifieke requirements loont een custom docker-compose aanpak.

Het doel is een omgeving waarbij elke developer binnen 15 minuten aan de slag kan. Met de setup in dit artikel is dat haalbaar.

Meer weten over Magento 2 development? Lees ook Custom Magento 2 module development best practices of bekijk onze Magento 2 diensten. De officiële Magento DevDocs bevatten de volledige installatie-instructies voor lokale development.

Wij helpen teams hun Magento 2 ontwikkelomgeving professionaliseren. Neem contact op met Coding.nl voor een vrijblijvend gesprek.

Geschreven door Ruthger Idema

15+ jaar ervaring in e-commerce development. Gespecialiseerd in Magento, Shopify en Laravel maatwerk.

Meer over ons team →

Deel dit artikel:

Magento 2 en Docker — lokale development setup die werkt