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.

Coding.nl
Bijgewerkt 11 min leestijd
Inhoud van dit artikel
  1. Wat je leert in dit artikel
  2. De basisarchitectuur
  3. Warden vs. custom docker-compose
  4. Installeer Warden via Homebrew
  5. Start de globale services (Traefik, DNS, CA)
  6. Initialiseer een nieuw Magento-project
  7. Start de omgeving
  8. Performance op macOS: het bindmount-probleem
  9. In je docker-compose.yml
  10. Gebruik 'mutagen-compose up' in plaats van 'docker compose up'
  11. De PHP-container correct inrichten
  12. docker/php/Dockerfile
  13. Systeemafhankelijkheden
  14. PHP-extensies die Magento vereist
  15. PECL-extensies
  16. Composer
  17. Magento-specifieke PHP-instellingen
  18. Xdebug instellen zonder alles te vertragen
  19. In docker-compose.yml
  20. Handige commando's voor dagelijks gebruik
  21. Shell openen in de PHP-container
  22. Magento CLI-commando uitvoeren
  23. Composer install (met cache)
  24. Magento installeren na eerste setup
  25. Logs bekijken
  26. Veelgemaakte fouten
  27. .dockerignore
  28. Best practices
  29. Conclusie

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.

AspectWardenCustom docker-compose
OpstarttijdSnel, alles voorgedefinieerdMeer tijd om in te richten
FlexibiliteitBeperkt, conventies verplichtVolledig vrij
macOS performanceMutagen ingebouwdHandmatig configureren
Meerdere projectenAutomatisch via TraefikHandmatig poortnummers beheren
Team-onboardingEén commandoMeer 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

  1. Elasticsearch memory te laag — Docker Desktop heeft standaard 2GB RAM. Elasticsearch alleen al wil 1GB. Zet Docker Desktop op minimaal 6GB.
  2. 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.
  3. Geen .dockerignore — Zonder .dockerignore kopieert Docker de volledige node_modules en vendor naar de build-context. Dat maakt je builds onnodig traag.
code
# .dockerignore
node_modules
vendor
var/cache
var/page_cache
var/session
var/log
.git

Best practices

PracticeWaarom
Named volumes voor vendor en var5-10x sneller dan bind mounts op macOS
Mutagen voor bestandssynchronisatieElimineert het macOS I/O-bottleneck
Xdebug standaard uitschakelen30-50% snellere requests in development
.env bestand voor configuratieGeen hardcoded credentials in docker-compose
Aparte Redis-databases per doelGeen 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.

Ruthger Idema

Geschreven door Ruthger Idema

Eigenaar van Coding.nl. 15+ jaar e-commerce met Magento, Shopify en Laravel, samen met het vaste team in Emmen.

Wil je dit voor jouw shop laten uitzoeken? Plan een half uur

Een half uur via video met de mensen die het werk ook echt doen. Kies hieronder een moment dat jou past.

  • Direct met het vaste team, geen tussenlagen
  • Concrete feedback op je huidige situatie of plannen
  • Eerlijk advies, ook als het antwoord "niet doen" is
  • Indicatie van kosten en tijdlijn
Liever bellen? 0591-239 299
Beschikbaar deze week

Plan een gratis Tech Check

Vrijblijvend jouw uitdagingen bespreken

Of bel direct: 0591-239 299