Comment utiliser Docker Compose sur un VPS Ubuntu ou Debian ?
Écrire un fichier compose.yaml, lancer WordPress et MariaDB avec docker compose up -d, puis gérer journaux, mises à jour, sauvegardes et HTTPS sur un VPS
Docker Compose décrit plusieurs conteneurs dans un seul fichier, compose.yaml : images, ports, volumes, variables et ordre de démarrage. Une seule commande, docker compose up -d, crée ou met à jour toute la pile. Ce guide part d’un VPS où Docker est déjà installé, monte un exemple concret, WordPress avec MariaDB, puis détaille les commandes du quotidien et les erreurs fréquentes. Il s’applique tel quel à Ubuntu 22.04 / 24.04 et à Debian 12 / 13.
Procédure étape par étape
-
Vérifier Docker et le plugin Compose
Lancez docker compose version. Si la réponse est docker: 'compose' is not a docker command, installez Docker depuis le dépôt officiel avec le paquet docker-compose-plugin, comme dans le guide d’installation de Docker.
-
Créer le dossier du projet
Créez un dossier par application, par exemple /opt/wordpress, et placez-vous dedans. Compose nomme le projet d’après ce dossier et cherche compose.yaml dans le dossier courant.
-
Écrire le fichier .env et compose.yaml
Générez un mot de passe dans .env, lisible par root seul, puis copiez le fichier compose.yaml ci-dessous. Au démarrage, Compose remplace ${DB_PASSWORD} par la valeur lue dans .env.
-
Démarrer la pile
Lancez docker compose up -d. Compose télécharge les images, crée le réseau et les volumes, attend que MariaDB soit prête, puis démarre WordPress. docker compose ps affiche ensuite les deux services en Up, avec (healthy) pour db.
-
Tester et lire les journaux
Depuis le VPS, curl -I http://127.0.0.1:8080 doit renvoyer une redirection vers la page d’installation de WordPress. En cas de problème, docker compose logs -f --tail=100 affiche les journaux de tous les services.
-
Mettre à jour les conteneurs
Pour passer à une nouvelle version, changez le tag de l’image dans compose.yaml, puis lancez docker compose pull et docker compose up -d : seuls les conteneurs dont l’image ou la configuration a changé sont recréés, les volumes restent en place.
Créer le projet et son mot de passe
mkdir -p /opt/wordpress
cd /opt/wordpress
echo "DB_PASSWORD=$(openssl rand -hex 24)" > .env
chmod 600 .env
Fichier compose.yaml : WordPress et MariaDB
services:
db:
image: mariadb:11.4
restart: unless-stopped
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"]
interval: 10s
timeout: 5s
retries: 5
wordpress:
image: wordpress:6.8-apache
restart: unless-stopped
depends_on:
db:
condition: service_healthy
environment:
WORDPRESS_DB_HOST: db
WORDPRESS_DB_USER: wordpress
WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
WORDPRESS_DB_NAME: wordpress
ports:
- "127.0.0.1:8080:80"
volumes:
- wp_data:/var/www/html
volumes:
db_data:
wp_data:
Démarrer et vérifier
docker compose up -d
docker compose ps
curl -I http://127.0.0.1:8080
docker compose logs -f --tail=100
Commandes Docker Compose du quotidien
docker compose ps
docker compose logs --tail=50 wordpress
docker compose restart wordpress
docker compose exec db sh
docker compose stop
docker compose start
docker compose down
docker compose config --quiet
docker compose ls
Mettre à jour les images
cd /opt/wordpress
docker compose pull
docker compose up -d
docker image prune -f
Sauvegarder la base MariaDB
cd /opt/wordpress
docker compose exec -T db sh -c 'mariadb-dump -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE"' > wordpress-$(date +%F).sql
HTTPS avec Caddy : compose.override.yaml
services:
caddy:
image: caddy:2
restart: unless-stopped
ports:
- "80:80"
- "443:443"
- "443:443/udp"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
volumes:
caddy_data:
caddy_config:
Caddyfile
example.com {
reverse_proxy wordpress:80
}
Avant de commencer
Il vous faut un VPS Linux avec Docker Engine et le plugin Compose, installés depuis le dépôt officiel de Docker : suivez le guide « Comment installer Docker sur Debian 12 ou Ubuntu 24.04 ? » si ce n’est pas encore fait. Les commandes sont lancées en root ; un compte membre du groupe docker les exécute aussi sans sudo.
- Compose v2 s’écrit docker compose, avec un espace. L’ancien programme docker-compose (v1) n’est plus maintenu depuis 2023 : ne l’installez ni avec pip ni avec apt.
- Le fichier s’appelle compose.yaml ; docker-compose.yml reste lu pour les anciens projets. La ligne version: en tête de fichier est obsolète et ne sert plus à rien.
- WordPress et MariaDB tiennent dans 1 à 2 Go de RAM ; prévoyez davantage dès que plusieurs piles tournent sur le même VPS.
Comprendre le fichier compose.yaml
Chaque entrée de services devient un conteneur. Compose crée aussi un réseau privé pour le projet : les services s’y joignent par leur nom, d’où WORDPRESS_DB_HOST: db. Aucun port de MariaDB n’est publié, la base reste donc invisible depuis Internet.
- image : l’image et son tag. Fixez une version (mariadb:11.4) plutôt que latest pour savoir ce que vous mettez à jour.
- ports : "127.0.0.1:8080:80" publie le port 80 du conteneur sur le port 8080 du VPS, en local seulement. Sans 127.0.0.1, le port est ouvert sur Internet, même si UFW le bloque.
- volumes : un volume nommé (db_data) conserve les données quand le conteneur est recréé. Il n’est supprimé que par docker compose down -v ou docker volume rm.
- environment et .env : les secrets restent dans .env, hors du fichier que vous partagez ou versionnez.
- restart: unless-stopped relance les conteneurs après un plantage ou un redémarrage du VPS, sauf ceux que vous avez arrêtés à la main.
- depends_on avec condition: service_healthy attend que le healthcheck de MariaDB réussisse avant de démarrer WordPress.
Mettre le site en ligne en HTTPS
Pour servir le site sur un nom de domaine, faites pointer un enregistrement A vers l’IPv4 du VPS, ouvrez les ports 80 et 443, puis ajoutez Caddy dans un fichier compose.override.yaml, que Compose lit automatiquement avec compose.yaml. Remplacez example.com par votre domaine dans le Caddyfile : Caddy obtient et renouvelle seul le certificat Let’s Encrypt.
Terminez ensuite l’installation de WordPress depuis l’adresse en https de votre domaine, pas depuis 127.0.0.1 : WordPress enregistre l’adresse utilisée lors de son installation.
Sauvegardes et mises à jour de la pile
Un volume n’est pas une sauvegarde : il disparaît avec le VPS ou avec un down -v lancé par erreur. Exportez la base avec mariadb-dump (bloc ci-dessus), copiez le dossier du projet et le contenu des volumes, puis envoyez le tout hors du VPS.
- docker compose pull télécharge les nouvelles images des tags indiqués, docker compose up -d recrée les conteneurs concernés et docker image prune -f libère la place des anciennes images.
- Avant de changer de version majeure de MariaDB ou de PostgreSQL, faites un export SQL : la nouvelle version peut exiger une migration des données.
- docker system df indique la place prise par les images, les conteneurs et les volumes.
Quel VPS pour Docker Compose ?
Docker a besoin d’un vrai noyau Linux : un VPS KVM convient, un hébergement mutualisé non. Chez ACLClouds, au 16 novembre 2026, le VPS Mini (2 vCPU, 8 Go de RAM, 40 Go de stockage) coûte 4,99 € par mois sans engagement, ou 3,99 € par mois avec un engagement d’un an : il fait tourner plusieurs petites piles Compose. Le VPS Essentiel (4 vCPU, 16 Go de RAM, 80 Go), à 9,99 € par mois, convient à une base de données chargée ou à n8n à côté d’un site.
L’option -v de docker compose down efface les données
docker compose down -v supprime aussi les volumes nommés du projet, donc la base MariaDB et les fichiers WordPress. Faites un export avant toute commande avec -v.
Vérification rapide
- docker compose version répond sans erreur.
- docker compose ps montre db en (healthy) et wordpress en Up.
- Le port 8080 n’est publié que sur 127.0.0.1.
- .env est en mode 600 et absent de tout dépôt Git.
- Un export SQL récent est stocké hors du VPS.
Questions fréquentes
Pourquoi no configuration file provided: not found ?
Compose ne trouve ni compose.yaml ni docker-compose.yml dans le dossier courant. Placez-vous dans le dossier du projet avec cd /opt/wordpress, ou indiquez le fichier avec docker compose -f /opt/wordpress/compose.yaml up -d.
Compose affiche « the attribute version is obsolete », est-ce grave ?
Non, c’est un simple avertissement. Compose v2 ignore la ligne version: "3.8" en tête de fichier : supprimez-la pour le faire disparaître, le reste du fichier ne change pas.
Pourquoi port is already allocated ou address already in use au démarrage ?
Un autre conteneur publie déjà ce port, ou un service du VPS (nginx, Apache) l’écoute. Trouvez-le avec docker ps --filter publish=80 et ss -tlnp | grep :80, puis arrêtez-le ou changez le port de gauche dans ports, par exemple "8081:80".
Pourquoi docker: 'compose' is not a docker command ?
Le plugin Compose v2 n’est pas installé. Avec le dépôt officiel de Docker, lancez apt install docker-compose-plugin. Les paquets docker.io et docker-compose des distributions sont en retard ou ne fournissent que l’ancienne commande avec un tiret.
Mes modifications de compose.yaml ne sont pas prises en compte, pourquoi ?
docker compose restart redémarre les conteneurs sans relire le fichier. Lancez docker compose up -d : Compose compare la configuration et recrée les services modifiés. Vérifiez d’abord le fichier avec docker compose config.
Mes données ont-elles disparu après docker compose down ?
Non : docker compose down supprime les conteneurs et le réseau, pas les volumes nommés. Les données ne disparaissent qu’avec down -v, ou si elles étaient écrites dans le conteneur sans volume. docker volume ls liste les volumes, préfixés par le nom du projet, par exemple wordpress_db_data.
Que corriger après yaml: line 8: mapping values are not allowed in this context ?
Le fichier YAML est mal indenté : une tabulation à la place des espaces, ou un niveau décalé. N’utilisez que des espaces (deux par niveau), mettez entre guillemets les valeurs qui contiennent : comme les ports, puis vérifiez avec docker compose config.