====== Docker & Docker Compose ======

Dernière mise à jour : juin 2026

Procédure d'installation de Docker CE depuis le dépôt officiel sur Debian Trixie, et commandes de base pour l'utilisation au quotidien.

===== Pourquoi le dépôt officiel ? =====

Debian fournit un paquet ''docker.io'', mais il est souvent en retard sur les versions. Le dépôt officiel Docker fournit ''docker-ce'', plus à jour, avec le plugin Compose v2 intégré (commande ''docker compose'' sans tiret).

===== Installation =====

==== 1. Prérequis ====

<code bash>
apt install -y ca-certificates curl gnupg
</code>

==== 2. Clé GPG et dépôt ====

<code bash>
install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/debian/gpg \
  | gpg --dearmor -o /etc/apt/keyrings/docker.gpg

chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/debian trixie stable" \
  > /etc/apt/sources.list.d/docker.list
</code>

==== 3. Installation des paquets ====

<code bash>
apt update

apt install -y \
  docker-ce \
  docker-ce-cli \
  containerd.io \
  docker-buildx-plugin \
  docker-compose-plugin
</code>

==== 4. Vérification ====

<code bash>
docker version
docker compose version
systemctl status docker
</code>

==== 5. Utiliser Docker sans sudo (optionnel) ====

<code bash>
usermod -aG docker tonuser
# se déconnecter / reconnecter pour que le groupe soit pris en compte
</code>

===== Mises à jour automatiques =====

Docker se met à jour avec le système via ''apt''. Pour inclure Docker dans les mises à jour de sécurité automatiques :

<code bash>
apt install -y unattended-upgrades apt-listchanges
dpkg-reconfigure unattended-upgrades   # répondre "Oui"
</code>

Dans ''/etc/apt/apt.conf.d/50unattended-upgrades'', ajouter la ligne Docker dans le bloc Origins-Pattern :

<code>
Unattended-Upgrade::Origins-Pattern {
    "origin=Debian,codename=${distro_codename},label=Debian-Security";
    "origin=Docker";
};
</code>

Vérifier que Docker est bien pris en compte :

<code bash>
unattended-upgrade --dry-run --debug 2>&1 | grep -i docker
</code>

**Note :** une mise à jour de Docker redémarre le daemon. Les conteneurs avec ''restart: unless-stopped'' redémarrent automatiquement. Pour un homelab sans contrainte de disponibilité stricte, les mises à jour automatiques sont adaptées.

===== Structure des projets =====

Convention utilisée sur le serveur principal :

<code>
/mnt/stockage/docker/
├── compose/          ← un sous-dossier par stack, contenant docker-compose.yml
│   ├── surveillance/
│   ├── auth/
│   ├── nextcloud/
│   └── ...
└── data/             ← données persistantes (bind mounts vers le RAID)
    ├── uptime-kuma/
    ├── kanidm/
    └── ...
</code>

**Principe clé :** les données persistantes vivent dans ''data/'', jamais dans les conteneurs. Un conteneur est jetable ; les données ne le sont pas.

===== Utilisation de base =====

==== Cycle de vie d'une stack ====

Depuis le répertoire contenant le ''docker-compose.yml'' :

<code bash>
# Démarrer / créer / mettre à jour (recrée les conteneurs qui ont changé)
docker compose up -d

# État des conteneurs de la stack
docker compose ps

# Arrêter la stack (conserve les conteneurs)
docker compose stop

# Arrêter et supprimer les conteneurs (conserve les volumes/données)
docker compose down

# Redémarrer un service (SANS relire le compose)
docker compose restart nom_service
</code>

**Important :** ''docker compose restart'' ne relit pas le fichier ''docker-compose.yml''. Après toute modification du compose, utiliser ''docker compose up -d'' pour appliquer les changements.

==== Logs ====

<code bash>
# Logs d'un service en continu
docker compose logs -f nom_service

# Logs de toute la stack
docker compose logs -f

# Dernières lignes seulement
docker compose logs --tail 50 nom_service
</code>

==== Mise à jour des images ====

<code bash>
# Récupérer les dernières images
docker compose pull

# Recréer les conteneurs avec les nouvelles images
docker compose up -d
</code>

==== Exécuter une commande dans un conteneur ====

<code bash>
# Shell interactif
docker compose exec nom_service bash

# ou directement avec docker
docker exec -it nom_conteneur bash

# Commande ponctuelle
docker exec -it nom_conteneur une_commande
</code>

==== Lancer un conteneur jetable ====

Utile pour des opérations ponctuelles (ex. génération de certificats, outils CLI) :

<code bash>
docker run --rm -it \
  -v /chemin/hote:/chemin/conteneur \
  image:tag \
  commande
</code>

  * ''--rm'' : supprime le conteneur après exécution
  * ''-it'' : mode interactif avec terminal
  * ''-v'' : montage d'un volume

===== Réseaux et ports =====

==== Syntaxe des ports ====

Dans le compose : ''"PORT_HOTE:PORT_CONTENEUR"''

<code yaml>
ports:
  - "3002:3000"               # écoute sur toutes les interfaces de l'hôte
  - "192.168.1.9:3002:3000"   # écoute uniquement sur l'IP LAN
  - "127.0.0.1:3002:3000"     # écoute uniquement en local (accès via tunnel/proxy)
</code>

Lier les ports à une IP précise est plus sûr que d'exposer sur ''0.0.0.0'' (toutes les interfaces).

==== Communication entre conteneurs ====

  * Les conteneurs d'une même stack se joignent par leur **nom de service** sur le réseau Docker interne
  * Un conteneur qui veut joindre un service de l'**hôte** (ex. MariaDB bare-metal) passe par l'IP de la gateway Docker, pas par ''127.0.0.1'' (qui désigne le conteneur lui-même)

<code bash>
# Trouver l'IP de la gateway d'un réseau
docker network inspect nom_reseau | grep Gateway
</code>

===== Diagnostic =====

<code bash>
# Lister tous les conteneurs (y compris arrêtés)
docker ps -a

# Inspecter un conteneur
docker inspect nom_conteneur

# Voir l'utilisation des ressources en temps réel
docker stats

# Lister les réseaux
docker network ls

# Lister les volumes
docker volume ls

# Nettoyer les ressources inutilisées (images, conteneurs, réseaux orphelins)
docker system prune

# Espace disque utilisé par Docker
docker system df
</code>

===== Bonnes pratiques retenues =====

  * Un sous-dossier ''compose/'' par stack, données dans ''data/''
  * ''restart: unless-stopped'' sur les services à garder actifs
  * Lier les ports à l'IP LAN du serveur plutôt qu'à ''0.0.0.0''
  * ''docker compose up -d'' après chaque modif du compose (pas ''restart'')
  * Données persistantes sur le RAID via bind mounts, jamais dans les conteneurs
  * Surveiller les ports déjà utilisés sur l'hôte avant d'exposer un service (''ss -tlnp | grep PORT'')