Docker Compose pour un environnement WordPress local en 2026

Pourquoi utiliser Docker Compose pour WordPress en local

J ai longtemps travaillé avec MAMP, puis XAMPP, puis Local by Flywheel. Chaque outil fonctionnait jusqu au jour où un conflit de version PHP ou une mise à jour macOS cassait tout. Depuis 2019, je suis passé à Docker Compose pour tous mes projets WordPress clients, et je n ai jamais regardé en arrière.

Le principe est simple : Docker isole chaque service (WordPress, MySQL, Redis, Mailhog) dans un conteneur indépendant. Docker Compose orchestre ces conteneurs via un fichier YAML déclaratif. Résultat : chaque projet a son propre environnement, avec sa propre version de PHP et de MySQL, sans interférence avec le système hôte ni avec les autres projets.

Concrètement, quand un client me demande de reprendre un site qui tourne sur PHP 7.4 et MySQL 5.7, je crée un fichier docker-compose.yml dédié en 30 secondes. Pas besoin de jongler avec phpbrew ou de maintenir plusieurs installations en parallèle. Et quand un nouveau développeur rejoint le projet, il clone le dépôt, lance docker compose up -d, et tout fonctionne. C est exactement le genre de workflow que je décris dans mon article sur Git pour un développeur WordPress.

En 2026, Docker Compose v2 est intégré nativement dans Docker Desktop et dans le paquet docker-ce sur Linux. La commande docker-compose (avec tiret) est officiellement dépréciée au profit de docker compose (sans tiret). Si vous utilisez encore l ancienne syntaxe, c est le moment de migrer.

Prérequis : installer Docker et Docker Compose en 2026

Avant de créer votre premier fichier YAML, vous avez besoin de Docker Engine et de Docker Compose v2. Voici la marche à suivre selon votre OS.

Sur macOS et Windows, installez Docker Desktop depuis le site officiel. La version gratuite suffit pour un usage individuel (la licence payante ne concerne que les entreprises de plus de 250 salariés ou 10 M$ de chiffre d affaires). Docker Compose v2 est inclus.

Sur Ubuntu/Debian, je recommande l installation via le dépôt officiel Docker plutôt que le paquet docker.io des dépôts Ubuntu, souvent en retard de plusieurs versions :

sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Vérifiez l installation avec docker compose version. Vous devez obtenir v2.27 ou supérieur en juin 2026. Ajoutez votre utilisateur au groupe docker (sudo usermod -aG docker $USER) pour éviter de taper sudo à chaque commande.

Si vous prévoyez de déployer ensuite sur un VPS, mon tutoriel pour déployer WordPress sur un VPS OVH reprend exactement cette stack Docker en contexte de production.

Structure du projet et fichiers essentiels

Pour chaque projet client, je crée un dossier avec cette arborescence :

mon-projet-wp/
├── docker-compose.yml
├── .env
├── .gitignore
├── wp-content/
│   ├── themes/
│   │   └── mon-theme-custom/
│   ├── plugins/
│   └── uploads/
└── config/
    ├── php.ini
    └── uploads.ini

Le dossier wp-content/ est monté en volume dans le conteneur WordPress. Cela permet de développer le thème en local avec votre éditeur favori (VS Code, PhpStorm, Cursor) et de voir les modifications en temps réel sans rebuild. Le reste du core WordPress reste dans le conteneur, ce qui évite de versionner 1 500 fichiers inutiles.

Le fichier .env contient les variables sensibles (mots de passe, clés de salage). Il ne doit jamais être commité dans Git. Ajoutez-le au .gitignore dès la création du projet. Le fichier php.ini dans config/ permet de surcharger les paramètres PHP (upload_max_filesize, memory_limit, max_execution_time) sans toucher à l image Docker.

Le fichier docker-compose.yml complet, expliqué ligne par ligne

Voici le fichier que j utilise sur 90 % de mes projets WordPress en 2026. Il lance trois services : WordPress avec Apache, MySQL 8.0 et phpMyAdmin.

services:
  db:
    image: mysql:8.0
    container_name: wp_mysql
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: ${DB_NAME:-wordpress}
      MYSQL_USER: ${DB_USER:-wp_user}
      MYSQL_PASSWORD: ${DB_PASSWORD:-secret_password}
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:-root_secret}
    volumes:
      - db_data:/var/lib/mysql
    ports:
      - "3306:3306"
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  wordpress:
    image: wordpress:6.7-php8.3-apache
    container_name: wp_site
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: ${DB_NAME:-wordpress}
      WORDPRESS_DB_USER: ${DB_USER:-wp_user}
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD:-secret_password}
    volumes:
      - wp_data:/var/www/html
      - ./wp-content:/var/www/html/wp-content
      - ./config/uploads.ini:/usr/local/etc/php/conf.d/uploads.ini
    ports:
      - "8080:80"

  phpmyadmin:
    image: phpmyadmin:latest
    container_name: wp_pma
    restart: unless-stopped
    depends_on:
      - db
    environment:
      PMA_HOST: db
      PMA_PORT: 3306
    ports:
      - "8081:80"

volumes:
  db_data:
  wp_data:

Quelques points importants à noter :

• Le healthcheck sur MySQL empêche WordPress de démarrer avant que la base ne soit prête. Sans cette directive, vous obtenez régulièrement des erreurs « Connection refused » au premier lancement.
• Les volumes nommés (db_data, wp_data) persistent les données entre les redémarrages. Un simple docker compose down arrête les conteneurs mais conserve les volumes. Pour tout supprimer, il faut explicitement ajouter -v.
• Le fichier uploads.ini contient les surcharges PHP. Par exemple : upload_max_filesize = 64M et post_max_size = 64M.

Pour lancer l environnement, ouvrez un terminal dans le dossier du projet et tapez :

docker compose up -d

WordPress est accessible sur http://localhost:8080 et phpMyAdmin sur http://localhost:8081. L installation guidée de WordPress se lance automatiquement au premier accès.

Le fichier .env associé ressemble à ceci :

DB_NAME=wordpress
DB_USER=wp_user
DB_PASSWORD=un_vrai_mot_de_passe_fort
DB_ROOT_PASSWORD=un_autre_mot_de_passe_fort

Ajouter WP-CLI pour automatiser l installation

L assistant d installation WordPress en navigateur, c est bien pour un premier test. Mais quand vous montez 3 à 5 environnements par semaine comme moi, ça devient vite pénible. WP-CLI résout ce problème.

J ajoute un service dédié dans le docker-compose.yml :

  wpcli:
    image: wordpress:cli-php8.3
    container_name: wp_cli
    depends_on:
      db:
        condition: service_healthy
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: ${DB_NAME:-wordpress}
      WORDPRESS_DB_USER: ${DB_USER:-wp_user}
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD:-secret_password}
    volumes:
      - wp_data:/var/www/html
      - ./wp-content:/var/www/html/wp-content
    entrypoint: wp
    command: "--info"
    user: "33:33"

Ensuite, je crée un script setup.sh qui automatise toute l installation :

#!/bin/bash
docker compose up -d db wordpress
sleep 10

docker compose run --rm wpcli core install \
  --url="http://localhost:8080" \
  --title="Mon Site Dev" \
  --admin_user=admin \
  --admin_password=admin123 \
  [email protected] \
  --skip-email

docker compose run --rm wpcli plugin install query-monitor --activate
docker compose run --rm wpcli plugin install advanced-custom-fields --activate
docker compose run --rm wpcli rewrite structure '/%postname%/'
docker compose run --rm wpcli option update timezone_string 'Europe/Paris'

echo "WordPress prêt sur http://localhost:8080"

En une commande, j ai un WordPress installé, configuré avec le bon fuseau horaire, les permaliens propres et mes plugins de base activés. J ai détaillé les commandes WP-CLI les plus utiles dans mon article WP-CLI pour les freelances si vous voulez aller plus loin.

Comparatif : Docker Compose vs Local WP vs DDEV vs Lando

Docker Compose n est pas le seul outil pour développer WordPress en local. Voici un comparatif honnête basé sur mon expérience quotidienne avec chacun de ces outils.

Mon verdict : si vous débutez et que vous voulez juste tester un thème, Local WP reste imbattable en simplicité. Si vous êtes développeur et que vous travaillez sur plusieurs projets avec des contraintes techniques variées, Docker Compose brut ou DDEV (qui utilise Docker sous le capot) sont les meilleurs choix. DDEV ajoute une couche d abstraction bienvenue pour le HTTPS automatique et Xdebug sans configuration manuelle.

Personnellement, j utilise Docker Compose brut quand j ai besoin de services non standard (Redis, Elasticsearch, Varnish) et DDEV quand je veux aller vite sur un projet WordPress classique. Les deux approches se complètent.

Bonnes pratiques, sécurité et passage en production

Un environnement Docker local n est pas un jouet. Si vous prenez de mauvaises habitudes en dev, elles se retrouveront en production. Voici les règles que j applique systématiquement.

1. Ne jamais utiliser de mots de passe en clair dans le YAML. Utilisez un fichier .env et référencez les variables avec la syntaxe ${VARIABLE}. Ajoutez .env dans votre .gitignore. Créez un fichier .env.example avec des valeurs factices pour documenter les variables attendues.

2. Fixer les versions des images. N utilisez jamais wordpress:latest ou mysql:latest en production. Spécifiez toujours le tag exact : wordpress:6.7-php8.3-apache, mysql:8.0.37. Cela évite les surprises lors d un docker compose pull.

3. Ne pas exposer les ports en production. En local, on mappe les ports pour un accès direct. En production, utilisez un reverse proxy (Nginx, Traefik, Caddy) devant les conteneurs et supprimez les directives ports: du docker-compose de production. Seul le proxy doit être exposé sur les ports 80 et 443.

4. Sauvegarder les volumes. Un docker compose down -v accidentel et toutes vos données disparaissent. Mettez en place des sauvegardes régulières du volume MySQL. J explique plusieurs stratégies dans mon article sur les sauvegardes WordPress automatiques.

5. Respecter le RGPD même en local. Si vous importez une base de production pour débuguer, les données personnelles des utilisateurs sont présentes dans votre environnement local. La CNIL rappelle les obligations du RGPD y compris pour les environnements de développement. Anonymisez les données avec WP-CLI ou un plugin dédié avant de travailler dessus.

Pour le monitoring en production, pensez à installer une solution analytics respectueuse de la vie privée. J ai comparé les options disponibles dans mon article sur Plausible, Umami et Matomo.

Dépannage : les erreurs courantes et leurs solutions

Après avoir aidé des dizaines de développeurs à mettre en place Docker Compose pour WordPress, voici les problèmes que je rencontre le plus souvent.

« Error establishing a database connection » : dans 80 % des cas, WordPress démarre avant que MySQL ne soit prêt. Ajoutez le healthcheck sur le service db et la condition service_healthy dans le depends_on de WordPress, comme dans mon exemple plus haut. Vérifiez aussi que les variables WORDPRESS_DB_HOST, WORDPRESS_DB_NAME, WORDPRESS_DB_USER et WORDPRESS_DB_PASSWORD correspondent exactement à celles du service MySQL.

« Port already in use » : un autre service (Apache local, MAMP, un ancien conteneur) utilise déjà le port 8080 ou 3306. Changez le port dans le mapping (8082:80 par exemple) ou identifiez le processus avec lsof -i :8080 sur macOS/Linux.

Permissions sur wp-content : sur Linux, le conteneur WordPress tourne avec l utilisateur www-data (UID 33). Si votre dossier wp-content local appartient à un autre utilisateur, vous aurez des erreurs d écriture. Solution : sudo chown -R 33:33 wp-content/ ou ajoutez user: "1000:1000" dans le service WordPress (en remplaçant par votre UID réel).

Lenteur sur macOS avec les volumes montés : c est le problème historique de Docker sur Mac. Le système de fichiers partagé entre l hôte et le conteneur est lent. Depuis Docker Desktop 4.x, le driver VirtioFS a considérablement amélioré les performances. Vérifiez qu il est activé dans Settings > General > Virtual Machine Options. Si la lenteur persiste, envisagez de monter uniquement wp-content/themes et wp-content/plugins au lieu de tout le dossier wp-content.

MySQL qui ne démarre plus après une mise à jour d image : supprimez le volume de données (docker compose down -v) et relancez. Attention, cela efface toutes les données. Exportez d abord votre base avec docker compose exec db mysqldump -u root -p wordpress > backup.sql.

Aller plus loin : multisite, Xdebug et HTTPS local

Une fois votre environnement de base en place, voici trois améliorations que j ajoute régulièrement selon les besoins du projet.

WordPress Multisite. Ajoutez ces constantes dans un fichier wp-config-extra.php monté en volume, ou passez-les en variables d environnement :

WORDPRESS_CONFIG_EXTRA: |
  define('WP_ALLOW_MULTISITE', true);
  define('MULTISITE', true);
  define('SUBDOMAIN_INSTALL', false);
  define('DOMAIN_CURRENT_SITE', 'localhost');
  define('PATH_CURRENT_SITE', '/');
  define('SITE_ID_CURRENT_SITE', 1);
  define('BLOG_ID_CURRENT_SITE', 1);

Xdebug pour le débogage pas à pas. Créez un fichier config/xdebug.ini :

zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003

Montez-le dans le conteneur WordPress et installez l extension Xdebug via un Dockerfile custom :

FROM wordpress:6.7-php8.3-apache
RUN pecl install xdebug && docker-php-ext-enable xdebug

Puis dans le docker-compose.yml, remplacez image: wordpress:6.7-php8.3-apache par :

build:
  context: .
  dockerfile: Dockerfile

Pour connecter VS Code, installez l extension PHP Debug et configurez le launch.json avec le port 9003 et le pathMapping vers /var/www/html. Si vous utilisez un IDE avec IA intégrée comme Cursor ou Claude Code, j ai comparé les options dans mon article sur les IDE avec IA en 2026.

HTTPS local avec mkcert. Installez mkcert, l outil open source de Filippo Valsorda, puis générez un certificat local :

mkcert -install
mkcert localhost 127.0.0.1 ::1

Montez les fichiers .pem générés dans un conteneur Nginx en reverse proxy devant WordPress. C est indispensable pour tester les Service Workers, les APIs de géolocalisation ou toute fonctionnalité qui exige un contexte sécurisé.

Si votre projet implique des appels à des API externes depuis WordPress, consultez mon guide sur l intégration d API externe dans WordPress pour gérer correctement les requêtes HTTP sortantes depuis un conteneur Docker.

Pour la gestion des images et des médias dans votre thème, pensez aussi à optimiser dès le développement local. Mon article sur l optimisation des images WordPress en WebP et AVIF vous donnera les bonnes pratiques à intégrer dans votre workflow.

Enfin, si vous automatisez vos déploiements avec des workflows CI/CD, le fichier docker-compose.yml peut servir de base pour vos pipelines. Combinez-le avec un outil comme n8n ou Make pour déclencher des actions post-déploiement automatiques.

Docker Compose est-il gratuit pour un usage freelance ?

Oui. Docker Engine et Docker Compose sont open source et entièrement gratuits. Docker Desktop est gratuit pour les entreprises de moins de 250 salariés et moins de 10 millions de dollars de chiffre d affaires annuel, ce qui couvre la quasi-totalité des freelances et des petites agences web.

Quelle est la différence entre docker-compose (avec tiret) et docker compose (sans tiret) ?

La commande docker-compose avec tiret correspond à la version 1, écrite en Python, qui est officiellement dépréciée depuis 2023. La commande docker compose sans tiret est la version 2, intégrée comme plugin natif de Docker CLI, écrite en Go. En 2026, utilisez exclusivement docker compose (v2). La syntaxe des fichiers YAML reste identique.

Docker Compose remplace-t-il un hébergement de production ?

Non. Docker Compose est conçu pour le développement local et les environnements de test. Pour la production, il faut ajouter un reverse proxy (Nginx, Traefik), du HTTPS avec Let’s Encrypt, des sauvegardes automatisées, du monitoring et un pare-feu. Docker Compose peut être utilisé en production sur un petit VPS, mais ce n est pas son usage principal.

Comment partager ma base de données WordPress Docker avec un collègue ?

Exportez la base avec la commande docker compose exec db mysqldump -u root -p wordpress > dump.sql, puis partagez le fichier SQL. Votre collègue l importera avec docker compose exec -T db mysql -u root -p wordpress < dump.sql après avoir lancé son propre environnement. Vous pouvez aussi versionner un script d import dans votre dépôt Git.[/site_a] [site_q]Docker consomme-t-il beaucoup de ressources sur un Mac M1/M2/M3 ?[/site_q] [site_a]Docker Desktop sur les puces Apple Silicon consomme entre 1,5 et 3 Go de RAM au repos, selon le nombre de conteneurs actifs. Pour un projet WordPress avec MySQL et phpMyAdmin, comptez environ 2 Go. Activez le driver VirtioFS dans les paramètres pour améliorer les performances des volumes montés. Pensez à arrêter les conteneurs inutilisés avec docker compose stop quand vous ne travaillez pas dessus.[/site_a] [site_q]Peut-on utiliser MariaDB à la place de MySQL dans le docker-compose.yml ?[/site_q] [site_a]Oui, et c est même recommandé par certains développeurs WordPress. Remplacez simplement l image mysql:8.0 par mariadb:11.4 dans votre fichier YAML. Les variables d environnement sont identiques (MYSQL_DATABASE, MYSQL_USER, etc.). MariaDB est généralement plus léger en mémoire et reste pleinement compatible avec WordPress.[/site_a] [site_q]Comment ajouter Redis pour le cache objet WordPress dans Docker Compose ?[/site_q] [site_a]Ajoutez un service Redis dans votre docker-compose.yml avec l image redis:7-alpine, puis installez le plugin Redis Object Cache dans WordPress. Configurez wp-config.php avec define('WP_REDIS_HOST', 'redis') et define('WP_REDIS_PORT', 6379). Le nom d hôte redis correspond au nom du service dans le fichier Compose, Docker gère la résolution DNS automatiquement.[/site_a] [/site_faq] [site_bio]