Docker, de la boîte à une vraie appli

Tout dev l'a vécu. Ton appli marche sur ton ordi. Tu la mets sur le serveur, et elle plante. Pas la même version de Python, une librairie qui manque, un réglage du système qui diffère. Le code est le même, c'est tout ce qu'il y a autour qui a changé.

Docker règle ça en emballant ton appli avec tout ce dont elle a besoin : le bon Python ou le bon Node, les librairies, les fichiers. Cet emballage, c'est un conteneur. La doc de Docker le définit en une phrase : un conteneur, c'est un process isolé, avec tous les fichiers dont il a besoin pour tourner.

La nuance qui compte : ce n'est pas une machine virtuelle. Une VM (virtual machine) fait tourner un système d'exploitation entier, avec son propre noyau — le cœur du système, celui qui parle au matériel. Un conteneur, lui, emprunte le noyau de la machine qui l'héberge. Il n'a rien à démarrer à part ton appli, c'est pour ça qu'il démarre presque tout de suite, et qu'on en fait tourner beaucoup sur une petite machine.

C'est la confusion numéro un, alors on la règle tout de suite.

• L'image est un paquet figé : le système de fichiers de ton appli, et la commande à lancer. Elle ne tourne pas. Elle ne change jamais une fois fabriquée.
• Le conteneur est une image qui tourne. Tu peux en lancer dix à partir de la même image : dix conteneurs identiques au départ, chacun sa vie ensuite.
• Le Dockerfile est la recette qui fabrique l'image. Un fichier texte, dans ton projet. On y revient en partie 3.

Pour essayer, installe Docker Desktop (Mac, Windows) ou Docker Engine (Linux), puis lance ton premier conteneur : un serveur web nginx, sorti d'une image toute prête.

Docker n'avait pas l'image ? Il l'a téléchargée tout seul, puis il en a sorti un conteneur. Le -d le lance en arrière-plan, le -p ouvre un port (section 6). Pour tout arrêter : docker stop mon-nginx, puis docker rm mon-nginx. L'image, elle, reste sur ta machine, prête pour le prochain gâteau.

Docker Hub, c'est la bibliothèque publique d'images : Python, Node, Postgres, Redis, nginx… Les plus sûres portent le badge Docker Official Image. Quand tu écris nginx, Docker comprend docker.io/library/nginx:latest : le registre (Docker Hub), l'espace des images officielles (library), le nom, et le tag après les deux-points.

Le tag dit quelle version tu veux. Et il y a un piège dans le mot latest : ce n'est pas « la dernière version ». C'est juste le tag que Docker prend quand tu n'en écris aucun. Il pointe sur ce que l'éditeur a décidé, et il bouge sans te prévenir. Ton image de lundi et celle de jeudi peuvent partir de deux bases différentes, avec le même Dockerfile.

Le tag dit aussi quelle variante. Pour la même version de Python, voilà ce qu'affiche Docker Hub :

Même écart côté Node : 410 Mo pour node:24, 81 Mo pour node:24-slim, 62 Mo pour node:24-alpine. Une image plus petite se télécharge plus vite, se déploie plus vite, et embarque moins de logiciels où trouver des failles.

Alpine a un prix : elle n'utilise pas la même bibliothèque C que Debian (musl au lieu de glibc). La page officielle de l'image Python le dit elle-même : certains logiciels s'y cassent, selon ce qu'ils attendent du système. Et il n'y a ni bash ni git par défaut.

Quand un conteneur écrit un fichier, il l'écrit dans une couche à lui, posée sur l'image. Cette couche meurt avec le conteneur. C'est voulu : un conteneur doit pouvoir être jeté et recréé à tout moment. Une nouvelle version de ton appli, c'est un nouveau conteneur, pas une mise à jour de l'ancien.

Tout ce qui doit survivre sort donc de la boîte. Deux façons :

• Un volume : un espace de stockage géré par Docker, que tu branches dans le conteneur à un chemin précis. Le conteneur meurt, le volume reste. C'est ce qu'on utilise pour une base de données.
• Un bind mount : un dossier de ta machine, branché tel quel dans le conteneur. Pratique en développement, pour voir tes modifs de code sans refabriquer l'image.

Dans le cloud, c'est la même idée à plus grande échelle : la base tourne à côté, dans un service fait pour ça, et les fichiers partent dans un stockage objet. La boîte, elle, reste jetable.

L'adresse de la base, le mode debug, l'URL du site : rien de ça ne s'écrit dans l'image. Ça se donne au conteneur quand il démarre, par des variables d'environnement. Ton code les lit (os.environ en Python, process.env en Node), et la même image sert partout.

Les secrets (mots de passe, clés d'API) suivent la même règle, en plus strict : ils ne doivent jamais entrer dans l'image. Une image se partage, se pousse sur un registre, se garde des mois. Tout ce qui est dedans, n'importe qui qui a l'image peut le lire. Et un secret écrit dans une ligne ENV du Dockerfile est dans l'image, pour toujours.

Sur un serveur, les valeurs vivent dans l'outil qui déploie (Coolify, un fichier .env protégé, le gestionnaire de secrets de ton cloud), et le fichier Compose ne contient que des ${NOM_DE_LA_VARIABLE}. On le fait pour de vrai en section 20, sur le Compose d'Umami.

Un conteneur a son propre réseau. Ton appli y écoute sur le port 8000, mais ce 8000-là est dans la boîte : ton navigateur ne le voit pas. -p publie un port, dans cet ordre : port de ta machine : port du conteneur.

Deux détails qui évitent des heures de recherche :

• Ton appli doit écouter sur 0.0.0.0, pas sur localhost. Dans le conteneur, localhost veut dire « le conteneur lui-même » : une appli qui n'écoute que là ne reçoit rien de dehors, même avec le bon -p.
• Sur un serveur, -p 5432:5432 ouvre ta base à internet. Par défaut, le port est publié sur toutes les adresses de la machine. Et sur Linux, le trafic d'un port publié par Docker passe avant les règles du pare-feu ufw : la doc Docker le dit noir sur blanc, ta règle ufw est ignorée. Une base n'a pas besoin de port publié : les autres conteneurs la joignent par le réseau Docker (section 15). Si tu dois vraiment l'ouvrir, limite-la à ta machine : -p 127.0.0.1:5432:5432.

Un conteneur qui « ne marche pas », c'est presque toujours l'un des trois : il s'est arrêté (ps -a te le dit), il a écrit une erreur (logs), ou il tourne mais pas comme tu crois (exec, et tu vas voir).

Dans un conteneur, prends sh plutôt que bash : les images légères n'ont souvent que sh. Et tout ce que tu modifies à la main là-dedans disparaîtra avec le conteneur (section 4). exec sert à regarder, pas à réparer : la réparation, c'est dans le Dockerfile.

Pour que docker logs serve à quelque chose, ton appli doit écrire ses logs sur la sortie standard, pas dans un fichier. C'est ce que font les images officielles, et c'est ce que Docker attend.

docker stop envoie au process principal du conteneur un signal pour lui dire « arrête-toi proprement » (SIGTERM). S'il n'est pas parti au bout de 10 secondes, Docker le tue (SIGKILL). Garde ces 10 secondes en tête : on les retrouve en section 13, et elles expliquent pourquoi certains conteneurs mettent toujours 10 secondes à s'arrêter.

docker system prune ne touche pas aux volumes par défaut : c'est voulu, pour ne pas perdre de données. Il existe une option --volumes. Ne la tape jamais sur un serveur sans savoir exactement quels volumes vont partir.

Voilà le Dockerfile d'une petite appli Python (Flask, servie par gunicorn), qui se connecte à une base Postgres. Je l'ai construit et lancé avant de l'écrire ici : il marche tel quel. Chaque ligne est une instruction, en majuscules, suivie de ses arguments.

Les instructions que tu croiseras le plus :

La colonne « quand » est celle qui compte. Tout ce qui est RUN et COPY se passe une fois, quand tu fabriques l'image. Au démarrage du conteneur, il ne se passe qu'une chose : CMD. Un pip install ne se relance pas à chaque démarrage, il est déjà dans l'image.

Une image n'est pas un bloc : c'est une pile de couches. RUN, COPY et ADD en ajoutent chacune une. Quand tu relances docker build, Docker regarde chaque ligne : rien n'a changé ? Il reprend la couche en cache, instantanément. Mais la doc est claire : dès qu'une couche change, toutes celles qui viennent après se refont, même si elles n'ont rien à voir.

D'où l'ordre du Dockerfile de la section 9. J'ai modifié app.py et relancé le build : les couches jusqu'au pip install sont sorties en CACHED, seule la copie du code s'est refaite. Si le Dockerfile commençait par COPY . ., chaque virgule changée dans le code relancerait l'installation de toutes les dépendances.

Deux conséquences qu'on oublie :

• Une couche ne s'efface pas. Un fichier copié dans une couche puis supprimé dans la suivante est toujours dans l'image, dans la couche d'avant. C'est pour ça que le nettoyage se fait dans le même RUN que l'installation : apt-get update && apt-get install … && rm -rf /var/lib/apt/lists/*.
• apt-get update seul sur sa ligne est un piège : sa couche reste en cache, et un apt-get install ajouté plus tard part d'une liste de paquets périmée. La doc demande de les mettre dans le même RUN.

Au moment du docker build, Docker envoie le dossier du projet au moteur de build : c'est le contexte. Le fichier .dockerignore, à la racine, dit ce qui n'en fait pas partie. Même syntaxe qu'un .gitignore.

Trois raisons, par ordre d'importance :

1. Les secrets. Sans lui, ton .env part dans l'image au premier COPY . ..
2. Le cache. Sans lui, toucher n'importe quel fichier (un log, un fichier du .git) change la couche COPY . . et relance tout ce qui suit.
3. La taille et la justesse. Tes node_modules ont été installés pour ton Mac ; l'image doit installer les siens, pour Linux.

Pour construire un site React ou Vue, il te faut Node, npm, et des centaines de Mo de dépendances. Pour le servir, il te faut un dossier de fichiers statiques et un serveur web. Le multi-stage met les deux dans le même Dockerfile, avec plusieurs FROM. Chaque FROM ouvre un étage ; le dernier devient l'image. COPY --from va chercher un fichier dans un étage précédent.

Node, npm et les node_modules restent dans l'étage 1, qui est jeté. L'image finale, c'est nginx et ton dossier dist. Rien d'autre.

Une de mes applis en prod est construite comme ça, en trois étages : un étage de base avec ce qu'il lui faut pour tourner, un étage de construction qui ajoute les compilateurs et fait le build, puis l'image finale, qui repart de l'étage de base et ne récupère que le résultat. Et comme en section 10, les dépendances sont téléchargées à partir du seul fichier de verrouillage (lockfile) avant de copier le code : une modif de code ne retélécharge rien.

Cette image, je ne la construis jamais sur le serveur. Le build demande à lui seul environ 4 Go de mémoire, et le serveur en a 4, déjà pris par la prod. C'est la CI (GitHub Actions) qui fabrique l'image à chaque version et la pousse sur un registre. Le serveur ne fait que la tirer et la lancer. Tu feras pareil en partie 5 : tu tireras une image qu'une autre équipe a construite.

Demande un Dockerfile à n'importe quel assistant, tu en auras un qui build. C'est justement le problème : les pièges d'un Dockerfile ne font pas d'erreur. L'image se construit, le conteneur démarre, et le souci ne se voit que plus tard — un secret qui fuit, un build qui refait tout à chaque modif, un arrêt qui traîne. Ce ne sont pas des défauts « de l'IA » : ce sont les pièges classiques, documentés par Docker, que n'importe quel Dockerfile peut contenir. Ta relecture passe sur chacun.

Le test des points 8 et 9. J'ai lancé la même petite appli de quatre façons, puis mesuré le temps de docker stop :

10 secondes, c'est le délai de docker stop (section 8) : l'appli n'a jamais entendu le signal, Docker a fini par la tuer. Dans le deuxième cas, la forme exec ne suffit pas : le process qui tourne en premier dans un conteneur (le « PID 1 ») n'a pas de réaction par défaut aux signaux, il faut que le programme les gère lui-même. Un process tué d'office, c'est une requête coupée en plein milieu et un déploiement qui prend 10 secondes de trop. --init (ou init: true dans Compose) glisse un mini-process devant ton appli, qui fait suivre les signaux.

Sans Compose, pour lancer l'appli de la section 9 avec sa base, il faut créer un réseau, un volume, et taper deux docker run de trois lignes chacun, dans le bon ordre. Avec Compose, tu décris le résultat voulu dans un fichier, et docker compose up s'occupe du reste. Le fichier s'appelle compose.yaml : c'est le nom préféré par Docker (docker-compose.yaml marche encore, pour la compatibilité). La ligne version: qu'on voit en tête des vieux tutos ne sert plus à rien : Compose affiche un avertissement et l'ignore.

Voilà le fichier de l'appli Python + Postgres, commenté. Je l'ai lancé tel quel : l'appli répond et lit la version de Postgres dans la base.

Tu vois tout ce qu'on a vu jusqu'ici : l'image fabriquée par le Dockerfile (build), une image de Docker Hub à version fixe, un port publié, la config dehors, le secret dans une variable, les données dans un volume. ${POSTGRES_PASSWORD} est remplacé par la valeur du fichier .env posé à côté du compose.yaml : Compose le lit tout seul.

Au up, Compose crée un réseau pour le projet (<nom-du-projet>_default) et y branche tous les services. Chaque service y est enregistré sous son nom : un conteneur joint l'autre en l'appelant par son nom, comme une adresse. Dans l'exemple, db dans DATABASE_URL, c'est le service db.

La doc insiste sur un point qui piège tout le monde : entre conteneurs, on utilise le port du conteneur. Le port de ta machine (la partie gauche de ports:) ne sert qu'à entrer depuis l'extérieur. La base écoute sur 5432 dans son conteneur, l'appli joint db:5432, et la base n'a besoin d'aucun ports:.

Tu peux aussi déclarer tes propres réseaux, pour isoler des groupes de services, ou brancher un fichier Compose sur un réseau créé ailleurs (external: true). Je m'en sers en prod pour séparer l'infra de l'appli : c'est l'histoire de la section 16.

Postgres démarre en une seconde, mais met un peu plus longtemps à accepter des connexions. Si ton appli se lance entre les deux, elle plante. depends_on ne suffit pas tout seul : la doc de Compose le dit, par défaut il attend que le conteneur tourne, pas qu'il soit prêt. Il existe trois conditions :

Le healthcheck, c'est une commande que Docker lance régulièrement dans le conteneur. Elle réussit : le conteneur est healthy. Elle rate plusieurs fois de suite : unhealthy. Pour Postgres, pg_isready ; pour Redis, redis-cli ping. Ses réglages :

• interval : le temps entre deux vérifications (30 s par défaut) ;
• timeout : au-delà, la vérification compte comme ratée (30 s par défaut) ;
• retries : le nombre d'échecs de suite avant unhealthy (3 par défaut) ;
• start_period : un temps de grâce au démarrage, où les échecs ne comptent pas (0 par défaut).

Et la limite qu'on découvre en prod : depends_on ne vaut que dans un même projet Compose. Il ne voit que les services du même fichier (ou des fichiers fusionnés avec -f). Il ne sait rien d'une base lancée ailleurs. Et il ne joue qu'au démarrage : si la base redémarre plus tard, ton appli doit savoir se reconnecter toute seule.

Dernier réglage, restart : ce que Docker fait quand le conteneur s'arrête. no (défaut) : rien. always : il le relance, y compris au redémarrage de Docker. unless-stopped : pareil, sauf si c'est toi qui l'as arrêté. on-failure : seulement s'il s'est arrêté sur une erreur.

Ce que ça a donné chez moi. Une de mes applis en prod : sept services, un seul serveur. Au départ, tout vivait dans un seul fichier Compose, et mon outil de déploiement recréait les sept conteneurs à chaque mise en ligne, base comprise. Un des services met deux minutes à démarrer, et l'appli l'attendait. Résultat : trois à quatre minutes de coupure à chaque déploiement. Ce chiffre-là est une estimation, je ne l'avais pas chronométré.

J'ai coupé en deux fichiers. L'infra d'un côté (la base, le cache, le service lent), déployée une fois, puis on n'y touche plus. L'appli de l'autre, la seule qu'on redéploie. Les deux se retrouvent sur un réseau partagé, déclaré external: true côté appli (section 15). Coupure mesurée après la bascule : 34 secondes. Même serveur, zéro euro de plus.

Le prix : plus de depends_on entre l'appli et sa base, puisqu'elles ne sont plus dans le même fichier. Au redémarrage du serveur, tout remonte en même temps, sans ordre. Alors l'appli attend elle-même. Un petit script, lancé en tout premier dans son conteneur, ne rend la main que quand ses dépendances répondent :

Pour le service lent, un port qui répond ne suffit pas : il écoute bien avant de savoir servir. Le script lui pose donc une vraie question, celle que l'appli lui posera en premier. Et au bout de dix minutes sans réponse, il abandonne avec une erreur : le conteneur s'arrête, et restart: always le relance pour un nouvel essai.

Je l'ai testé en redémarrant le serveur. L'appli est arrivée avant le service lent, le script a attendu 57 secondes, puis tout a démarré seul.

Toutes ces commandes se lancent dans le dossier du compose.yaml, et parlent des services par leur nom (web, db), pas des conteneurs.

J'ai vérifié la différence : après un down, le volume de la base est toujours là, le prochain up le rebranchera. Après un down -v, le volume a disparu, et les données avec. En local, c'est pratique pour repartir de zéro. Sur un serveur, c'est ta base de prod.

docker compose config est la commande sous-cotée de la liste : elle affiche le fichier tel que Compose le comprend, avec les variables remplacées. Une variable vide, une indentation cassée : tu le vois avant de lancer quoi que ce soit.

Umami compte les visites d'un site : combien de monde, d'où ils viennent, quelles pages ils lisent. C'est un logiciel libre (licence MIT), que tu installes sur ta propre machine : tes chiffres sont dans ta base, pas chez quelqu'un d'autre. Moi, j'utilise Umami et PostHog. Umami, je l'héberge moi-même, sur un de mes serveurs.

Je l'ai pris pour cette page parce que son dépôt GitHub contient un fichier Compose officiel, court, qui se sert d'à peu près tout ce que tu viens d'apprendre. Il n'y a rien à fabriquer : le fichier suffit.

Ce que ça donne, une fois lancé :

• Deux images téléchargées. Dans docker images, celle d'Umami pèse 1,05 Go, celle de Postgres 286 Mo.
• Au premier démarrage, Compose attend que la base se déclare prête, puis Umami crée ses tables (26 migrations dans les logs) et démarre.
• docker compose down, puis up : le site que j'avais déclaré dans Umami est toujours là. down -v, puis up : plus rien, retour au compte admin / umami. Le volume, comme en section 17.

Si Compose te répond address already in use, c'est que le port 3000 est déjà pris sur ta machine (c'est le port par défaut de beaucoup d'outils de dev). Ça m'est arrivé pendant ce test. Libère le port, ou change le chiffre de gauche dans ports: (section 6).

Voilà le fichier que tu viens de lancer. Je n'ai touché à aucune ligne de YAML : j'ai seulement ajouté les commentaires. D'abord ce qu'il construit, ensuite le fichier.

Ce que chaque bloc reprend de la page :

Trois choses que la démo de la partie 4 n'avait pas :

• Pas de build:. L'image est construite par l'équipe d'Umami et publiée sur un registre, comme dans mon histoire de la section 12. Leur Dockerfile est dans le dépôt, et tu sais le lire : plusieurs étages, un utilisateur qui n'est pas root, un CMD entre crochets. J'ai vérifié dans le conteneur : whoami répond nextjs, pas root.
• Un healthcheck sur l'appli aussi, pas seulement sur la base. docker compose ps affiche healthy pour les deux.
• init: true, le réglage de la section 13. Le premier process du conteneur est bien le mini-process de Docker.

Et deux choses que cette page t'a appris à ne pas laisser passer : le tag latest, et des mots de passe écrits en dur. Pour essayer chez toi, ça ne gêne personne. Pour le mettre en ligne, si.

Umami démarre très bien avec ses valeurs d'exemple. Rien ne t'oblige à les changer, et c'est bien le problème. Avant de le poser sur un serveur :

1. Le tag. latest bouge sans prévenir (section 3). Aujourd'hui, latest et 3.4.0 sont la même image. Écris 3.4.0 : c'est toi qui choisis le jour de la mise à jour.
2. Les secrets. APP_SECRET protège les jetons de connexion : la doc d'Umami demande une valeur unique par installation. Pareil pour la clé de la double authentification.
3. Les mots de passe. Celui de la base (umami, écrit deux fois dans le fichier) part dans le .env. Celui du compte admin se change dans l'interface, dès la première connexion.
4. Le port. "3000:3000" ouvre l'appli à tout internet, en HTTP, et sans passer par ton pare-feu (section 6). Avec 127.0.0.1 devant, elle n'est joignable que depuis le serveur lui-même. Devant, tu mets un reverse proxy (Caddy, nginx, ou celui de ton outil de déploiement) : c'est lui qui reçoit le trafic en HTTPS et le passe à l'appli.

Je l'ai lancé tel quel : l'appli répond sur localhost:3000, et plus du tout depuis l'adresse de mon Mac sur le réseau.

Le piège, si tu as déjà lancé le fichier d'origine. Postgres écrit son mot de passe dans le volume au tout premier démarrage. Changer la variable ensuite ne change rien : la base garde l'ancien. J'ai essayé. La base s'affiche healthy, et Umami redémarre en boucle sur password authentication failed. Sur une installation de test, docker compose down -v, et tu repars de zéro. Sur une base qui a déjà des données, le mot de passe se change dans Postgres, pas dans le fichier.

1. Dans Umami, ouvre Websites, puis Add website. Donne un nom, et le domaine de ton site.
2. Clique sur Edit en face de ce site. Sous Tracking code, Umami te donne une ligne de script, avec l'identifiant du site dedans.
3. Colle cette ligne dans le <head> de tes pages.

Je l'ai fait sur une page de test, ouverte dans Chrome : une visite, et Umami affiche 1 visiteur, 1 page vue. Il faut un vrai navigateur : c'est lui qui exécute le script, et Umami écarte les robots par défaut.

Regarde le dessin de la section 19 : ce n'est pas ton site qui envoie la visite, c'est le navigateur de ton visiteur. Tant qu'Umami tourne sur ton ordi, localhost:3000 ne veut rien dire pour lui : tu ne compteras que tes propres visites. Pour un vrai site, il te faut :

• Umami sur un serveur allumé en permanence, avec le fichier de la section 20. Pour choisir le serveur : les cinq types de serveurs, et les moins chers ;
• un nom de domaine qui pointe dessus, par exemple stats.ton-site.fr ;
• du HTTPS devant. Si ton site est en HTTPS, le navigateur refuse de charger un script en HTTP.

La ligne devient alors src="https://stats.ton-site.fr/script.js", et rien d'autre ne change. Dernier détail : certains bloqueurs de pub bloquent ce script. Ton compteur sera toujours un peu en dessous de la réalité.

Compose gère des conteneurs sur une machine. Kubernetes gère des conteneurs sur un groupe de machines : il décide où chaque conteneur tourne, en relance ailleurs quand une machine tombe, en ajoute quand la charge monte, et fait les mises à jour sans coupure. C'est puissant, et c'est un métier à part entière.

Une de mes applis en prod, sept services, tient sur un seul serveur et deux fichiers Compose. La plupart des projets perso, et beaucoup de projets pros, n'ont pas besoin de plus. Et tout ce que tu as appris ici se retrouve dans Kubernetes : les images, les tags, les variables d'environnement, les volumes, les healthchecks, les services qu'on appelle par leur nom. Apprends Docker et Compose à fond d'abord. Le jour où Kubernetes arrive dans ton équipe, tu n'auras que la couche du dessus à apprendre.