Configurer le daemon Docker (daemon.json)

Ce que vous allez apprendre

• daemon.json : emplacement, structure, options principales
• Storage drivers : overlay2, btrfs, zfs, choix et configuration
• Logging drivers : json-file, journald, fluentd, splunk
• Registries : mirrors, insecure registries, authentification
• Ressources : limites par défaut, cgroups, ulimits
• Production : live restore, userland proxy, metrics

Introduction

Le fichier daemon.json regroupe la configuration de Docker Engine. Il permet de personnaliser le comportement du daemon sans modifier les arguments de ligne de commande systemd. Ce guide couvre toutes les options importantes pour configurer Docker en production : du choix du storage driver à l'exposition des métriques Prometheus.

Appliquer les modifications

Après modification de daemon.json, rechargez ou redémarrez Docker :

# Reload (options compatibles uniquement)
sudo systemctl reload docker

# Restart (toutes les options)
sudo systemctl restart docker

Prérequis

Docker installé Guide d'installation Docker

Commandes Docker Les commandes essentielles

• Accès root ou sudo
• Docker Engine installé (pas Docker Desktop)
• Éditeur de texte (vim, nano)

Emplacement du fichier daemon.json

Le fichier de configuration du daemon Docker varie selon le système d'exploitation.

Système	Emplacement
Linux	/etc/docker/daemon.json
Windows	C:\ProgramData\docker\config\daemon.json
macOS (Docker Desktop)	~/.docker/daemon.json

Glissez pour voir

Fichier à créer

Le fichier daemon.json n'existe pas par défaut. Vous devez le créer manuellement. Docker utilisera les valeurs par défaut pour toutes les options non spécifiées.

Création du fichier sur Linux :

# Créer le répertoire si nécessaire
sudo mkdir -p /etc/docker

# Créer le fichier avec une configuration minimale
sudo tee /etc/docker/daemon.json << 'EOF'
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
EOF

# Redémarrer Docker
sudo systemctl restart docker

Structure et syntaxe

Le fichier daemon.json utilise le format JSON standard. Chaque option doit respecter la syntaxe JSON stricte.

Règles de syntaxe :

• Pas de virgule après le dernier élément
• Les chaînes entre guillemets doubles (")
• Les booléens en minuscules (true, false)
• Pas de commentaires (JSON ne les supporte pas)

Exemple de structure :

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 65535,
      "Soft": 65535
    }
  },
  "live-restore": true,
  "debug": false
}

Validation de la syntaxe

Validez toujours le fichier avant de redémarrer Docker :

# Validation par dockerd
sudo dockerd --validate

# Alternative simple avec jq
jq . /etc/docker/daemon.json

Erreur de syntaxe = Docker ne démarre plus

Une erreur JSON dans daemon.json empêche Docker de démarrer. Validez systématiquement avant d'appliquer.

Storage drivers

Le storage driver gère le système de fichiers des images et conteneurs. Le choix du driver impacte les performances et la compatibilité.

Choisir le bon storage driver

Avant de choisir un driver, il faut savoir quel magasin d'images votre démon utilise. Les deux n'emploient pas le même vocabulaire, et Docker a changé de défaut en cours de route.

Magasin d'images	Ce que docker info affiche	Où on le rencontre
classique	Storage Driver: overlay2	installations montées de version, et daemons en userns-remap
containerd	Storage Driver: overlayfs avec driver-type: io.containerd.snapshotter.v1	installations neuves de Docker Engine 29

Glissez pour voir

Les notes de version de Docker Engine 29 sont explicites sur deux points que l'on confond souvent : le magasin containerd devient le défaut des installations neuves seulement, une machine mise à jour conservant le sien, et le changement ne s'applique pas aux démons configurés en userns-remap.

Les noms se ressemblent et désignent deux mécanismes distincts : overlay2 est l'ancien graph driver de Docker, overlayfs est un snapshotter de containerd. Confondre les deux mène à écrire une configuration qui ne s'applique pas.

Ce que la commande rend réellement. Sur une machine dont le daemon.json ne contient aucun storage-driver, mesuré le 19 septembre 2026 sous Docker Engine 29.1.3 :

docker info | grep -A1 "Storage Driver"

 Storage Driver: overlayfs
  driver-type: io.containerd.snapshotter.v1

Le démon a donc choisi le magasin containerd tout seul, sans qu'on le lui demande. Une conséquence visible immédiatement : docker image ls --tree liste les images par plateforme, ce que le magasin classique ne sait pas faire.

Faut-il déclarer un storage driver ?

Non, dans le cas général. Forcer "storage-driver": "overlay2" sur une installation récente revient à demander l'ancien magasin d'images, et donc à perdre ce que le nouveau apporte : images multi-plateformes en local, attestations, SBOM et provenance rattachés à l'image.

Les drivers du tableau ci-dessous restent utiles pour lire une machine existante, pas pour en configurer une neuve :

Driver	Ce que sa présence signifie
overlayfs	magasin containerd, le défaut d'une installation Docker 29
overlay2	magasin classique, installation héritée ou driver forcé
btrfs, zfs	le stockage de la machine impose déjà ce système de fichiers
devicemapper, aufs	machine ancienne : ces drivers ne sont plus maintenus
vfs	aucune copie sur écriture, très lent, réservé au débogage

Glissez pour voir

Ne déduisez pas le comportement d'une machine depuis une autre

Une installation montée de version depuis un Docker plus ancien peut très bien rester sur le magasin classique et son overlay2. Les deux configurations coexistent donc dans un parc, et un script qui suppose l'une casse sur l'autre. La seule réponse fiable est celle de la machine concernée :

docker info --format '{{.Driver}} {{json .DriverStatus}}'

Changement de storage driver

Changer de storage driver supprime toutes les images et conteneurs existants. Les données de /var/lib/docker sont spécifiques à chaque driver.

Procédure de migration :

# 1. Sauvegarder les images importantes
docker save myapp:latest > myapp.tar

# 2. Arrêter Docker
sudo systemctl stop docker

# 3. Supprimer les données existantes
sudo rm -rf /var/lib/docker

# 4. Modifier daemon.json
sudo vim /etc/docker/daemon.json

# 5. Redémarrer Docker
sudo systemctl start docker

# 6. Recharger les images
docker load < myapp.tar

Partition dédiée /var/lib/docker

En production, utilisez une partition dédiée pour les données Docker. Cela permet :

• D'isoler l'espace disque Docker
• D'utiliser un filesystem adapté (ext4, xfs)
• De faciliter les sauvegardes et migrations

1. Créer et monter la partition

   # Formater la partition (exemple: /dev/sdb1)
   sudo mkfs.ext4 /dev/sdb1
   
   # Créer le point de montage
   sudo mkdir -p /mnt/docker-data
   
   # Monter la partition
   sudo mount /dev/sdb1 /mnt/docker-data
   
   # Ajouter au fstab pour montage automatique
   echo '/dev/sdb1 /mnt/docker-data ext4 defaults 0 2' | sudo tee -a /etc/fstab

2. Migrer les données existantes

   # Arrêter Docker
   sudo systemctl stop docker
   
   # Copier les données
   sudo rsync -aP /var/lib/docker/ /mnt/docker-data/
   
   # Sauvegarder l'ancien répertoire
   sudo mv /var/lib/docker /var/lib/docker.bak

3. Configurer daemon.json

   {
     "data-root": "/mnt/docker-data"
   }

4. Redémarrer et vérifier

   /mnt/docker-data

   sudo systemctl start docker
   docker info | grep "Docker Root Dir"

Logging drivers

Docker supporte plusieurs backends pour les logs des conteneurs. Le choix dépend de votre infrastructure de centralisation.

json-file (défaut)

Le driver par défaut stocke les logs en JSON dans /var/lib/docker/containers/<id>/<id>-json.log.

Rotation obligatoire

Sans rotation, les logs peuvent remplir le disque et crasher le système. Configurez toujours max-size et max-file.

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3",
    "compress": "true",
    "labels": "production_status,team"
  }
}

Option	Description	Exemple
max-size	Taille max par fichier	10m, 100k
max-file	Nombre de fichiers en rotation	3, 5
compress	Compresser les fichiers rotés	true
labels	Labels à inclure dans les logs	env,team

Glissez pour voir

Consulter les logs :

# Via docker logs
docker logs mycontainer

# Fichier direct
cat /var/lib/docker/containers/<id>/<id>-json.log | jq

journald

Le driver journald envoie les logs au journal systemd. Intégration native avec les outils système Linux.

{
  "log-driver": "journald",
  "log-opts": {
    "tag": "{{.Name}}/{{.ID}}"
  }
}

Avantages :

• Rotation automatique par journald
• Métadonnées enrichies
• Intégration journalctl

Consulter les logs :

# Tous les conteneurs
journalctl -u docker.service

# Un conteneur spécifique
journalctl CONTAINER_NAME=mycontainer

# Avec l'ID
journalctl CONTAINER_ID=abc123

Drivers centralisés

Pour les environnements de production, envoyez les logs vers un système centralisé.

Fluentd

{
  "log-driver": "fluentd",
  "log-opts": {
    "fluentd-address": "localhost:24224",
    "tag": "docker.{{.Name}}",
    "fluentd-async": "true"
  }
}

Option	Description
fluentd-address	Adresse du collecteur Fluentd
tag	Tag pour le routage
fluentd-async	Mode asynchrone (recommandé)

Glissez pour voir

Splunk

{
  "log-driver": "splunk",
  "log-opts": {
    "splunk-url": "https://splunk.example.com:8088",
    "splunk-token": "your-hec-token",
    "splunk-index": "docker",
    "splunk-insecureskipverify": "false"
  }
}

Gelf (Graylog)

{
  "log-driver": "gelf",
  "log-opts": {
    "gelf-address": "udp://graylog.example.com:12201",
    "tag": "docker-{{.Name}}"
  }
}

Driver par conteneur

Vous pouvez surcharger le driver au niveau conteneur :

docker run --log-driver=json-file --log-opt max-size=5m myapp

Configuration des registries

Le daemon décide seul d'où viennent les images et à quelles conditions il fait confiance à une source. Trois réglages couvrent ce périmètre : un cache pour éviter de retélécharger les mêmes images, une liste d'exceptions TLS pour les registries internes, et le stockage des identifiants. Les deux premiers vivent dans daemon.json, le troisième non.

Registry mirrors

Un registry mirror est un cache local des images de Docker Hub. Il réduit la bande passante consommée et évite d'atteindre les quotas de téléchargement appliqués aux comptes anonymes et gratuits.

{
  "registry-mirrors": [
    "https://mirror.gcr.io",
    "https://registry.example.com"
  ]
}

Fonctionnement :

1. docker pull nginx interroge d'abord le mirror
2. Si l'image est en cache, téléchargement local (rapide)
3. Sinon, le mirror télécharge depuis Docker Hub et met en cache

Vérifier la configuration :

docker info | grep -A5 "Registry Mirrors"

Mirrors publics

Google propose un mirror gratuit : https://mirror.gcr.io. Utile pour contourner les rate limits Docker Hub.

Insecure registries

Pour les registries internes sans HTTPS ou avec certificats auto-signés :

{
  "insecure-registries": [
    "registry.local:5000",
    "192.168.1.100:5000"
  ]
}

Sécurité

insecure-registries désactive la vérification TLS. Ne jamais utiliser en production exposée. Préférez ajouter le certificat CA :

# Ajouter le certificat
sudo mkdir -p /etc/docker/certs.d/registry.local:5000
sudo cp ca.crt /etc/docker/certs.d/registry.local:5000/

Authentification par défaut

L'authentification aux registries est stockée dans ~/.docker/config.json (par utilisateur, pas dans daemon.json).

# Connexion interactive
docker login registry.example.com

# Vérifier les credentials stockés
cat ~/.docker/config.json

Credential helpers pour stockage sécurisé :

{
  "credHelpers": {
    "gcr.io": "gcloud",
    "*.dkr.ecr.*.amazonaws.com": "ecr-login"
  }
}

Optimisations production

Les options qui suivent ne changent rien au fonctionnement de Docker sur un poste de développement : elles répondent à des contraintes d'exploitation. Continuité de service pendant une mise à jour, supervision des métriques, limites de ressources appliquées à tous les conteneurs, performances réseau. Chacune se teste isolément, car certaines modifient des comportements dont vos applications dépendent peut-être sans que vous le sachiez.

Live restore

Live restore maintient les conteneurs en fonctionnement pendant un redémarrage du daemon Docker.

{
  "live-restore": true
}

Cas d'usage :

• Mise à jour de Docker sans interruption de service
• Récupération après crash du daemon
• Maintenance du daemon

Limitations :

• Ne fonctionne pas si arrêt manuel (systemctl stop docker)
• Les options de runtime ne doivent pas changer entre les versions

Vérification :

# Redémarrer le daemon
sudo systemctl restart docker

# Les conteneurs doivent toujours tourner
docker ps

Metrics Prometheus

Exposez les métriques Docker au format Prometheus pour le monitoring.

{
  "metrics-addr": "0.0.0.0:9323",
  "experimental": true
}

Métriques disponibles :

Métrique	Description
engine_daemon_container_states_containers	Conteneurs par état
engine_daemon_image_actions_seconds	Durée des opérations images
engine_daemon_network_actions_seconds	Durée des opérations réseau
process_cpu_seconds_total	CPU utilisé par le daemon

Glissez pour voir

Accès aux métriques :

curl http://localhost:9323/metrics

Configuration Prometheus (prometheus.yml) :

scrape_configs:
  - job_name: 'docker'
    static_configs:
      - targets: ['docker-host:9323']

Sécuriser l'endpoint

L'endpoint métriques expose des informations sensibles. Limitez l'accès par firewall ou utilisez un reverse proxy avec authentification.

Ressources par défaut

Définissez des limites appliquées à tous les conteneurs par défaut.

{
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 65535,
      "Soft": 65535
    },
    "nproc": {
      "Name": "nproc",
      "Hard": 4096,
      "Soft": 4096
    }
  },
  "default-shm-size": "64M"
}

Option	Description
nofile	Limite de descripteurs de fichiers
nproc	Limite de processus
default-shm-size	Taille de /dev/shm

Glissez pour voir

Surcharge par conteneur :

docker run --ulimit nofile=1024:2048 myapp

Userland proxy

Le userland proxy gère le port forwarding en espace utilisateur. Le désactiver améliore les performances mais peut causer des problèmes avec localhost.

{
  "userland-proxy": false
}

Avantages désactivé :

• Meilleures performances réseau
• Moins de processus (pas de docker-proxy)

Inconvénients :

• Problèmes avec connexions localhost vers conteneurs
• Incompatibilité avec certains scénarios hairpin

Testez avant production

Désactivez le userland-proxy en staging d'abord. Certaines applications dépendent du comportement hairpin.

IPv6

Activez le support IPv6 natif pour les conteneurs. L'option porte sur le réseau bridge par défaut et rend les conteneurs bi-pile : ils conservent leur adresse IPv4 et reçoivent en plus une adresse IPv6 prise dans la plage déclarée.

{
  "ipv6": true,
  "fixed-cidr-v6": "2001:db8:1::/64"
}

Option	Description
ipv6	Active IPv6 sur le bridge par défaut
fixed-cidr-v6	Plage d'adresses IPv6 pour les conteneurs

Glissez pour voir

Vérification :

docker run --rm alpine ip -6 addr show eth0

Validation et rechargement

Une erreur dans daemon.json ne se manifeste qu'au redémarrage du daemon, c'est-à-dire au moment où tous les conteneurs sont déjà arrêtés. D'où la règle : on valide d'abord, on applique ensuite. Reste à choisir comment appliquer, car toutes les options ne se rechargent pas à chaud.

Valider avant d'appliquer

Ces trois commandes vont du plus superficiel au plus complet : jq ne vérifie que la syntaxe JSON, alors que dockerd --validate contrôle aussi que les options existent et sont compatibles entre elles.

# Validation complète par dockerd
sudo dockerd --validate

# Validation JSON simple
jq . /etc/docker/daemon.json

# Valider et voir les valeurs par défaut
sudo dockerd --config-file /etc/docker/daemon.json --validate

Rechargement à chaud vs redémarrage

Certaines options peuvent être appliquées sans redémarrer le daemon (rechargement à chaud via SIGHUP), tandis que d'autres nécessitent un redémarrage complet. Cette distinction est importante en production pour minimiser les interruptions.

Option	Reload (SIGHUP)	Restart
debug	✅	✅
labels	✅	✅
live-restore	✅	✅
max-concurrent-downloads	✅	✅
max-concurrent-uploads	✅	✅
shutdown-timeout	✅	✅
storage-driver	❌	✅
data-root	❌	✅
log-driver	❌	✅
default-runtime	❌	✅

Glissez pour voir

# Reload (options compatibles)
sudo systemctl reload docker
# ou
sudo kill -SIGHUP $(pidof dockerd)

# Restart (toutes les options)
sudo systemctl restart docker

Exemple complet daemon.json production

Voici une configuration de référence pour un environnement de production :

{
  "data-root": "/mnt/docker-data",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "5",
    "compress": "true"
  },
  "live-restore": true,
  "userland-proxy": false,
  "no-new-privileges": true,
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 65535,
      "Soft": 65535
    }
  },
  "default-shm-size": "64M",
  "registry-mirrors": [
    "https://mirror.gcr.io"
  ],
  "metrics-addr": "127.0.0.1:9323",
  "experimental": true,
  "max-concurrent-downloads": 10,
  "max-concurrent-uploads": 5
}

Points clés de cette configuration :

• overlay2 : storage driver performant
• data-root : partition dédiée
• Rotation logs : évite de remplir le disque
• live-restore : continuité de service
• no-new-privileges : sécurité par défaut
• Métriques : monitoring Prometheus (localhost uniquement)

Dépannage

Quand Docker refuse de démarrer après une modification, l'information utile n'est pas dans docker ps, qui ne répond plus, mais dans le journal systemd du service. Le message d'erreur y désigne presque toujours la ligne ou l'option fautive de daemon.json.

Logs du daemon

La première commande affiche le journal du service en continu, la seconde lance le daemon au premier plan en mode bavard pour voir sa configuration effective au démarrage.

# Logs systemd
journalctl -u docker.service -f

# Mode debug
sudo dockerd --debug

Erreurs courantes

Les erreurs de configuration du daemon empêchent généralement Docker de démarrer. Voici les messages d'erreur les plus fréquents et leurs solutions.

Erreur	Cause	Solution
invalid character	Erreur JSON	Valider avec jq
unable to configure the Docker daemon with file	Option invalide	Vérifier la documentation
Error starting daemon: error initializing graphdriver	Storage driver incompatible	Supprimer /var/lib/docker
daemon not running	Erreur de config	Consulter journalctl -u docker
permission denied	Droits fichier	chmod 644 daemon.json

Glissez pour voir

Réinitialiser la configuration

En cas de blocage, écarter le fichier ramène Docker à ses valeurs par défaut et permet de le redémarrer. Renommez plutôt que de supprimer : vous garderez la configuration fautive pour la corriger option par option.

# Arrêter Docker
sudo systemctl stop docker

# Sauvegarder et supprimer la config
sudo mv /etc/docker/daemon.json /etc/docker/daemon.json.bak

# Redémarrer avec config par défaut
sudo systemctl start docker

À retenir

1. daemon.json se trouve dans /etc/docker/ sur Linux et n'existe pas par défaut
2. Le magasin d'images se lit, il ne se force pas : overlayfs sur une installation Docker 29 récente, overlay2 sur une machine héritée
3. Rotation des logs obligatoire avec max-size et max-file
4. registry-mirrors accélèrent les pulls et évitent les rate limits
5. live-restore maintient les conteneurs pendant les redémarrages daemon
6. Validez toujours avec dockerd --validate avant de redémarrer
7. Certaines options nécessitent un restart complet, d'autres supportent reload
8. Partition dédiée pour /var/lib/docker en production

Contrôle des connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

5 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Pour aller plus loin

• Gérer les secrets : Ce que la configuration du démon ne doit jamais contenir.
• Protéger la socket avec un proxy : La suite logique quand un outil tiers réclame l'accès au démon.
• Ce qui se passe sous le capot : Ce que chaque option de daemon.json déclenche côté noyau.

×

📖 Voir la documentation →