Docker-Compose : le guide complet pour vos services auto-hébergés sur Linux

Si vous utilisez Docker pour un projet domotique, vous avez probablement fini par accumulation plusieurs commandes docker run dans un fichier texte pour vous rappeler comment relancer vos conteneurs. C’est le premier signe qu’il est temps de passer à docker-compose. Cet outil transforme vos scripts de lancement en véritable configuration reproductible, versionnable et partagable.

Après des années à gérer des installations Docker manuellement sur mes serveurs, docker-compose a été le changement de workflow le plus significatif. Voici pourquoi et comment je l’utilise concrètement pour Home Assistant, Nextcloud, et d’autres services auto-hébergés.

Docker-compose, kézako ?

Docker-compose est un outil qui permet de définir et gérer plusieurs conteneurs Docker dans un seul fichier de configuration : docker-compose.yml. Là où docker run lance un conteneur à la fois avec une longue ligne de paramètres, docker-compose centralise tout dans un fichier lisible et reproductible.

Exemple concret

Concrètement, au lieu de taper ceci :

docker run -d --name homeassistant --network=host \
  -v /opt/ha/config:/config --restart=unless-stopped \
  homeassistant/home-assistant:stable

Vous écrivez ceci dans docker-compose.yml :

services:
  homeassistant:
    image: homeassistant/home-assistant:stable
    container_name: homeassistant
    network_mode: host
    volumes:
      - /opt/ha/config:/config
    restart: unless-stopped

Puis vous lancez tout avec docker-compose up -d. Et tout est documenté.

Installation

# Installation de Docker (si pas encore fait)
curl -fsSL https://get.docker.com | sh

# Installation de docker-compose
sudo apt update
sudo apt install docker-compose

# Vérification
docker-compose --version

Ou via pip pour une version plus récente :

pip3 install docker-compose

Structure d’un fichier docker-compose.yml

Le fichier se divise en services (chaque conteneur) avec ses paramètres. Voici la structure minimale dont vous aurez besoin 90% du temps :

version: "3.8"
services:
  mon_service:
    image: nom_de_l_image:latest
    container_name: mon_conteneur
    restart: unless-stopped
    ports:
      - "8080:80"          # host:port_conteneur
    volumes:
      - /chemin/local:/app  # host:conteneur
    environment:
      - TZ=Europe/Paris
    networks:
      - mon_reseau

networks:
  mon_reseau:
    driver: bridge

Commandes de base

• docker-compose up -d — Lance tous les services en arrière-plan
• docker-compose down — Arrête et supprime les conteneurs
• docker-compose restart — Redémarre tous les services
• docker-compose logs -f — Suivre les logs en temps réel
• docker-compose ps — Voir le statut de tous les services
• docker-compose pull && docker-compose up -d — Mise à jour en une commande
• docker-compose config — Valider la syntaxe du fichier sans lancer

Exemple complet : Home Assistant + Traefik + Cloudflare Tunnel

version: "3.8"
services:
  homeassistant:
    image: homeassistant/home-assistant:stable
    container_name: homeassistant
    network_mode: host
    volumes:
      - /opt/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
    environment:
      - TZ=Europe/Paris
    restart: unless-stopped

  traefik:
    image: traefik:v3.0
    container_name: traefik
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik/acme.json:/acme.json
      - ./traefik/config.yml:/etc/traefik/config.yml:ro
    environment:
      - CF_API_EMAIL=votre@email.com
      - CF_API_KEY=votre_cloudflare_api_key

  cloudflare-tunnel:
    image: cloudflare/cloudflare:latest
    container_name: cloudflare-tunnel
    restart: unless-stopped
    command: tunnel --config /etc/cloudflared/config.yml run
    volumes:
      - /opt/cloudflared:/etc/cloudflared
    environment:
      - TUNNEL_TOKEN=votre_token

Pourquoi c’est mieux qu’un script de lancement

Reproductibilité

Votre fichier docker-compose est un document. Vous pouvez le versionner avec Git, le partager, le sauvegarder. Si votre serveur lâche demain, vous relancez tout sur un nouveau serveur en 5 minutes avec un git clone && docker-compose up -d.

Mise à jour simple

Pour mettre à jour un service : docker-compose pull && docker-compose up -d. Pas de « je ne sais plus comment j’avais lancé ce conteneur ».

Isolation et réseau

Docker-compose crée automatiquement un réseau Docker bridge pour vos services. Ils communiquent entre eux par leurs noms de conteneurs sans exposer de ports sur l’host.

Les pièges à éviter

Ne mixez pas network_mode: host et ports:

Si vous utilisez network_mode: host (comme pour Home Assistant), vous ne pouvez pas utiliser le mapping de ports. Choisissez l’un ou l’autre.

Chemin absolus pour les volumes

Les volumes sont relatifs au dossier contenant le YAML. Utilisez des chemins absolus pour les données importantes.

Séparez les secrets dans un fichier .env

Créez un fichier .env (ajoutez-le à .gitignore) pour vos tokens et mots de passe.

# .env (NE PAS VERSIONNER)
CF_API_KEY=votre_cle_cloudflare
TZ=Europe/Paris

Pour aller plus loin

• Watchtower — met à jour automatiquement vos conteneurs en arrière-plan
• Portainer — interface web pour gérer vos conteneurs (à mettre derrière Traefik)
• Diun — notifications quand une nouvelle image est publiée
• Ansible — pour automatiser le provisioning du serveur lui-même

---

---

Ressources

• Documentation officielle docker-compose
• Guide d’installation
• Exemples docker-compose sur GitHub