WordPress Docker Setup 2026: Docker Compose, Composer und Xdebug

Wenn Sie im Jahr 2026 als professioneller WordPress-Entwickler arbeiten, ist Docker Ihr wichtigstes Werkzeug. Vorbei sind die Zeiten, in denen man PHP-Versionen manuell auf dem Mac installierte oder mit Windows-spezifischen Serverfehlern kämpfte. Docker ist zur gemeinsamen Sprache für Entwicklungsumgebungen geworden, und wer im heutigen WordPress-Ökosystem arbeitet, sollte es sicher beherrschen.

Dieser Leitfaden behandelt Docker in der WordPress-Entwicklung: von den Grundlagen und dem offiziellen wordpress-Image über Compose und wp-env bis zu Debugging, CI/CD und der Migration von MAMP oder LocalWP. Die technischen Details stammen aus der offiziellen Dokumentation von Docker, der wordpress-Seite auf Docker Hub, von MariaDB und aus dem WordPress-Entwicklerhandbuch, jeweils im Abschnitt verlinkt.

#Warum Docker für die WordPress-Entwicklung

Die Ausrede “Bei mir funktioniert es” zählt nicht mehr, sobald die Umgebung in versionierten Dateien steckt. Containerisierung sorgt für Konsistenz zwischen den Umgebungen und hat verändert, wie WordPress-Teams zusammenarbeiten und Software ausliefern.

#Gleiche Umgebung lokal und in der Produktion

Ihr lokaler Container kann dieselbe Linux-Distribution, dieselbe PHP-Version und dieselbe MySQL-Konfiguration nutzen wie Ihr Produktionsserver. Das reduziert die ärgerlichste Fehlerklasse: Fehler, die nur in der Produktion auftreten. Wenn Sie in einem Container mit demselben Image wie der Server entwickeln, verhält sich der Code auf Ihrem Laptop genauso auf dem Staging-Server und in der Produktion.

Gleiche Umgebungen bedeuten mehr als gleiche Softwareversionen. Dazu gehören Netzwerkkonfiguration, Umgebungsvariablen und Dateirechte. Mit Docker arbeitet jedes Teammitglied in derselben Umgebung, egal ob auf macOS, Windows oder Linux als Host-System.

#Mehrere PHP-Versionen in isolierten Projekten

Projekt A braucht PHP 8.4, Projekt B braucht PHP 7.4? Kein Problem. Jedes Projekt lebt in seiner eigenen “Blase” und kommt anderen nie in die Quere. Mit klassischen Werkzeugen wie MAMP oder XAMPP war diese Isolation schwer zu erreichen, weil ein Wechsel der PHP-Version alle Projekte gleichzeitig betraf.

Die Isolation schützt auch Ihr Host-Betriebssystem. PHP-Erweiterungen, Systembibliotheken und Projektabhängigkeiten bleiben getrennt. Braucht ein Projekt eine experimentelle PHP-Erweiterung oder eine ungewöhnliche Serverkonfiguration, können Sie sie ohne Risiko für Ihre anderen Projekte einsetzen.

#Reproduzierbare Umgebung mit Dateien in Git

Jede Docker-Umgebung wird durch Konfigurationsdateien beschrieben, die in Git versioniert sind. Ein neues Teammitglied klont das Repository, führt einen Befehl aus und hat eine laufende Umgebung, ohne Schritt-für-Schritt-Anleitung, die schnell veraltet. Die Dokumentation der Umgebung lebt im Projektcode selbst.

#WordPress mit Docker Compose einrichten

Docker Compose koordiniert mehrere Container. Ein typisches WordPress-Setup im Jahr 2026 besteht aus mehreren Diensten, die zusammen eine vollständige Entwicklungsumgebung bilden.

#Welche Dienste WordPress in Docker Compose braucht

1. WordPress (PHP-FPM oder Apache): die Engine, die den PHP-Code von WordPress ausführt.
2. Nginx: der Webserver vor PHP-FPM, wenn Sie die fpm-Variante wählen.
3. MariaDB/MySQL: die Datenbank, in der alle Inhalte liegen.
4. Redis: der Objekt-Cache, empfehlenswert, wenn das Projekt ihn in der Produktion nutzt.
5. Mailpit: fängt ausgehende E-Mails beim Testen ab.

# Ausschnitt aus compose.yaml mit der FPM-Variante
services:
  db:
    image: mariadb:11.4
    volumes:
      - db_data:/var/lib/mysql
  wordpress:
    image: wordpress:php8.4-fpm
    depends_on:
      - db
volumes:
  db_data:

Die fpm-Variante enthält keinen Webserver und braucht daher einen Nginx-Container, der die PHP-Anfragen weiterreicht. Wer Nginx nicht konfigurieren möchte, nimmt die Apache-Variante (wordpress:php8.4-apache), die WordPress direkt auf Port 80 des Containers ausliefert.

#Bind mounts oder benannte Volumes für WordPress

Volumes sind in Docker Compose für die WordPress-Entwicklung zentral. Theme- und Plugin-Verzeichnisse müssen eingebunden werden, damit Sie den Code live bearbeiten können, während die Datenbankdaten in benannten Volumes bleiben, damit zwischen Neustarts nichts verloren geht.

Die richtige Strategie wägt Performance und Funktion ab. Für Dateien, die Sie oft bearbeiten (Themes, eigene Plugins), nutzen Sie Bind mounts. Für Daten, die nur erhalten bleiben müssen (Datenbank, Uploads), nutzen Sie benannte Docker-Volumes. Die Dokumentation des offiziellen Images nennt die Pfade: Themes gehören nach /var/www/html/wp-content/themes/, Plugins nach /var/www/html/wp-content/plugins/.

#Zugangsdaten in .env-Dateien mit Docker Compose

Der Umgang mit Geheimnissen zählt auch lokal. Legen Sie Datenbank-Zugangsdaten und API-Schlüssel in .env-Dateien ab und tragen Sie diese in Ihre .gitignore ein. Docker Compose liest die .env-Datei im Projektverzeichnis und ersetzt Variablen wie ${DB_PASSWORD} in compose.yaml. So bleibt sensible Konfiguration vom versionierten Code getrennt.

#Umgebungsvariablen des offiziellen WordPress-Images

Das wordpress-Image von Docker Hub erzeugt seine eigene wp-config.php aus Umgebungsvariablen. Laut der offiziellen Image-Seite werden diese erkannt:

Das Detail, das am meisten Zeit kostet: Der WordPress-Container legt die in WORDPRESS_DB_NAME angegebene Datenbank nicht an. Das erledigt der Datenbank-Container, mit MARIADB_DATABASE bei MariaDB oder MYSQL_DATABASE bei MySQL. Stimmen die beiden Namen nicht überein, meldet WordPress einen Verbindungsfehler, obwohl die Zugangsdaten korrekt sind.

WORDPRESS_CONFIG_EXTRA dient für Konstanten, die das Image nicht direkt anbietet, etwa WP_ALLOW_MULTISITE oder WP_ENVIRONMENT_TYPE. Alles darin wird mit eval() ausgeführt. Halten Sie den Inhalt deshalb kurz und versionieren Sie ihn zusammen mit der übrigen Konfiguration.

#WordPress erst starten, wenn MariaDB bereit ist

Ein einfaches depends_on reicht nicht. Die Compose-Dokumentation zur Startreihenfolge erklärt, dass Compose nur wartet, bis der abhängige Container läuft, nicht bis er Verbindungen annimmt. MariaDB braucht beim ersten Start einige Sekunden zur Initialisierung, und WordPress kann früher starten und an der Verbindung scheitern.

Die Lösung ist ein healthcheck in der Datenbank und condition: service_healthy bei WordPress. Das offizielle MariaDB-Image bringt dafür das Skript healthcheck.sh mit, und die MariaDB-Dokumentation zeigt ein Beispiel mit WordPress. Für eine Entwicklungsumgebung angepasst sieht es so aus:

services:
  db:
    image: mariadb:11.4
    environment:
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wordpress
      MARIADB_PASSWORD: ${DB_PASSWORD}
      MARIADB_RANDOM_ROOT_PASSWORD: '1'
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 10s
      interval: 10s
      timeout: 5s
      retries: 3
  wordpress:
    image: wordpress:php8.4-apache
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
      WORDPRESS_DEBUG: '1'
    volumes:
      - wp_data:/var/www/html
      - ./mein-theme:/var/www/html/wp-content/themes/mein-theme
    depends_on:
      db:
        condition: service_healthy
volumes:
  db_data:
  wp_data:

Mit dieser Datei startet docker compose up -d zuerst die Datenbank, wartet, bis der Healthcheck besteht, und startet erst dann WordPress unter http://localhost:8080. Das eigene Theme ist als Bind mount eingebunden, der Rest von WordPress liegt im Volume wp_data.

#WordPress-Images apache, fpm, alpine und cli

Das offizielle Image erscheint in mehreren Varianten. Die Tags kombinieren WordPress-Version, PHP-Version und Typ, zum Beispiel php8.4-apache, php8.4-fpm, php8.4-fpm-alpine oder cli.

• apache: WordPress und Apache in einem Container. Der direkteste Weg für die lokale Entwicklung.
• fpm: nur PHP-FPM, gedacht für den Betrieb hinter Nginx oder einem anderen Proxy.
• fpm-alpine: dasselbe auf Alpine Linux, mit kleinerem Image.
• cli: WP-CLI ohne Webserver, um wp-Befehle gegen eine bestehende Installation auszuführen.

Die cli-Variante hat eine auf Docker Hub dokumentierte Falle: Sie basiert auf Alpine, und ihr Benutzer www-data hat die UID 82, während die Debian-basierten Varianten die UID 33 verwenden. Wenn Sie wordpress:cli gegen eine Debian-Installation ausführen, ist meist --user 33:33 nötig, manchmal auch -e HOME=/tmp, damit WP-CLI in die Dateien schreiben kann.

#PHP-Erweiterungen zum offiziellen Image hinzufügen

Das Image enthält keine zusätzlichen PHP-Erweiterungen, auch wenn beliebte Plugins sie verlangen. Docker Hub nennt als Beispiel, dass das Image von sich aus keine E-Mails versenden kann. Für weitere Erweiterungen bauen Sie ein eigenes Image mit FROM wordpress:... und folgen der Anleitung des php-Images. Für Direktiven wie upload_max_filesize genügt es, eine custom.ini nach $PHP_INI_DIR/conf.d/ zu kopieren:

FROM wordpress:php8.4-apache
COPY custom.ini $PHP_INI_DIR/conf.d/

Wenn Sie Themes oder Plugins für mehrere Installationen direkt ins Image packen wollen, sollen sie laut Dokumentation nach /usr/src/wordpress/. Dieser Ordner wird beim ersten Start des Containers nach /var/www/html/ kopiert.

#wp-env, die offizielle Docker-Umgebung von WordPress

Wenn Sie Plugins oder Themes entwickeln und keinen bestimmten Server nachbilden müssen, erspart wp-env das Schreiben einer compose.yaml von Hand. Es ist ein Node-Paket aus dem Gutenberg-Repository, das unter der Haube Docker nutzt. Die Installation erfolgt mit npm -g i @wordpress/env, der Start mit wp-env start im Plugin-Ordner.

Die Umgebung läuft dann unter http://localhost:8888 mit dem Benutzer admin und dem Passwort password. Die Konfiguration liegt in einer .wp-env.json im Projektstamm:

{
  "$schema": "https://schemas.wp.org/trunk/wp-env.json",
  "core": null,
  "phpVersion": "8.3",
  "plugins": [ "." ],
  "config": {
    "WP_DEBUG_LOG": true
  }
}

core auf null nutzt die neueste stabile WordPress-Version, phpVersion legt die PHP-Version fest und plugins listet die Plugins, die installiert und aktiviert werden. Dazu kommen themes, mappings zum Einbinden von Verzeichnissen, port (standardmäßig 8888), testsPort (8889) und mariadbVersion.

Composer, PHPUnit und WP-CLI sind im Container cli enthalten: wp-env run cli wp plugin list oder wp-env run cli --env-cwd=wp-content/plugins/mein-plugin composer install. Xdebug ist installiert, aber abgeschaltet, und wird mit wp-env start --xdebug aktiviert. Die Dokumentation beschreibt außerdem einen experimentellen Modus, wp-env start --runtime=playground, der WordPress ohne Docker in WebAssembly ausführt, mit SQLite und ohne den Befehl run.

Der praktische Unterschied zu Compose: wp-env entscheidet die Architektur für Sie. Für ein Plugin geht das schneller. Um einen Produktionsserver mit Nginx, Redis und einer exakten MariaDB-Version nachzubilden, bleibt Compose das passende Werkzeug.

#VS Code Dev Container für WordPress

Viele Entwickler installieren PHP gar nicht mehr auf ihrem Laptop. Sie nutzen VS Code Dev Containers, die die Arbeit mit dem Editor verändern.

#So funktioniert ein Dev Container in VS Code

Sie öffnen Ihren Projektordner, VS Code erkennt den Ordner .devcontainer, startet Docker und verbindet die IDE direkt mit dem Inneren des Containers. VS-Code-Erweiterungen, Kommandozeilenwerkzeuge und Editor-Einstellungen laufen im Container.

#Vorkonfigurierte Erweiterungen und Linter im Container

Ein eingerichteter Arbeitsplatz für jedes Projekt, sobald der Ordner geöffnet ist. Ob jemand seit fünf Minuten oder seit fünf Jahren im Team ist, die Umgebung ist für alle gleich. PHP-Erweiterungen, Linter, Code-Formatierer und Debugging-Werkzeuge sind im Repository festgelegt.

#Dev Container für verteilte Teams

Für WordPress-Agenturen mit verteilten Teams beseitigen Dev Container eine häufige Reibungsquelle: Unterschiede zwischen lokalen Umgebungen. Wer an einem anderen Standort arbeitet, hat trotzdem exakt dieselbe Umgebung wie das restliche Team, ohne zeitraubende manuelle Einzelkonfigurationen.

#Docker auf Mac und Windows beschleunigen

Docker war auf Systemen außer Linux langsam, weil die Projektdateien eine virtuelle Maschine durchqueren. Docker Desktop bietet heute mehrere Optionen, um diesen Aufwand zu senken.

#VirtioFS in Docker Desktop aktivieren

Wählen Sie unter macOS in den Einstellungen von Docker Desktop VirtioFS als Implementierung für die Dateifreigabe. Die Dokumentation der Docker-Desktop-Einstellungen gibt an, dass VirtioFS die Dauer von Dateisystemoperationen um bis zu 98% verkürzt hat. Es ersetzt die älteren Optionen osxfs und gRPC FUSE.

#Synchronized file shares für große Repositorys

Für sehr große Projekte bietet Docker Desktop Synchronized file shares: Es hält einen synchronisierten Cache der Host-Dateien auf einem ext4-Dateisystem in der virtuellen Maschine. Docker empfiehlt es für Repositorys mit 100 000 Dateien oder mehr, verfügbar ist es in den Abonnements Pro, Team und Business. Eine WordPress-Installation mit großem node_modules im Theme kann in diese Größenordnung kommen.

#Wie viel RAM Docker Desktop belegt

Die virtuelle Maschine von Docker Desktop reserviert Speicher, solange sie läuft. Der Modus Resource Saver hält sie an, wenn 5 Minuten lang kein Container läuft (der Wert ist einstellbar), und Docker nennt eine Einsparung von 2 GB oder mehr an Speicher und CPU auf dem Host.

#Docker vs LocalWP, MAMP und DDEV

#Docker Compose im Vergleich zu DDEV und Lando

DDEV und Lando vereinfachen Docker für WordPress-Entwickler. Sie liefern vorgefertigte Konfigurationen und vereinfachte Befehle, die die Lernkurve flacher machen. Für Projekte, bei denen Sie jede Komponente der Infrastruktur selbst bestimmen müssen, bleibt Compose mit einer eigenen Datei die flexibelste Wahl.

#Wann DDEV und wann Docker Compose

Die Wahl hängt von Ihrer Erfahrung und dem Projekt ab. Wenn Sie mit Containern gerade anfangen, bietet DDEV einen sanfteren Einstieg. Wenn Sie mehrere Projekte mit unterschiedlichen Infrastruktur-Anforderungen betreuen, lässt Ihnen Docker Compose mit eigenen Konfigurationen mehr Spielraum.

#Sicherheit in Docker-Umgebungen für WordPress

Docker isoliert standardmäßig, aber die Konfiguration entscheidet, wie viel Schutz Sie tatsächlich bekommen.

#Container ohne root und aktuelle Images

Führen Sie Prozesse in Ihren Containern nicht als root aus, wenn es nicht nötig ist. Halten Sie die Basis-Images aktuell, um Sicherheitspatches zu erhalten; die Dokumentation des wordpress-Images erinnert selbst daran, regelmäßig neu zu bauen und neu auszurollen. Scannen Sie Ihre Images mit Werkzeugen wie Docker Scout oder Trivy auf bekannte Schwachstellen.

#Getrennte Docker-Netzwerke pro Projekt

Compose legt für jedes Projekt ein eigenes Netzwerk an. Behalten Sie diese Trennung bei und verbinden Sie Container verschiedener Projekte nicht ohne Grund mit demselben Netzwerk, damit eine Lücke in einem Projekt die anderen nicht erreicht.

#Docker Secrets und .env-Dateien für Passwörter

Schreiben Sie Zugangsdaten nie direkt in Ihr Dockerfile oder in compose.yaml. Das wordpress-Image akzeptiert das Suffix _FILE an seinen Variablen: WORDPRESS_DB_PASSWORD_FILE=/run/secrets/db_password liest das Passwort aus einer Datei statt aus einer Variable. Compose bindet jedes Secret unter /run/secrets/<name> im Container ein, so die Anleitung zu Secrets, die eine Einschränkung nennt: Secrets funktionieren nur in Linux-Containern.

#CI/CD für WordPress mit Docker einrichten

Der größte Vorteil von Docker: Ihre CI/CD-Pipeline (GitHub Actions, GitLab CI) kann dieselben Images nutzen wie Ihre lokale Umgebung. Diese Konsistenz beseitigt eine ganze Klasse von Deployment-Fehlern.

#Schritte einer CI/CD-Pipeline mit Docker

1. PHPUnit-Tests im Container ausführen, um die Backend-Logik zu prüfen.
2. End-to-End-Tests mit Cypress oder Playwright gegen den Container ausführen.
3. Das stabile Image in Ihren Produktionscluster ausrollen (Kubernetes/Swarm).

#Private Image-Registry für WordPress

Teams, die eigene WordPress-Images bauen, legen sie in einer privaten Container-Registry ab. Diese Images enthalten die nötigen PHP-Erweiterungen, Entwicklungswerkzeuge und die Projektkonfiguration, sodass ein neues Teammitglied das Image herunterlädt, statt es zu bauen.

Docker Hub beschreibt außerdem ein statisches Deployment: ein Image mit WordPress, Theme und Plugins in /usr/src/wordpress bauen, es mit --read-only und tmpfs für /tmp und /run betreiben und Updates durch das Ausrollen eines neuen Images einspielen statt über automatische Updates.

#WordPress auf Kubernetes oder Docker Swarm

Für WordPress-Sites mit hohem Traffic erlaubt die Orchestrierung mit Kubernetes oder Docker Swarm eine Skalierung nach Bedarf. Steigt der Traffic bei Kampagnen oder Verkaufsaktionen, starten neue Container und fangen die Last ab.

#WordPress in Docker debuggen

Debugging von WordPress in Containern erfordert ein paar andere Techniken als die klassische lokale Entwicklung.

#Xdebug in Containern

Xdebug im Container braucht Aufmerksamkeit beim Netzwerk: Der Container muss die IDE erreichen, die auf dem Host lauscht. Viele Dev-Container-Konfigurationen bringen Xdebug bereits mit, wp-env aktiviert es mit --xdebug, und in einem eigenen Image müssen Sie die Erweiterung installieren sowie Verbindungshost und Port einstellen.

#Logs mit docker compose logs ansehen

Docker bietet zentralen Zugriff auf die Logs aller Dienste. Mit docker compose logs sehen Sie die gemeinsame Ausgabe von WordPress, Nginx, MariaDB und Redis, mit docker compose logs -f wordpress folgen Sie einem einzelnen Dienst. Bei aktiviertem WORDPRESS_DEBUG erscheinen PHP-Warnungen in derselben Ausgabe. In der Produktion liefern Werkzeuge wie Grafana und Prometheus Monitoring-Dashboards.

#Query Monitor und Blackfire in Docker

Werkzeuge wie Query Monitor und Blackfire funktionieren in Docker-Umgebungen für WordPress. Profiling im Container liefert ein Bild der Performance unter Bedingungen nahe an der Produktion.

#Von MAMP oder LocalWP zu Docker migrieren

Wenn Sie MAMP, XAMPP oder LocalWP nutzen, ist der Umstieg auf Docker einfacher, als er aussieht. Üblicherweise exportieren Sie die Datenbanken, schreiben Compose-Dateien, die Ihre aktuelle Konfiguration nachbilden, und übernehmen die übrigen Praktiken nach und nach.

#Ein Pilotprojekt auf Docker Compose umziehen

Beginnen Sie mit einem einzigen Pilotprojekt. Legen Sie eine compose.yaml an, die Ihre aktuelle Umgebung nachbildet, einschließlich PHP-Version, Datenbank-Engine und benötigter Erweiterungen. Wenn das Pilotprojekt läuft, ziehen Sie die übrigen Projekte um.

#Datenbank und wp-content importieren

Exportieren Sie Ihre Datenbanken mit mysqldump und importieren Sie sie in den MariaDB-Container. Kopieren Sie Ihre WordPress-Dateien (vor allem wp-content) in die Volume-Struktur von Docker. Ändert sich die URL, zum Beispiel auf http://localhost:8080, führen Sie wp search-replace mit WP-CLI aus und prüfen Sie, ob Medien und Links in der neuen Umgebung funktionieren.

#Fazit

Docker ist nicht mehr nur etwas für DevOps, sondern eine Grundfähigkeit für WordPress-Entwickler im Jahr 2026. Mit Containern beseitigen Sie Umgebungsfehler, beschleunigen das Onboarding neuer Teammitglieder und bauen sicherere Anwendungen. Die Zeit, die Sie in Docker investieren, zahlt sich in Produktivität und Codequalität aus.

Kämpfen Sie noch mit lokalen Serverkonfigurationen? Dann ist es Zeit, Ihre Umgebung mit Docker zu containerisieren.