Docker Compose : créer et administrer plusieurs services auto-hébergés simplement

Docker Compose permet de définir et gérer plusieurs services auto-hébergés dans un fichier YAML unique, puis de les démarrer avec docker compose up. Cette approche regroupe l’application, sa base de données, ses volumes persistants et son réseau privé sans multiplier les commandes docker run difficiles à maintenir.

Docker Compose est un outil Docker conçu pour décrire une application multi-conteneurs et son état attendu. Ce tutoriel montre comment organiser un projet, créer un fichier compose.yaml, protéger les variables sensibles, vérifier les services, effectuer des sauvegardes et corriger les incidents courants sur un serveur personnel.

Que permet Docker Compose pour les services auto-hébergés ?

Docker Compose sert à créer plusieurs conteneurs qui fonctionnent ensemble, par exemple une interface web, une base PostgreSQL et un outil d’administration. Docker Compose décrit ces composants dans un fichier YAML, crée un réseau de communication entre eux et pilote leur cycle de vie depuis le répertoire du projet.

Le gain réel de Docker Compose est la reproductibilité : la même configuration peut être relancée sur une autre machine équipée de Docker. Docker Compose ne remplace pas l’administration du système hôte, les sauvegardes ni les mises à jour de sécurité, mais il réduit les écarts entre la configuration documentée et celle réellement exécutée.

Docker, image, conteneur, service, volume et réseau

Une image Docker est un modèle immuable utilisé pour créer un conteneur. Un conteneur est une instance en cours d’exécution de cette image. Dans un fichier Compose, un service décrit la manière de lancer un ou plusieurs conteneurs à partir d’une image, avec ses variables, ses volumes, ses ports et son réseau.

Un volume conserve des fichiers en dehors du cycle de vie éphémère du conteneur. Un réseau Docker permet aux services d’un même projet de communiquer entre eux par leur nom de service, sans publier chaque port sur le réseau de la machine.

Élément	Rôle concret	Point de vigilance
Image	Modèle téléchargé pour lancer un logiciel	Choisir une source officielle et une version maîtrisée
Conteneur	Processus isolé exécutant l’image	Les données internes disparaissent lors d’une recréation
Service	Déclaration Compose d’un composant applicatif	Définir ports, dépendances et variables explicitement
Volume	Stockage persistant géré par Docker	Sauvegarder avant toute opération destructive
Réseau	Canal privé entre services du projet	Ne publier que les ports nécessaires

Un conteneur recréable n’est pas une sauvegarde : les volumes et les fichiers de configuration doivent être protégés séparément.

Préparer le serveur et le projet Docker Compose

Un projet Docker Compose propre repose sur trois prérequis : Docker installé, le sous-module Compose disponible et un compte capable d’exécuter Docker. Docker Compose fonctionne sous Linux, macOS et Windows ; Docker Desktop l’inclut sur Windows et macOS, tandis que Linux nécessite une installation adaptée à la distribution et à l’environnement choisi.

La documentation officielle de Docker Compose reste la référence pour vérifier la méthode d’installation correspondant au système utilisé. La syntaxe actuelle est docker compose, avec un espace ; l’ancienne forme docker-compose peut encore apparaître dans des tutoriels anciens, mais elle ne doit pas servir de repère pour une nouvelle installation.

Étape 1 : vérifier Docker et Docker Compose

Ouvrez un terminal sur la machine qui hébergera les services, puis exécutez les deux commandes suivantes. La première vérifie le moteur Docker ; la seconde confirme que le plugin Compose répond.

docker --version
docker compose version

Le résultat attendu est l’affichage d’une version pour chaque commande. Une commande introuvable indique un problème d’installation ou de droits ; ne commencez pas la configuration YAML tant que cette base n’est pas opérationnelle.

Étape 2 : créer un répertoire de projet isolé

Créez un dossier par application ou groupe de services. Cette séparation évite de mélanger les fichiers Compose, les journaux exportés et les variables de plusieurs applications.

mkdir -p ~/services/administration
cd ~/services/administration

Le résultat attendu est un répertoire courant dédié au projet. Docker Compose utilisera normalement ce nom de dossier pour nommer les ressources qu’il crée, notamment le réseau du projet.

Étape 3 : préparer les fichiers à protéger

Créez un fichier .env destiné aux variables locales et un fichier .gitignore si le projet est suivi avec Git. Le fichier .env ne doit pas être partagé publiquement ni ajouté à un dépôt contenant des secrets.

touch .env compose.yaml .gitignore
printf ".env\n" >> .gitignore

Le résultat attendu est une structure minimale, lisible et prête à accueillir la configuration. Les mots de passe ne seront pas écrits dans le fichier Compose partagé.

Comment créer un fichier de configuration Docker Compose ?

Un fichier de configuration Docker Compose décrit les services à lancer, leur stockage persistant, les réseaux qu’ils utilisent et les paramètres injectés au démarrage. Pour un premier déploiement auto-hébergé, partez d’un exemple réduit : une base PostgreSQL privée et Adminer, une interface web temporairement accessible seulement depuis la machine hôte.

La base de données de cet exemple n’ouvre aucun port vers l’extérieur : seul le service Adminer peut l’atteindre via le réseau Docker interne. Le principe est simple : chaque exposition réseau doit être justifiée par un usage réel, pas ajoutée par défaut.

Étape 4 : renseigner les variables sensibles dans .env

Ajoutez des valeurs locales dans .env. Remplacez les exemples par des identifiants robustes avant tout accès externe. Le mot de passe ci-dessous est volontairement un emplacement à compléter, pas une valeur utilisable telle quelle.

POSTGRES_DB=application
POSTGRES_USER=application_user
POSTGRES_PASSWORD=REMPLACEZ_PAR_UN_SECRET_UNIQUE

Le résultat attendu est un fichier séparé contenant les informations variables. Pour un environnement plus exposé ou une équipe, étudiez la gestion de secrets adaptée à votre plateforme plutôt que de multiplier les copies de fichiers .env.

Étape 5 : déclarer les services, le volume et le réseau

Copiez la configuration suivante dans compose.yaml. Les images sont volontairement épinglées à des branches de version plutôt qu’à latest, mais un environnement de production peut exiger un verrouillage encore plus strict, par version précise ou digest selon la politique de maintenance retenue.

services:
  database:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - interne
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5

  adminer:
    image: adminer:4
    ports:
      - "127.0.0.1:8080:8080"
    depends_on:
      database:
        condition: service_healthy
    networks:
      - interne
    restart: unless-stopped

volumes:
  postgres_data:

networks:
  interne:

Le résultat attendu est une définition de deux services reliés par le réseau interne. Depuis Adminer, le nom d’hôte de la base est database, qui correspond au nom du service ; aucune adresse IP Docker fixe n’est nécessaire.

Étape 6 : valider le fichier avant le déploiement

Exécutez la commande suivante dans le répertoire qui contient compose.yaml. Docker Compose résout les variables et affiche la configuration finale qu’il comprend.

docker compose config

Le résultat attendu est une configuration développée sans erreur de syntaxe. Une variable vide, une indentation YAML incorrecte ou une clé mal placée doit être corrigée ici, avant de créer les conteneurs.

Le fichier Compose décrit le déploiement ; le fichier .env porte les valeurs locales ; une sauvegarde protège les données. Ces trois fonctions ne doivent pas être confondues.

Comment démarrer et vérifier les services Docker Compose ?

Docker Compose démarre l’ensemble du projet avec une seule commande et conserve l’état de chaque service pour faciliter le diagnostic. Après le démarrage, vérifiez d’abord l’état des conteneurs, puis les journaux du service concerné ; ouvrir une interface web sans contrôler les journaux masque souvent une erreur de démarrage utile.

Étape 7 : lancer le projet en arrière-plan

Lancez les services avec l’option -d afin de rendre la main au terminal. Docker récupère les images absentes, crée le réseau et le volume, puis démarre les conteneurs déclarés.

docker compose up -d

Le résultat attendu est la création des services database et adminer. Le premier téléchargement d’une image peut prendre plus de temps selon la connexion et la taille de l’image.

Étape 8 : contrôler l’état et lire les journaux

Utilisez docker compose ps pour afficher l’état des services, puis docker compose logs pour examiner les messages de démarrage. Ajoutez le nom d’un service pour réduire le bruit lorsque le projet contient plusieurs conteneurs.

docker compose ps
docker compose logs --tail=100 database
docker compose logs -f adminer

Le résultat attendu est un service PostgreSQL déclaré sain après son contrôle de santé et un service Adminer en cours d’exécution. La commande avec -f suit les nouveaux journaux ; arrêtez-la avec Ctrl+C, sans arrêter les conteneurs.

Étape 9 : tester la communication interne

Accédez à http://127.0.0.1:8080 depuis la machine hôte. Dans Adminer, indiquez database comme serveur, puis utilisez les valeurs du fichier .env pour vous connecter à PostgreSQL.

Le résultat attendu est une connexion à la base sans publication directe du port PostgreSQL. Sur un serveur distant, ne rendez pas ce port accessible en modifiant hâtivement 127.0.0.1 ; passez plutôt par un accès administrateur sécurisé, un tunnel adapté ou un proxy correctement configuré.

Administrer Docker Compose au quotidien

Docker Compose permet d’arrêter, redémarrer, reconstruire et inspecter un projet sans toucher aux autres projets présents sur le serveur. Les commandes doivent être exécutées dans le répertoire du bon fichier Compose, car un même hôte peut gérer plusieurs ensembles de services indépendants.

• docker compose stop arrête les conteneurs sans supprimer leur configuration.
• docker compose start redémarre les conteneurs déjà créés.
• docker compose restart adminer redémarre uniquement le service Adminer.
• docker compose exec database sh ouvre une commande dans le conteneur PostgreSQL, si l’image fournit un shell compatible.
• docker compose down arrête et supprime les conteneurs et le réseau du projet, mais conserve normalement les volumes nommés.

La commande docker compose down -v supprime aussi les volumes nommés et peut donc effacer les données persistantes. N’utilisez jamais l’option -v comme commande de nettoyage de routine sans sauvegarde vérifiée et sans comprendre les volumes visés.

Mettre à jour un conteneur sans perdre les données

Une mise à jour consiste généralement à récupérer une image, puis à recréer les conteneurs concernés avec la configuration existante. Le volume postgres_data reste séparé du conteneur ; cette séparation protège les données contre une recréation normale, pas contre une suppression volontaire du volume.

docker compose pull
docker compose up -d
docker compose ps

Le résultat attendu est le redémarrage des services avec les images téléchargées. Consultez les notes de version de l’image et effectuez une sauvegarde avant une mise à niveau majeure de base de données, car la compatibilité des formats de données dépend du logiciel concerné.

Configurer le redémarrage automatique avec prudence

La politique restart: unless-stopped de l’exemple redémarre un service après un incident ou un redémarrage de l’hôte, sauf si vous l’avez arrêté explicitement. Cette automatisation améliore la disponibilité, mais elle ne corrige ni une boucle d’erreur ni une configuration invalide.

Un redémarrage répété produit des journaux et consomme des ressources sans résoudre la cause. Contrôlez les logs et l’état du conteneur avant de conclure qu’une politique de redémarrage a « réparé » un service.

Protéger les services auto-hébergés et leurs données

Un serveur personnel exposé sur Internet reste responsable de son système d’exploitation, de ses comptes, de ses règles réseau et de ses images Docker. Docker Compose aide à structurer les services auto-hébergés, mais Docker Compose ne fournit pas une sécurité automatique à un service mal configuré ou non maintenu.

Réduire les ports publiés

Publiez un port seulement lorsqu’un utilisateur ou un autre système doit réellement atteindre le service. Dans l’exemple, 127.0.0.1:8080:8080 limite Adminer à la machine hôte ; PostgreSQL n’a aucune section ports, donc il reste joignable uniquement depuis le réseau Docker du projet.

Un service web destiné à Internet nécessite généralement une couche supplémentaire, comme un proxy inverse configuré avec TLS et des règles d’accès. Le choix du proxy dépend de l’architecture ; l’essentiel est de ne pas exposer une interface d’administration ou une base de données par défaut.

Sauvegarder avant de compter sur les volumes

Un volume Docker garantit la persistance entre deux conteneurs ; il ne protège pas contre une suppression, une corruption logique, un ransomware sur l’hôte ou une erreur humaine. Une sauvegarde utile est copiée hors du serveur et testée par une restauration dans un environnement isolé.

1. Identifiez les volumes et les fichiers de configuration qui contiennent des données métier.
2. Exportez les données avec l’outil recommandé par l’application, par exemple une sauvegarde logique pour une base de données.
3. Copiez les exports vers un emplacement distinct du serveur hébergé.
4. Documentez la procédure de restauration et testez-la périodiquement.

Une sauvegarde non restaurée au moins une fois est une hypothèse, pas une garantie de reprise. La fréquence dépend du volume de données et de la perte acceptable, deux critères qui doivent être définis avant un incident.

Erreurs fréquentes avec Docker Compose et comment les éviter

Les erreurs Docker Compose les plus courantes viennent d’un mauvais périmètre réseau, d’une variable manquante ou d’une confusion entre conteneur et volume. Les messages affichés par docker compose config, docker compose ps et docker compose logs permettent généralement d’isoler le problème sans supprimer le projet.

• Une indentation YAML incorrecte : YAML dépend des espaces. Exécutez docker compose config après chaque modification importante.
• Un port déjà occupé : le démarrage échoue si un autre service utilise le port publié. Changez le port hôte ou arrêtez le processus légitime qui l’occupe après identification.
• Une base exposée inutilement : ajouter ports à PostgreSQL rend le service potentiellement accessible hors du réseau Docker. Supprimez cette publication si aucun client externe n’en a besoin.
• Des variables absentes : un .env manquant ou incomplet peut fournir des valeurs vides. Vérifiez la sortie de docker compose config, sans partager les secrets affichés.
• Une suppression de volume involontaire : la commande down -v efface les volumes nommés du projet. Sauvegardez avant toute action incluant -v.

Quand un service ne joint pas la base de données

Un service Docker Compose doit utiliser le nom du service cible comme hôte sur le réseau interne, par exemple database, et non localhost. Dans un conteneur, localhost désigne le conteneur lui-même ; cette confusion explique de nombreux refus de connexion.

Vérifiez également que les deux services appartiennent au même réseau Compose et que les identifiants fournis correspondent à ceux définis au premier démarrage de la base. Les journaux du client et de PostgreSQL donnent des indices différents : nom d’hôte introuvable, refus réseau ou erreur d’authentification.

Docker Compose, docker run, Docker Swarm ou Kubernetes : que choisir ?

Docker Compose convient à un serveur personnel, à un environnement de développement ou à un petit ensemble de services où la configuration doit rester lisible dans un fichier. La commande docker run convient à un conteneur isolé ou à un test ponctuel ; Docker Swarm et Kubernetes répondent à des besoins d’orchestration distribuée plus larges, avec une charge d’exploitation supérieure.

Outil	Usage adapté	Limite principale
docker run	Test rapide ou service unique	Les options deviennent difficiles à reproduire à plusieurs services
Docker Compose	Serveur personnel, développement, petit groupe de services	Ce n’est pas une plateforme complète pour un cluster distribué
Docker Swarm	Cas nécessitant une orchestration Docker sur plusieurs nœuds	Écosystème et choix d’intégration à évaluer selon le besoin
Kubernetes	Plateformes distribuées avec besoins d’exploitation avancés	Complexité de déploiement, de sécurité et de supervision plus élevée

Le bon arbitrage ne consiste pas à adopter l’outil le plus complexe. Pour administrer quelques services auto-hébergés sur une seule machine, Docker Compose apporte souvent le niveau de structuration utile sans imposer l’infrastructure et les compétences opérationnelles d’un cluster.

Liste de contrôle avant de publier un service

Un déploiement auto-hébergé prêt à durer doit pouvoir être relancé, surveillé et restauré sans dépendre de commandes mémorisées. Passez cette liste en revue avant d’ouvrir un accès à des utilisateurs ou à Internet.

• Le fichier compose.yaml passe la validation docker compose config.
• Les secrets sont hors du dépôt et les droits d’accès au fichier .env sont limités.
• Les volumes contenant les données importantes sont identifiés et inclus dans la stratégie de sauvegarde.
• Les bases de données et consoles d’administration ne sont pas exposées sans nécessité.
• Les images, le système hôte et les comptes administrateurs disposent d’une procédure de mise à jour.
• Les journaux et la procédure de restauration ont été vérifiés avant un incident.

Questions fréquentes sur Docker Compose

Docker Compose est-il adapté à un serveur personnel ?

Docker Compose est adapté à un serveur personnel qui héberge un nombre raisonnable de services sur une machine ou un petit périmètre. Docker Compose facilite le démarrage, l’arrêt et la documentation de l’ensemble, mais le système hôte, le pare-feu, les sauvegardes et les comptes restent à administrer.

Comment conserver les données après une mise à jour de conteneur ?

Les données doivent être placées dans un volume nommé ou un montage persistant déclaré dans le fichier Compose. La recréation normale d’un conteneur conserve ce volume, mais une commande de suppression incluant -v peut l’effacer.

Peut-on administrer un service sans arrêter les autres ?

Docker Compose accepte un nom de service dans plusieurs commandes, par exemple docker compose restart adminer ou docker compose logs database. Cette approche limite l’intervention au composant concerné, sous réserve que les dépendances applicatives tolèrent ce redémarrage.

Faut-il exposer chaque service sur Internet ?

Non. Les services internes, notamment les bases de données, n’ont généralement pas besoin d’un port publié. Un réseau Docker permet aux conteneurs d’un même projet de communiquer sans rendre ces composants accessibles depuis l’extérieur.

Pourquoi Docker Compose utilise-t-il le nom du service comme adresse ?

Docker Compose crée un réseau de projet qui permet aux services de se résoudre par leur nom. Dans l’exemple, Adminer joint PostgreSQL avec l’hôte database, ce qui évite de dépendre d’une adresse IP de conteneur susceptible de changer.