Docker + IA

Un accompagnement, pas une documentation

Ce livre n'est pas une documentation technique de plus. C'est une formation complète, pensée pour vous prendre par la main à l'endroit exact où vous êtes aujourd'hui — même si vous n'avez jamais tapé une seule commande Docker — et vous conduire, étape après étape, jusqu'à concevoir seul des architectures d'applications modernes intégrant de l'intelligence artificielle.

La plupart des ressources sur Docker souffrent du même défaut : elles expliquent comment faire sans jamais expliquer pourquoi. On vous demande d'écrire un Dockerfile avant même d'avoir compris ce qu'est une image. On vous jette dans docker compose up sans que vous ayez saisi le problème que Compose résout. Résultat : vous copiez des commandes sans les comprendre, et le jour où quelque chose casse — et quelque chose casse toujours — vous êtes bloqué.

Ici, la démarche est inverse. Chaque concept suit une progression rigoureuse :

On comprend d'abord le problème réel. On voit le concept à travers une analogie et un schéma. On fait soi-même, en tapant les commandes. On modifie pour tester les limites. On résout les erreurs les plus fréquentes — parce qu'elles arriveront. Et enfin, on construit de vrais projets.

Le livre est traversé par deux grands axes. Le premier, le plus long, fait de vous un utilisateur professionnel de Docker. Le second vous apprend à mettre Docker au service de l'IA : connecter une application conteneurisée à une API de modèle de langage, comprendre et bâtir un système RAG, exécuter un modèle localement, exploiter un GPU. À la fin, ces deux axes se rejoignent dans un projet final ambitieux : un assistant documentaire intelligent, entièrement conteneurisé.

Comment utiliser ce livre

Ce livre se pratique autant qu'il se lit. Voici comment en tirer le maximum.

Lisez-le dans l'ordre (au moins la première fois)

La difficulté augmente volontairement et progressivement. Chaque chapitre suppose acquis ce qui précède. Si vous êtes déjà à l'aise avec les bases, vous pouvez survoler les premières parties — mais ne sautez jamais un concept que vous n'avez jamais pratiqué.

Gardez un terminal ouvert

Chaque commande présentée est faite pour être tapée, pas seulement lue. La mémoire des doigts vaut dix relectures. Résistez à la tentation du copier-coller sur les premières commandes.

Repérez les encadrés

Ils rythment la lecture et signalent l'essentiel. Voici la légende que vous retrouverez tout au long du livre :

Faites les exercices — et cherchez avant de regarder la correction

Chaque grande partie propose des exercices à trois niveaux : Débutant (application directe), Intermédiaire (combiner plusieurs concepts), Pro (problème ouvert). Les corrections sont masquées : cliquez pour les révéler, mais seulement après avoir vraiment essayé.

Quand ça ne marche pas

Vous croiserez régulièrement une rubrique « Si ça ne fonctionne pas » structurée en Symptôme → Cause probable → Vérification → Solution. Elle vaut de l'or : déboguer est une compétence à part entière, et ce livre vous l'enseigne autant que Docker lui-même.

Prérequis

La bonne nouvelle : ils sont volontairement légers. Ce livre part vraiment de zéro sur Docker.

Un mot sur les niveaux de lecture

Le livre est écrit pour trois profils, et vous progresserez naturellement de l'un à l'autre :

Sommaire détaillé

Voici l'intégralité du parcours. Il est conçu comme une montée en difficulté continue : chaque partie prépare la suivante, et les deux axes — Docker puis IA — convergent dans le projet final.

flowchart TD
  A([Débutant complet]) --> B[Bases & conteneurs]
  B --> C[Images & Dockerfile]
  C --> D[Vraies applications]
  D --> E[Réseaux · Volumes · Config]
  E --> F[Docker Compose]
  F --> G[Debugging · Optimisation · Sécurité]
  G --> H[Registry · CI/CD · Déploiement]
  H --> I[Docker + IA]
  I --> J[RAG & base vectorielle]
  J --> K[IA locale & GPU]
  K --> L[Projets de fin de formation]
  L --> M([Développeur d'applications IA Dockerisées])
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Front matter

• Couverture · Préface · Comment utiliser ce livre · Prérequis · Sommaire détaillé

Partie 0 — Introduction

• Chapitre 0 — Pourquoi Docker en 2026 ? Les problèmes du développement sans conteneurs, le fameux « ça marche sur ma machine », Docker dans les entreprises modernes, le Cloud, le CI/CD, les microservices et l'IA.

Partie 1 — Comprendre les fondamentaux

• Chapitre 1 — Le problème que Docker résout. Application, OS, dépendances, versions, environnement, configuration ; ce qui casse quand on déplace une application.
• Chapitre 2 — Comprendre les conteneurs. Conteneur, image, runtime, isolation, portabilité ; conteneur vs machine virtuelle, expliqué visuellement.

Partie 2 — Installation et premiers pas

• Chapitre 3 — Installer Docker. Docker Desktop vs Docker Engine, Windows/macOS/Linux, vérifier l'installation, docker run hello-world décortiqué.
• Chapitre 4 — Les premières commandes. run, ps, stop/start/restart, rm, images, rmi, logs, inspect, exec ; tableau récapitulatif. Mini-projet 1 : nginx + redis + postgres.

Partie 3 — Images Docker

• Chapitre 5 — Comprendre les images. Image, couche, repository, tag, registry, Docker Hub.
• Chapitre 6 — Créer sa première image. FROM, WORKDIR, COPY, RUN, EXPOSE, CMD, ENTRYPOINT, ENV, ligne par ligne.
• Chapitre 7 — Dockerfile professionnel. Ordre des instructions, cache, .dockerignore, images légères (Alpine, Debian slim, officielles), sécurité.

Partie 4 — Conteneuriser de vraies applications

• Chapitre 8 — Docker + Java (Spring Boot) + PostgreSQL.
• Chapitre 9 — Docker + Node.js. API, ports, environnement, dépendances, npm, logs.
• Chapitre 10 — Docker + Python (FastAPI).
• Chapitre 11 — Docker + frontend. Build, fichiers statiques, Nginx, multi-stage.

Partie 5 — Réseaux Docker

• Chapitre 12 — Comprendre les réseaux. Réseau bridge, communication entre conteneurs, hostname, ports ; pourquoi postgres:5432 et non localhost:5432.

Partie 6 — Stockage

• Chapitre 13 — Volumes Docker. Pourquoi les données disparaissent, volume vs bind mount, persistance, exemple PostgreSQL.

Partie 7 — Variables et configuration

• Chapitre 14 — Variables d'environnement. -e, fichier .env, configuration, credentials, secrets, dev/test/prod — et pourquoi jamais de mot de passe dans un Dockerfile.

Partie 8 — Docker Compose

• Chapitre 15 — Pourquoi Docker Compose ? Services, networks, volumes, ports, environment, depends_on, healthcheck.
• Chapitre 16 — Projet complet avec Compose. Frontend → Backend REST → PostgreSQL (+ Redis si pertinent).

Partie 9 — Debugging et problèmes réels

• Chapitre 17 — Déboguer Docker. Port déjà utilisé, conteneur qui s'arrête, mauvaise variable, connexion PostgreSQL impossible, hostname, image introuvable, permission denied, volume, réseau. La méthode « Diagnostic en 5 minutes ».

Partie 10 — Docker avancé

• Chapitre 18 — Multi-stage builds. Mauvaise vs bonne approche, bénéfices (taille, sécurité, performance).
• Chapitre 19 — Optimisation des images. Cache de couches, ordre, .dockerignore, images minimales, avant/après.
• Chapitre 20 — Sécurité Docker. Non-root, images officielles, mises à jour, secrets, surface d'attaque, scan, moindre privilège.

Partie 11 — Docker en équipe et en production

• Chapitre 21 — Docker Hub et Registry. login, tag, push, pull, registry privé.
• Chapitre 22 — Docker et CI/CD. Git → build → tests → push → deploy ; pipeline GitHub Actions.
• Chapitre 23 — Docker et déploiement. Serveur/VPS, registry, reverse proxy, HTTPS, variables, logs ; où Kubernetes s'insère (survol).

Partie 12 — Introduction à l'IA Axe IA

• Chapitre 24 — Pourquoi Docker + IA ? Dépendances lourdes, Python, modèles, versions, GPU, environnement reproductible.

Partie 13 — Première application IA conteneurisée

• Chapitre 25 — API IA avec Python + FastAPI + Docker.

Partie 14 — Intégration des API d'IA

• Chapitre 26 — Connecter une application Docker à une API d'IA. Clé API, variables d'environnement, sécurité, requêtes/réponses, gestion d'erreurs, coûts — sans dépendre d'un seul fournisseur.

Partie 15 — RAG et base vectorielle

• Chapitre 27 — Comprendre le RAG. Embeddings, base vectorielle, chunks, retrieval, contexte — sans mathématiques inutiles.
• Chapitre 28 — Projet RAG Dockerisé. « Chatbot documentaire » : frontend, backend, base vectorielle, modèle d'embedding, LLM.

Partie 16 — IA locale et modèles open source

• Chapitre 29 — Exécuter un modèle IA localement. Inference, CPU/GPU, mémoire, quantization ; Ollama et Docker Model Runner ; limites matérielles.

Partie 17 — Docker + GPU

• Chapitre 30 — Comprendre Docker et GPU. GPU, CUDA, NVIDIA Container Toolkit, accès GPU depuis un conteneur ; exemple GPU + alternative CPU.

Partie 18 — Projets de fin de formation

• Projet 1 Débutant — « Mon premier environnement Docker » : application + PostgreSQL, volume, réseau, variables.
• Projet 2 Intermédiaire — « Application Web complète » : Frontend + Backend + PostgreSQL + Redis avec Compose.
• Projet 3 Avancé — « API IA Dockerisée » : génération de texte, historique, erreurs, variables, logs.
• Projet 4 — PROJET FINAL — « AI Knowledge Assistant » : upload de documents, extraction, embeddings, recherche vectorielle, génération, interface web, backend, base de données, base vectorielle, Compose.

Partie 19 — Autonomie professionnelle

• Chapitre 31 — Démarrer un projet Docker de zéro. Checklist en 12 étapes.
• Chapitre 32 — Checklist Docker professionnelle. Développement, sécurité, performance, production, IA.

Partie 20 — Référence rapide

• Cheat sheets : Commandes essentielles, Dockerfile, Docker Compose, Debugging, Docker + IA.
• Glossaire : Container, Image, Dockerfile, Registry, Volume, Network, Compose, Layer, Build, Runtime, API, LLM, Embedding, RAG, Base vectorielle, Inference, GPU.
• Évaluation finale et projet d'autonomie sans solution.

Pourquoi Docker en 2026 ?

Le problème

Imaginez la scène, vécue par des millions de développeurs. Vous passez deux semaines à construire une application. Sur votre ordinateur, tout fonctionne parfaitement. Vous l'envoyez à un collègue, ou vous la déployez sur un serveur… et rien ne marche. Une bibliothèque manque. La version de Python n'est pas la bonne. Une variable de configuration est absente. Le message d'erreur ne ressemble à rien de ce que vous avez vu.

Vous répondez alors la phrase la plus célèbre — et la plus détestée — de l'informatique :

Le concept : votre application ne vit pas seule

Une application n'est jamais un simple fichier isolé. Pour fonctionner, elle a besoin d'un environnement entier autour d'elle :

• un langage et sa version précise (Python 3.12, Node 22, Java 21…) ;
• des dépendances — les bibliothèques externes qu'elle utilise, chacune dans une version compatible ;
• des outils système installés sur la machine ;
• une configuration : variables d'environnement, chemins, ports, adresses de bases de données ;
• un système d'exploitation qui gère tout cela.

Sur votre machine, cet environnement s'est construit petit à petit, souvent sans que vous en gardiez la trace. Le jour où l'application change de machine, tout cet échafaudage invisible disparaît — et l'application s'écroule.

Visualisation : l'analogie du conteneur maritime

Le nom « Docker » et sa fameuse baleine ne sont pas un hasard. Avant les conteneurs maritimes standardisés, charger un bateau était un cauchemar : chaque marchandise avait sa forme, son emballage, ses contraintes. L'invention du conteneur standard a tout changé : peu importe ce qu'il y a dedans (des bananes ou des voitures), la boîte a toujours la même taille, et n'importe quel port, camion ou grue dans le monde sait la manipuler.

Docker fait exactement cela pour le logiciel. Peu importe ce qu'il y a dans le conteneur — une API Java, un site Node.js, un modèle d'IA en Python — l'extérieur est standardisé. N'importe quelle machine équipée de Docker sait le faire tourner, à l'identique.

flowchart LR
  subgraph SANS [" Sans Docker"]
    A1[Application] -.dépend de.-> B1[Environnement<br/>de VOTRE machine]
    B1 -.absent ailleurs.-> C1(( Casse<br/>sur le serveur))
  end
  subgraph AVEC [" Avec Docker"]
    A2[Application] --- B2[Son environnement]
    A2 --- B2
    B2 --> D2[ Conteneur scellé]
    D2 --> E2((Tourne à l'identique<br/>partout))
  end
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;
  style SANS fill:#EDF2FB,stroke:#B7C6DE,color:#12213A;
  style AVEC fill:#EDF2FB,stroke:#B7C6DE,color:#12213A;

Pourquoi c'est devenu incontournable en 2026

Docker n'est pas une curiosité de développeur : c'est aujourd'hui un standard de l'industrie. Voici les cinq forces qui l'ont rendu indispensable — chacune deviendra un chapitre pratique plus loin.

Ce que Docker n'est pas (pour éviter les malentendus)

Deux clarifications utiles dès maintenant, que nous approfondirons :

• Docker n'est pas une machine virtuelle. Un conteneur est bien plus léger et démarre en une fraction de seconde. Nous verrons pourquoi au Chapitre 2.
• Docker ne remplace pas votre code. Il l'emballe. Votre application reste la vôtre ; Docker s'occupe de la rendre transportable et reproductible.

Exercices

Le problème que Docker résout

Le problème

Au chapitre précédent, nous avons dit qu'une application « ne vit pas seule ». Regardons cela de plus près, car c'est le problème que Docker attaque. Prenons une application web toute simple, écrite en Python. Que faut-il, réellement, pour la faire tourner ?

Le concept : les quatre couches d'une application qui tourne

Sur votre machine, votre application repose sur un empilement de couches. Chacune dépend de celle du dessous :

flowchart TD
  A[" Machine du développeur"] --> B[" Application<br/><span style='font-size:11px'>votre code</span>"]
  B --> C[" Dépendances<br/><span style='font-size:11px'>bibliothèques + versions</span>"]
  C --> D[" Runtime & outils système<br/><span style='font-size:11px'>Python 3.12, libs système…</span>"]
  D --> E[" Système d'exploitation<br/><span style='font-size:11px'>+ configuration, variables</span>"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Le point crucial : votre code ne représente que la couche du haut. Tout le reste — les versions des bibliothèques, le runtime du langage, les outils système, la configuration — s'est installé progressivement sur votre machine. Vous l'avez peut-être oublié, mais votre application en dépend à chaque exécution.

Visualisation : ce qui se passe quand on déplace l'application

Vous envoyez maintenant uniquement votre code (la couche du haut) à un collègue ou sur un serveur. Les couches du dessous, elles, restent sur votre machine. Sur la machine cible, elles sont différentes… ou absentes.

flowchart TB
  subgraph DEV [" Votre machine"]
    direction TB
    d1[Application] --> d2["Dépendances v2.1"] --> d3["Python 3.12"] --> d4[OS + config OK]
  end
  subgraph PROD [" Le serveur"]
    direction TB
    p1[Application] --> p2["Dépendances v1.4 "] --> p3["Python 3.9 "] --> p4[Config manquante ]
  end
  DEV -. "on ne déplace que le code" .-> PROD
  PROD --> X(( Ça casse))
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;
  style DEV fill:#EDF2FB,stroke:#B7C6DE,color:#12213A;
  style PROD fill:#EDF2FB,stroke:#B7C6DE,color:#12213A;

Les trois familles de problèmes

Tout ce qui casse lors d'un déplacement se range presque toujours dans l'une de ces trois catégories :

Un exemple parlant : deux projets, une seule machine

Voici un cas que tout développeur finit par rencontrer. Vous avez deux projets sur votre ordinateur :

• Projet A a besoin de la version 1 d'une bibliothèque.
• Projet B a besoin de la version 2 de la même bibliothèque.

Sur une machine « classique », vous ne pouvez installer qu'une seule version à la fois. Installer l'une casse l'autre. Vous voilà coincé. Avec Docker, chaque projet vit dans son propre conteneur, avec sa propre version — isolés, ils s'ignorent totalement et fonctionnent tous les deux. Cette idée d'isolation est si importante qu'elle occupe le chapitre suivant.

Exercices

Comprendre les conteneurs

Le concept : image, conteneur, runtime

Trois mots reviennent sans cesse. Fixons-les une bonne fois avec une analogie simple : la cuisine.

Isolation et portabilité : les deux super-pouvoirs

Deux propriétés font toute la valeur d'un conteneur :

• Isolation — chaque conteneur croit être seul au monde. Il a ses propres fichiers, ses propres bibliothèques, son propre réseau. Ce qui se passe dans un conteneur ne perturbe ni la machine hôte ni les autres conteneurs. C'est ce qui permet aux deux projets incompatibles du Chapitre 1 de cohabiter.
• Portabilité — comme l'image contient tout l'environnement, le conteneur se comporte de la même façon partout où Docker est installé : votre portable, celui d'un collègue, un serveur Cloud. Fini le « ça marche sur ma machine ».

Visualisation : la pile logicielle

Où se place Docker sur votre machine ? Empilons les couches, du bas (le matériel) vers le haut (votre application) :

flowchart TD
  A[" Application (dans le conteneur)"] --> B[" Container"]
  B --> C[" Docker Engine<br/><span style='font-size:11px'>le runtime</span>"]
  C --> D[" Système d'exploitation hôte"]
  D --> E[" Matériel (Hardware)"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Ce dernier point est fondamental et nous mène à la comparaison la plus importante du chapitre.

Conteneur vs Machine virtuelle

Beaucoup confondent les deux. La différence tient à une seule couche, mais elle change tout. Une machine virtuelle (VM) embarque un système d'exploitation invité complet par-dessus un hyperviseur. Un conteneur, lui, partage le système d'exploitation de l'hôte via le Docker Engine.

flowchart TB
  subgraph VM [" Machine virtuelle — lourde"]
    direction TB
    v1[Application] --> v2["Guest OS<br/>(OS complet, plusieurs Go)"]
    v2 --> v3[Hypervisor]
    v3 --> v4[Host OS]
    v4 --> v5[Hardware]
  end
  subgraph CT [" Conteneur — léger"]
    direction TB
    c1[Application] --> c2[Container]
    c2 --> c3[Docker Engine]
    c3 --> c4[Host OS]
    c4 --> c5[Hardware]
  end
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;
  style VM fill:#EDF2FB,stroke:#B7C6DE,color:#12213A;
  style CT fill:#EDF2FB,stroke:#B7C6DE,color:#12213A;

Exercices

# 1) Entrez dans un Ubuntu conteneurisé et créez-y un fichier
docker run -it --name test-ubuntu ubuntu bash
#   dans le conteneur :
cat /etc/os-release   # → Ubuntu
echo "coucou" > /tmp/preuve.txt
exit

# 2) Lancez un Alpine : autre distribution, autre monde
docker run -it --name test-alpine alpine sh
#   dans le conteneur :
cat /etc/os-release   # → Alpine
ls /tmp/preuve.txt    # → n'existe PAS ici
exit

Installer Docker

Le problème : deux « Docker » qui portent le même nom

Quand on débute, une confusion revient sans cesse : on parle de « Docker », mais il existe en réalité deux produits complémentaires. Clarifions-les tout de suite, cela vous évitera bien des malentendus.

Installation selon votre système

La procédure exacte évolue au fil des versions. Téléchargez toujours depuis la source officielle — docs.docker.com — et suivez la page correspondant à votre système. Voici la vue d'ensemble.

Windows

• Prérequis : Windows 10/11 64 bits avec WSL 2 (Windows Subsystem for Linux) activé. Docker Desktop propose de l'activer pendant l'installation.
• Téléchargez Docker Desktop for Windows, lancez l'installateur, redémarrez si demandé.
• Ouvrez Docker Desktop : une icône de baleine apparaît dans la barre des tâches quand le moteur est prêt.
• Vos commandes se tapent dans PowerShell, l'invite de commandes, ou un terminal WSL.

macOS

• Choisissez la bonne puce : Apple Silicon (M1/M2/M3/M4…) ou Intel. En cas de doute : menu Pomme → « À propos de ce Mac ».
• Téléchargez Docker Desktop for Mac, glissez l'application dans « Applications », lancez-la.
• Les commandes se tapent dans l'app Terminal.

Linux

Deux options selon votre besoin :

• Docker Desktop for Linux (Ubuntu, Debian, Fedora…) si vous voulez l'expérience graphique sur votre poste.
• Docker Engine si vous êtes sur un serveur ou préférez le tout-en-ligne-de-commande. C'est le choix classique en production.

# Récupère et exécute le script d'installation officiel de Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Permet d'utiliser docker sans « sudo » (voir l'encadré ci-dessous)
sudo usermod -aG docker $USER
# Puis fermez/rouvrez votre session pour que le changement prenne effet

Vérifier que tout fonctionne

Quel que soit votre système, deux commandes confirment que Docker est bien installé et démarré.

docker --version

Vous devriez voir une ligne du type Docker version 27.x.x, build ... (le numéro exact importe peu). Si la commande est « introuvable », Docker n'est pas installé ou pas dans le PATH.

docker info

docker info interroge le daemon (le moteur qui tourne en arrière-plan). S'il répond avec un long récapitulatif (nombre de conteneurs, d'images, version du noyau…), c'est que le moteur est bien démarré et vous parle. S'il affiche une erreur de connexion, le daemon n'est pas lancé — voir « Si ça ne fonctionne pas » plus bas.

Votre premier conteneur : hello-world

Le moment est venu. Cette commande est le « bonjour le monde » de Docker. Tapez-la :

docker run hello-world

Après quelques secondes, Docker affiche un message qui commence par Hello from Docker! et vous félicite. Anodin ? Pas du tout : en une commande, il vient de se passer une chaîne d'événements qui résume tout Docker.

Comprendre ce qui vient de se passer

Décomposons, car ce mécanisme se reproduira à chaque docker run de votre vie de développeur :

flowchart TD
  A["Vous tapez<br/>docker run hello-world"] --> B{"L'image 'hello-world'<br/>est-elle en local ?"}
  B -- Non --> C["Docker la télécharge<br/>depuis Docker Hub"]
  B -- Oui --> D
  C --> D["Docker crée un conteneur<br/>à partir de l'image"]
  D --> E["Le conteneur s'exécute :<br/>il affiche son message"]
  E --> F["Le programme se termine :<br/>le conteneur s'arrête"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

1. Docker cherche l'image en local. La première fois, vous ne l'avez pas.
2. Il la télécharge depuis Docker Hub, le registre public d'images (on y reviendra en Partie 3). Vous verrez une ligne Unable to find image... pulling from library/hello-world.
3. Il crée un conteneur à partir de cette image (l'image = le modèle ; le conteneur = l'instance, souvenez-vous du Chapitre 2).
4. Il exécute le programme contenu dans l'image : ici, un petit programme qui affiche un texte.
5. Le programme se termine, donc le conteneur s'arrête. Un conteneur vit tant que son programme principal tourne — retenez bien cela, c'est la cause n°1 de « mon conteneur s'arrête tout seul » que nous verrons au Chapitre 17.

Si ça ne fonctionne pas

Les premières commandes Docker

Le concept : le cycle de vie d'un conteneur

Presque toutes les commandes de ce chapitre agissent sur une même idée : le cycle de vie d'un conteneur. Un conteneur naît (créé et démarré), vit (en cours d'exécution), peut être mis en pause (arrêté), redémarré, puis détruit (supprimé). Gardez ce schéma en tête :

flowchart LR
  A["Image"] -->|docker run| B[" En cours<br/>d'exécution"]
  B -->|docker stop| C[" Arrêté"]
  C -->|docker start| B
  B -->|docker restart| B
  C -->|docker rm| D[" Supprimé"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Décortiquons une commande complète

Avant la liste, apprenons à lire une commande docker run. Prenons un serveur web nginx, que nous rendons accessible dans le navigateur :

docker run -d -p 8080:80 --name mon-nginx nginx

Chaque morceau a un rôle précis :

Ouvrez maintenant http://localhost:8080 dans votre navigateur : la page d'accueil de nginx s'affiche. Vous venez de faire tourner un vrai serveur web, isolé, en une ligne.

Les commandes essentielles, une par une

Pour chacune : son rôle, un exemple, et l'erreur classique associée.

docker ps — lister les conteneurs actifs

docker ps            # conteneurs EN COURS d'exécution
docker ps -a         # TOUS les conteneurs, y compris arrêtés

Affiche l'identifiant, l'image, le statut, les ports et le nom. Erreur classique : chercher un conteneur arrêté avec docker ps tout court et croire qu'il a disparu — il faut -a.

docker stop / start / restart

docker stop mon-nginx      # arrêt propre (laisse le temps de se fermer)
docker start mon-nginx     # redémarre un conteneur arrêté
docker restart mon-nginx   # stop puis start, en une commande

Erreur classique : stop ne supprime pas le conteneur, il le met seulement en pause. Il apparaît toujours dans docker ps -a et garde ses données.

docker rm / docker rmi — supprimer

docker rm mon-nginx        # supprime un conteneur (il doit être arrêté)
docker rm -f mon-nginx     # force la suppression même s'il tourne
docker rmi nginx           # supprime l'IMAGE nginx

docker images — lister les images locales

docker images     # toutes les images téléchargées ou construites

Affiche le dépôt (repository), le tag (version), l'identifiant et la taille. Utile pour repérer les grosses images à nettoyer.

docker logs — lire la sortie d'un conteneur

docker logs mon-nginx        # affiche les logs
docker logs -f mon-nginx     # suit les logs en temps réel (Ctrl+C pour quitter)

C'est votre outil de débogage n°1. Un conteneur qui « ne marche pas » a presque toujours écrit la raison dans ses logs. On y reviendra longuement au Chapitre 17.

docker inspect — tous les détails

docker inspect mon-nginx     # configuration complète, au format JSON

Renvoie tout : réseau, ports, volumes, variables d'environnement, adresse IP interne. Verbeux, mais précieux quand un détail cloche (nous l'utiliserons pour diagnostiquer les problèmes réseau).

docker exec — entrer dans un conteneur en marche

docker exec -it mon-nginx bash

Ceci ouvre un terminal à l'intérieur du conteneur, comme si vous vous y connectiez. -i = interactif, -t = terminal. Tapez exit pour ressortir. Indispensable pour explorer ce qui se passe dedans.

Tableau récapitulatif

Si ça ne fonctionne pas

Contexte & objectif

Trois briques que vous croiserez dans presque tous vos futurs projets : un serveur web (nginx), un cache mémoire (redis) et une base de données (postgres). L'objectif n'est pas encore de les relier, mais de prendre en main le cycle de vie et les commandes du chapitre.

Étapes

docker run -d -p 8080:80 --name web nginx

Vérifiez sur http://localhost:8080.

docker run -d --name cache redis

Pas de -p ici : nous n'exposons pas redis au navigateur, on le testera de l'intérieur.

docker run -d --name db -e POSTGRES_PASSWORD=secret postgres

PostgreSQL exige un mot de passe : on le fournit via la variable d'environnement -e POSTGRES_PASSWORD=secret (le -e sera au cœur du Chapitre 14).

Tests & résultat attendu

docker ps

Vous devez voir trois conteneurs actifs : web, cache, db. Testons maintenant redis de l'intérieur :

docker exec -it cache redis-cli
# puis, dans l'invite redis :
ping
# → réponse attendue : PONG
# tapez exit pour ressortir

Et jetons un œil aux logs de PostgreSQL, qui indiquent qu'il est prêt à accepter des connexions :

docker logs db # cherchez : « database system is ready to accept connections »

Nettoyage

docker stop web cache db
docker rm web cache db

Erreurs possibles

• Port 8080 déjà pris → changez pour -p 8081:80.
• db s'arrête aussitôt → vous avez probablement oublié -e POSTGRES_PASSWORD=... ; regardez docker logs db, le message est explicite.
• « redis-cli: not found » → vous n'êtes pas dans le conteneur ; refaites docker exec -it cache redis-cli.

Comprendre les images

Le concept : une image est un empilement de couches

Au Chapitre 2, nous avons dit qu'une image est un « modèle figé » contenant l'application et son environnement. Regardons de plus près : une image n'est pas un bloc monolithique, c'est un empilement de couches (layers) superposées, chacune en lecture seule.

Chaque couche représente une modification par rapport à la précédente : « partir d'un mini-Linux », puis « installer Python », puis « ajouter mon code », etc. L'image finale est la somme de toutes ces couches empilées.

flowchart TD
  L4["Couche 4 · Votre code applicatif"] --> L3["Couche 3 · Dépendances installées"]
  L3 --> L2["Couche 2 · Runtime (ex. Python)"]
  L2 --> L1["Couche 1 · Système de base (ex. Debian slim)"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Le vocabulaire : repository, tag, registry

Trois mots à ne plus jamais confondre. Prenons un nom d'image complet et disséquons-le :

docker.io / library / postgres : 16
   │            │          │        │
registry    (espace de    repo      tag

Quand vous écrivez simplement postgres, Docker complète pour vous : cela signifie docker.io/library/postgres:latest. C'est pour cela que docker run nginx « connaît » nginx : il va le chercher sur Docker Hub.

Docker Hub, le registre public

Docker Hub est le registry public par défaut : une immense bibliothèque d'images prêtes à l'emploi. On y trouve des images officielles (maintenues en lien avec les éditeurs : python, node, postgres, nginx…) et des images publiées par la communauté.

Visualisation : le trajet d'une image

Voici la boucle complète que vous allez apprendre à parcourir dans les deux prochains chapitres, puis à publier vous-même en Partie 11.

flowchart LR
  A[" Dockerfile<br/>(la recette)"] -->|docker build| B[" Image<br/>(couches figées)"]
  B -->|docker push| C[" Registry<br/>(Docker Hub)"]
  C -->|docker pull| D[" Image<br/>en local"]
  D -->|docker run| E[" Conteneur<br/>(en exécution)"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Voir les couches en pratique

Deux commandes utiles dès maintenant. La première liste vos images locales, la seconde montre l'historique des couches d'une image :

docker images              # vos images locales, avec leur taille
docker history postgres:16 # les couches qui composent l'image, de haut en bas

Exercices

Créer sa première image

Le concept : le Dockerfile est une recette

Souvenez-vous du « README fragile » du Chapitre 1 : la liste de choses à installer, toujours incomplète. Le Dockerfile est sa version exécutable et reproductible. C'est un simple fichier texte qui décrit, étape par étape, comment construire votre image — et Docker suit la recette à la lettre, à l'identique, à chaque fois.

Chaque instruction du Dockerfile crée en général une nouvelle couche (rappelez-vous le Chapitre 5). Écrire un Dockerfile, c'est donc décrire l'empilement de couches de votre image.

Notre première image, extrêmement simple

Commençons par le strict minimum : une petite application Python qui affiche un message. Créez un dossier et deux fichiers.

print("Bonjour depuis mon premier conteneur Docker ! ")

FROM python:3.12-slim
WORKDIR /app
COPY app.py .
CMD ["python", "app.py"]

Comprendre chaque ligne

Construire et lancer

docker build -t mon-app .

Décryptons : docker build construit une image ; -t mon-app lui donne un nom (tag) ; le . final est le contexte de build — le dossier où Docker cherche le Dockerfile et les fichiers à copier. Ce point est facile à oublier !

docker run mon-app
# → Bonjour depuis mon premier conteneur Docker ! 

Félicitations : vous n'êtes plus seulement utilisateur d'images, vous en fabriquez. C'est un cap majeur.

Les instructions qu'il vous reste à connaître

Notre exemple minimal n'utilisait pas tout. Voici les instructions restantes, avec leur usage typique.

RUN — exécuter une commande pendant la construction

RUN lance une commande au moment du build et fige son résultat dans une couche. C'est ainsi qu'on installe des dépendances :

RUN pip install requests

ENV — définir une variable d'environnement

ENV APP_ENV=production

La variable est disponible pendant le build et dans le conteneur au démarrage. Utile pour la configuration — un sujet entier au Chapitre 14 (où l'on verra pourquoi on n'y met jamais de mot de passe).

EXPOSE — documenter le port utilisé

EXPOSE 8000

ENTRYPOINT vs CMD

Les deux définissent ce qui se lance au démarrage, mais avec une nuance :

• CMD donne une commande par défaut, facilement remplaçable : docker run mon-app autre-commande écrase le CMD.
• ENTRYPOINT fixe le programme principal, toujours exécuté ; ce qu'on passe au run devient ses arguments.

On les combine souvent : ENTRYPOINT définit l'outil, CMD ses arguments par défaut.

ENTRYPOINT ["python", "app.py"]
CMD ["--port", "8000"]

Si ça ne fonctionne pas

Exercices

FROM python:3.12-slim
WORKDIR /app
RUN pip install requests
COPY app.py .
CMD ["python", "app.py"]

Dockerfile professionnel

Le problème : un build lent et une image obèse

Au chapitre précédent, on a fait « marcher » une image. Ça ne suffit pas en contexte professionnel : on veut des builds rapides et des images légères et sûres. Deux leviers principaux : l'ordre des instructions (pour le cache) et le choix de l'image de base.

Le cache de couches : le comprendre pour l'exploiter

Quand Docker reconstruit une image, il parcourt le Dockerfile de haut en bas. Pour chaque instruction, il se demande : « rien n'a changé ici depuis la dernière fois ? » Si oui, il réutilise la couche en cache au lieu de la refaire. Mais dès qu'une instruction change, toutes les couches suivantes sont invalidées et refaites.

Mauvaise approche

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
CMD ["python", "app.py"]

Ici, COPY . . copie tout le projet avant l'installation. Résultat : à la moindre modification d'une ligne de code, Docker invalide la copie et refait pip install en entier — même si les dépendances n'ont pas bougé. Chaque build réinstalle tout. Lent.

Bonne approche

FROM python:3.12-slim
WORKDIR /app

# 1) On copie SEULEMENT le fichier de dépendances…
COPY requirements.txt .
# 2) …et on installe. Cette couche est mise en cache.
RUN pip install --no-cache-dir -r requirements.txt

# 3) Le code, qui change souvent, vient EN DERNIER.
COPY . .
CMD ["python", "app.py"]

Maintenant, tant que requirements.txt ne change pas, Docker réutilise la couche d'installation en cache et ne refait que la copie du code. Les builds passent de plusieurs minutes à quelques secondes.

flowchart TD
  A["Modification d'une ligne de code"] --> B{"Où est copié le code<br/>dans le Dockerfile ?"}
  B -->|"COPY . . AVANT le RUN"| C[" pip install refait<br/>à chaque build"]
  B -->|"COPY . . APRÈS le RUN"| D[" pip install réutilisé<br/>depuis le cache"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Le fichier .dockerignore

Le COPY . . copie tout le dossier dans l'image — y compris des fichiers inutiles, lourds, voire sensibles. Le fichier .dockerignore (à placer à la racine, comme un .gitignore) liste ce qu'il faut exclure.

# Dépendances déjà réinstallées dans l'image
node_modules
__pycache__
# Historique et fichiers de dev
.git
.gitignore
# Secrets — ne JAMAIS les embarquer dans une image
.env
*.key
# Divers
*.log
Dockerfile
README.md

Choisir son image de base : officielle, slim, alpine

La ligne FROM décide à elle seule d'une bonne partie de la taille et de la sécurité de votre image. Trois grandes familles :

Première bonne pratique de sécurité : ne pas tourner en root

Par défaut, un conteneur s'exécute en tant que root (super-utilisateur). Si une faille de l'application est exploitée, l'attaquant hérite de ces droits élevés. La parade : créer un utilisateur sans privilèges et basculer dessus avec USER.

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

# Créer un utilisateur non-root et lui donner la main
RUN useradd --create-home appuser
USER appuser

CMD ["python", "app.py"]

Récapitulatif : l'anatomie d'un Dockerfile pro

FROM python:3.12-slim          # base légère et fixée
WORKDIR /app                    # dossier de travail
COPY requirements.txt .         # dépendances d'abord (cache)
RUN pip install --no-cache-dir -r requirements.txt
COPY . .                        # code ensuite (change souvent)
RUN useradd --create-home appuser
USER appuser                    # non-root
EXPOSE 8000                     # documentation du port
CMD ["python", "app.py"]     # commande de démarrage

Exercices

FROM node:22-slim
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "server.js"]

FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install
COPY . .
CMD ["node", "server.js"]

node_modules   # réinstallé par npm install dans l'image
.env           # secrets : jamais dans une image
.git           # historique inutile et lourd
*.log          # logs de dev sans valeur

Docker + Java (Spring Boot) + PostgreSQL

Le contexte

Notre application est une petite API REST de gestion de tâches, construite avec Spring Boot, qui stocke ses données dans PostgreSQL. Peu importe que vous maîtrisiez Spring : ce qui nous intéresse, c'est la conteneurisation. L'architecture visée :

flowchart LR
  U["Client / navigateur"] -->|HTTP 8080| A[" Conteneur<br/>Spring Boot (API)"]
  A -->|JDBC 5432| D[" Conteneur<br/>PostgreSQL"]
  D --> V[" Volume<br/>(données persistantes)"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Le projet

Une application Spring Boot se compile en un unique fichier .jar exécutable. On suppose que vous l'avez généré avec le wrapper Maven fourni par Spring :

./mvnw clean package -DskipTests
# produit par exemple : target/tasks-api-0.0.1-SNAPSHOT.jar

Le point clé côté Spring : la configuration de la base doit être lisible depuis l'environnement, pas codée en dur. Dans application.properties, on utilise des variables :

spring.datasource.url=${SPRING_DATASOURCE_URL}
spring.datasource.username=${SPRING_DATASOURCE_USERNAME}
spring.datasource.password=${SPRING_DATASOURCE_PASSWORD}
spring.jpa.hibernate.ddl-auto=update

Le Dockerfile

Notre .jar est déjà construit : l'image n'a plus qu'à fournir un Java d'exécution (JRE) et lancer le jar.

# Image officielle avec juste le nécessaire pour EXÉCUTER du Java 21
FROM eclipse-temurin:21-jre
WORKDIR /app

# On copie le jar construit et on le renomme app.jar
COPY target/*.jar app.jar

# Utilisateur non-root (bonne pratique du Chapitre 7)
RUN useradd --create-home appuser
USER appuser

EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

docker build -t tasks-api .

Faire communiquer l'API et PostgreSQL

Deux conteneurs qui doivent se parler ont besoin d'être sur le même réseau Docker. Les réseaux ont leur chapitre dédié (Chapitre 12) ; pour l'instant, retenez juste le geste : on crée un réseau, et on y attache les deux conteneurs.

docker network create tasks-net

docker run -d --name db --network tasks-net \
  -e POSTGRES_DB=tasks \
  -e POSTGRES_USER=tasks \
  -e POSTGRES_PASSWORD=secret \
  postgres:16

docker run -d --name api --network tasks-net -p 8080:8080 \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/tasks \
  -e SPRING_DATASOURCE_USERNAME=tasks \
  -e SPRING_DATASOURCE_PASSWORD=secret \
  tasks-api

Vérifier

docker logs -f api   # attendez « Started ...Application » et « HikariPool ... »
# puis testez l'API, par ex. :
curl http://localhost:8080/tasks

Si ça ne fonctionne pas

Docker + Node.js

Le contexte

Une mini-API qui répond en JSON. Deux fichiers suffisent. On applique directement les bonnes pratiques du Chapitre 7.

{
  "name": "node-api",
  "version": "1.0.0",
  "main": "server.js",
  "scripts": { "start": "node server.js" },
  "dependencies": { "express": "^4.19.2" }
}

const express = require("express");
const app = express();

// Le port vient de l'environnement, avec une valeur par défaut
const PORT = process.env.PORT || 3000;

app.get("/", (req, res) => {
  res.json({ message: "Bonjour depuis Node.js dans Docker " });
});

app.listen(PORT, () => {
  console.log(`API à l'écoute sur le port ${PORT}`);
});

Le Dockerfile

FROM node:22-slim
WORKDIR /app

# 1) Dépendances d'abord (cache) — on copie les manifestes seuls
COPY package.json package-lock.json* ./
RUN npm install --omit=dev

# 2) Puis le code applicatif
COPY . .

ENV PORT=3000
EXPOSE 3000
CMD ["node", "server.js"]

node_modules
npm-debug.log
.env
.git

Construire, lancer, observer

docker build -t node-api .
docker run -d -p 3000:3000 --name api node-api
curl http://localhost:3000
# → {"message":"Bonjour depuis Node.js dans Docker "}

docker logs -f api
# → API à l'écoute sur le port 3000

Si ça ne fonctionne pas

Docker + Python (FastAPI)

Le contexte

FastAPI est aujourd'hui l'un des frameworks web Python les plus utilisés — et, bonne nouvelle, c'est exactement celui qui nous servira pour les API d'IA (Partie 13). Le patron de ce chapitre vous resservira directement.

fastapi==0.115.0
uvicorn[standard]==0.30.6

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def racine():
    return {"message": "Bonjour depuis FastAPI dans Docker "}

@app.get("/sante")
def sante():
    return {"status": "ok"}

Le Dockerfile

FROM python:3.12-slim
WORKDIR /app

# Dépendances d'abord (cache)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Puis le code
COPY ./app ./app

EXPOSE 8000
# --host 0.0.0.0 est INDISPENSABLE dans un conteneur (voir encadré)
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Construire, lancer, tester

docker build -t python-api .
docker run -d -p 8000:8000 --name api python-api

curl http://localhost:8000
# → {"message":"Bonjour depuis FastAPI dans Docker "}
curl http://localhost:8000/sante
# → {"status":"ok"}

Si ça ne fonctionne pas

Docker + frontend

Le problème : un frontend, ce sont deux moments très différents

Une application frontend moderne (React, Vue, Angular, Svelte…) vit en deux temps :

• La construction (build). Sur du code source, on lance un outil (Node.js + un bundler) qui produit des fichiers statiques optimisés : du HTML, du CSS et du JavaScript. Ce moment a besoin de Node et de toutes les dépendances de développement.
• Le service (runtime). Une fois construits, ces fichiers statiques n'ont plus besoin de Node : un simple serveur web comme Nginx suffit à les livrer au navigateur.

flowchart LR
  A[" Code source<br/>(React/Vue…)"] -->|npm run build| B[" Fichiers statiques<br/>HTML · CSS · JS"]
  B --> C[" Nginx<br/>sert les fichiers"]
  C --> D[" Conteneur léger"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

La solution : le multi-stage build

Un Dockerfile peut contenir plusieurs étapes (FROM successifs). L'idée géniale : on construit dans une première étape riche (avec Node), puis on ne copie que le résultat dans une seconde étape minimale (Nginx). Tout l'outillage de la première étape est jeté.

# ---------- ÉTAPE 1 : build ----------
FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm install
COPY . .
RUN npm run build          # produit /app/dist (fichiers statiques)

# ---------- ÉTAPE 2 : runtime ----------
FROM nginx:alpine
# On copie UNIQUEMENT les fichiers construits depuis l'étape « build »
COPY --from=build /app/dist /usr/share/nginx/html
# Configuration Nginx adaptée aux applications monopage (SPA)
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

server {
  listen 80;
  location / {
    root /usr/share/nginx/html;
    index index.html;
    # Renvoie index.html pour toute route inconnue (routing côté client)
    try_files $uri $uri/ /index.html;
  }
}

Construire et servir

docker build -t frontend .
docker run -d -p 8080:80 --name web frontend
# Ouvrez http://localhost:8080 : votre application s'affiche,
# servie par un conteneur qui ne contient même pas Node.

Si ça ne fonctionne pas

Comprendre les réseaux

Le problème

Un conteneur est isolé (Chapitre 2) : par défaut, il ne voit pas les autres. Or une application réelle est faite de plusieurs services qui doivent se parler : un backend interroge une base, un frontend appelle le backend. Comment percer l'isolation, juste ce qu'il faut, entre les bons conteneurs ?

Le concept : un réseau Docker est un « couloir privé »

Un réseau Docker relie des conteneurs entre eux. Deux conteneurs sur le même réseau peuvent communiquer ; deux conteneurs sur des réseaux différents s'ignorent. C'est comme un couloir privé : seuls ceux qui y ont une porte peuvent se rendre visite.

Docker fournit un service génial sur ces réseaux : le DNS interne. Chaque conteneur y est joignable par son nom. Pas besoin de connaître son adresse IP (qui change à chaque redémarrage) : on l'appelle par son nom de conteneur, point.

flowchart TB
  subgraph NET [" Réseau Docker « app-net »"]
    direction LR
    F["Frontend"] -->|"appelle backend:8000"| B["Backend"]
    B -->|"appelle postgres:5432"| P["PostgreSQL"]
  end
  U["Navigateur"] -->|"localhost:8080 (port publié)"| F
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;
  style NET fill:#EDF2FB,stroke:#B7C6DE,color:#12213A;

Créer et utiliser un réseau

docker network create app-net          # créer un réseau
docker run -d --name db --network app-net postgres:16
docker run -d --name api --network app-net mon-api
docker network inspect app-net         # voir qui est connecté

Une fois db et api sur app-net, l'API atteint la base à l'adresse db:5432. Le nom db est résolu automatiquement par le DNS interne de Docker.

Le cœur du chapitre : postgres:5432 vs localhost:5432

C'est la confusion à éliminer. Le mot localhost signifie « moi-même ». Le problème : à l'intérieur d'un conteneur, « moi-même » désigne ce conteneur précis, pas votre machine ni les autres conteneurs.

Port interne vs port publié

Deux notions distinctes qu'on confond souvent :

• Port interne : le port sur lequel un service écoute dans le réseau Docker. Les autres conteneurs l'utilisent (ex. db:5432). Aucun -p n'est nécessaire pour cette communication interne.
• Port publié (-p hôte:conteneur) : uniquement pour exposer un service à votre machine (le navigateur). Sans -p, le service reste joignable par les autres conteneurs mais invisible depuis l'hôte.

Si ça ne fonctionne pas

Volumes Docker

Le problème : un conteneur est éphémère

Imaginez : vous lancez PostgreSQL, créez des tables, insérez des données précieuses. Puis vous supprimez le conteneur (docker rm) pour le recréer avec une nouvelle option. Vous relancez… et tout a disparu. Base vide. Panique.

Ce n'est pas un bug, c'est le fonctionnement normal. Le système de fichiers d'un conteneur est éphémère : il naît et meurt avec le conteneur. Tout ce qui y est écrit est perdu à sa suppression. Parfait pour une application sans état — catastrophique pour une base de données.

Le concept : le volume, un coffre-fort hors du conteneur

Un volume est un espace de stockage géré par Docker, qui vit en dehors du cycle de vie des conteneurs. On le « branche » sur un dossier du conteneur : tout ce que le conteneur écrit dans ce dossier va en réalité dans le volume, qui survit à la suppression du conteneur.

flowchart TD
  C[" Conteneur PostgreSQL<br/>écrit dans /var/lib/postgresql/data"] --> V[" Volume Docker<br/>pgdata"]
  V --> H[" Stockage de la machine hôte<br/>(géré par Docker)"]
  X[" On supprime le conteneur"] -.->|"les données restent"| V
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Mise en pratique avec PostgreSQL

PostgreSQL range ses données dans /var/lib/postgresql/data. On y branche un volume nommé pgdata :

docker run -d --name db \
  -e POSTGRES_PASSWORD=secret \
  -v pgdata:/var/lib/postgresql/data \
  postgres:16

Le format de -v est nom_du_volume:chemin_dans_le_conteneur. Docker crée le volume pgdata automatiquement s'il n'existe pas. Testez la persistance :

# 1) créez des données (via psql, une app…), puis :
docker rm -f db                 # on DÉTRUIT le conteneur

# 2) on le recrée, branché sur le MÊME volume
docker run -d --name db \
  -e POSTGRES_PASSWORD=secret \
  -v pgdata:/var/lib/postgresql/data \
  postgres:16
# → vos données sont toujours là. 

docker volume ls              # lister les volumes
docker volume inspect pgdata  # détails d'un volume
docker volume rm pgdata       # supprimer (attention : efface les données !)

Volume nommé vs bind mount

Il existe deux façons de persister des données. À ne pas confondre :

Si ça ne fonctionne pas

Variables d'environnement, configuration & secrets

Le principe : la config vient de l'extérieur

Une bonne image est générique. Ce qui la spécialise pour un environnement donné — l'URL de la base, une clé d'API, un niveau de log — lui est fourni au démarrage, via des variables d'environnement. Ainsi la même image passe de votre poste à la production sans modification.

Trois façons de passer des variables

1) Une par une avec -e

docker run -e APP_ENV=production -e LOG_LEVEL=info mon-app

2) En lot avec un fichier .env

Dès qu'il y a plusieurs variables, on les regroupe dans un fichier .env :

APP_ENV=production
LOG_LEVEL=info
DATABASE_URL=postgresql://tasks:secret@db:5432/tasks
API_KEY=sk-remplacez-moi

docker run --env-file .env mon-app

3) Avec Docker Compose (aperçu)

C'est l'approche que vous utiliserez le plus. On y arrive dès la Partie 8 :

services:
  api:
    image: mon-app
    environment:
      APP_ENV: production
    env_file:
      - .env

Configuration, credentials, secrets : ne pas tout mélanger

#  CATASTROPHIQUE
ENV DATABASE_PASSWORD=SuperSecret123

Une image, trois environnements

La même image mon-app, spécialisée par ses variables :

Si ça ne fonctionne pas

Pourquoi Docker Compose ?

Le problème : trop de commandes à la main

Au Chapitre 8, faire tourner une API + une base demandait déjà : créer un réseau, lancer la base avec ses variables et son volume, lancer l'API avec ses variables et son port… Ajoutez un cache Redis et un frontend, et vous voilà à jongler avec six commandes longues, dans le bon ordre, à retaper à chaque fois. C'est fastidieux, source d'erreurs, et impossible à partager proprement avec un collègue.

flowchart LR
  Y[" docker-compose.yml<br/>(décrit toute l'app)"] -->|docker compose up| E[" frontend<br/> backend<br/> postgres<br/> redis"]
  E -.->|réseau, volumes, variables| E
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Anatomie d'un docker-compose.yml

C'est un fichier YAML (indentation à base d'espaces, jamais de tabulations). Commençons par un cas simple : une API et sa base.

services:                       # la liste de vos conteneurs
  api:                          # 1er service, nommé « api »
    build: .                    # construit l'image depuis le Dockerfile local
    ports:
      - "8000:8000"            # publie le port (hôte:conteneur)
    environment:
      DATABASE_URL: postgresql://tasks:secret@db:5432/tasks
    depends_on:
      - db                      # démarre après « db »

  db:                           # 2e service, nommé « db »
    image: postgres:16          # utilise une image existante
    environment:
      POSTGRES_DB: tasks
      POSTGRES_USER: tasks
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data   # persistance (Ch.13)

volumes:                        # déclaration des volumes nommés
  pgdata:

Les clés à connaître

depends_on et healthcheck : démarrer dans le bon ordre

Un piège classique : l'API démarre plus vite que PostgreSQL et tente de se connecter à une base pas encore prête. depends_on seul garantit l'ordre de démarrage, mais pas que la base soit prête à répondre. La solution complète combine un healthcheck sur la base et une condition sur le depends_on :

services:
  api:
    build: .
    depends_on:
      db:
        condition: service_healthy   # attend que db soit « healthy »

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5

Les commandes Compose essentielles

Si ça ne fonctionne pas

Projet complet avec Docker Compose

Architecture

flowchart TB
  U["Navigateur"] -->|localhost:8080| F[" frontend<br/>Nginx"]
  F -->|/api → | B[" backend<br/>FastAPI"]
  B -->|messages| P[" db<br/>PostgreSQL"]
  B -->|compteur de visites| R[" cache<br/>Redis"]
  P --> V[" volume pgdata"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Technologies & prérequis

FastAPI (backend), PostgreSQL, Redis, Nginx (frontend statique). Prérequis : Docker et Docker Compose installés (Partie 2). Aucun autre outil : tout tourne en conteneurs.

Structure du projet

Le backend

fastapi==0.115.0
uvicorn[standard]==0.30.6
psycopg[binary]==3.2.1
redis==5.0.8

import os
import psycopg
import redis
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel

app = FastAPI()
app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])

DATABASE_URL = os.environ["DATABASE_URL"]
redis_client = redis.from_url(os.environ["REDIS_URL"], decode_responses=True)

def init_db():
    with psycopg.connect(DATABASE_URL) as conn:
        conn.execute("CREATE TABLE IF NOT EXISTS messages (id SERIAL PRIMARY KEY, texte TEXT)")

@app.on_event("startup")
def startup():
    init_db()

class Message(BaseModel):
    texte: str

@app.get("/api/messages")
def lister():
    visites = redis_client.incr("visites")          # compteur dans Redis
    with psycopg.connect(DATABASE_URL) as conn:
        rows = conn.execute("SELECT texte FROM messages ORDER BY id DESC").fetchall()
    return {"visites": visites, "messages": [r[0] for r in rows]}

@app.post("/api/messages")
def ajouter(m: Message):
    with psycopg.connect(DATABASE_URL) as conn:
        conn.execute("INSERT INTO messages (texte) VALUES (%s)", (m.texte,))
    return {"status": "ok"}

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Le frontend

<!doctype html>
<html lang="fr">
<head><meta charset="utf-8"><title>Livre d'or</title></head>
<body>
  <h1>Livre d'or </h1>
  <input id="txt" placeholder="Votre message">
  <button onclick="envoyer()">Envoyer</button>
  <p id="visites"></p>
  <ul id="liste"></ul>
  <script>
    const API = "http://localhost:8000";   // le backend, publié sur 8000
    async function charger() {
      const r = await fetch(API + "/api/messages");
      const d = await r.json();
      visites.textContent = "Visites : " + d.visites;
      liste.innerHTML = d.messages.map(m => "<li>" + m + "</li>").join("");
    }
    async function envoyer() {
      await fetch(API + "/api/messages", {method:"POST",
        headers:{"Content-Type":"application/json"},
        body: JSON.stringify({texte: txt.value})});
      txt.value = ""; charger();
    }
    charger();
  </script>
</body></html>

FROM nginx:alpine
COPY index.html /usr/share/nginx/html/index.html
EXPOSE 80

La configuration

POSTGRES_DB=guestbook
POSTGRES_USER=guest
POSTGRES_PASSWORD=secret

Le fichier d'orchestration

services:
  frontend:
    build: ./frontend
    ports:
      - "8080:80"
    depends_on:
      - backend

  backend:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started

  db:
    image: postgres:16
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 5s
      timeout: 3s
      retries: 5

  cache:
    image: redis:7

volumes:
  pgdata:

Étapes & commandes

docker compose up --build      # construit et démarre les 4 services
# (ajoutez -d pour l'arrière-plan)

Tests & résultat attendu

• Ouvrez http://localhost:8080 : le Livre d'or s'affiche.
• Saisissez un message, cliquez « Envoyer » : il apparaît dans la liste, et le compteur de visites augmente à chaque chargement.
• Vérifiez la persistance : docker compose down (sans -v), puis docker compose up — vos messages sont toujours là (volume pgdata).

docker compose ps            # les 4 services et leur état
docker compose logs -f backend

Erreurs possibles

• Le backend démarre avant la base → grâce à condition: service_healthy, ça n'arrive pas ; si vous l'enlevez, vous verrez le « connection refused » du Chapitre 8.
• Le frontend n'atteint pas l'API → ici le navigateur appelle localhost:8000 (port publié), pas backend:8000 : le nom de service ne vaut qu'entre conteneurs, jamais depuis le navigateur.
• Port 8080 ou 8000 déjà pris → changez la partie gauche des ports.
• Erreur CORS dans la console du navigateur → assurée par le middleware CORS du backend.

Déboguer Docker

La bonne attitude

Face à une panne, le réflexe débutant est de tout relancer au hasard. Le réflexe pro est d'observer avant d'agir. Docker vous donne des instruments précis : utilisez-les dans l'ordre, et la cause se révèle presque toujours en quelques minutes.

La méthode « Diagnostic en 5 minutes »

Une procédure à suivre dans l'ordre, à chaque fois. Elle couvre l'immense majorité des cas.

flowchart TD
  S([" Quelque chose ne marche pas"]) --> A["1 · docker ps -a<br/>Le conteneur tourne-t-il ?"]
  A --> B["2 · docker logs <nom><br/>Que dit l'application ?"]
  B --> C["3 · docker inspect <nom><br/>Config, réseau, variables"]
  C --> D["4 · Vérifier les PORTS"]
  D --> E["5 · Vérifier le RÉSEAU"]
  E --> F["6 · Vérifier les VARIABLES"]
  F --> G["7 · Vérifier les VOLUMES"]
  G --> R([" Cause identifiée"])
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

1. docker ps -a — Le conteneur est-il « Up » ou « Exited » ? S'il est arrêté, l'étape 2 dira pourquoi.
2. docker logs <nom> — L'instrument n°1. L'application écrit presque toujours la cause de son crash ici.
3. docker inspect <nom> — La configuration réelle : réseaux, ports, variables, montages. Idéal pour repérer un écart avec ce que vous croyiez.
4. Ports — Le port publié correspond-il au port de l'application (Chapitre 4) ?
5. Réseau — Les conteneurs qui doivent se parler sont-ils sur le même réseau ? Utilisent-ils le bon nom (Chapitre 12) ?
6. Variables — Les variables attendues sont-elles bien passées, au bon nom (Chapitre 14) ?
7. Volumes — Le bon chemin est-il monté (Chapitre 13) ?

Catalogue des dix pannes les plus fréquentes

Trois commandes de diagnostic avancé

docker exec -it <nom> sh          # entrer dans le conteneur et explorer
docker inspect <nom> | grep -i ip  # trouver l'IP interne, le réseau
docker compose logs -f             # suivre TOUS les services d'un coup

Exercices

Multi-stage builds

Le problème : les outils de build n'ont rien à faire en production

Vous l'avez déjà entrevu au Chapitre 11. Pour construire une application, il faut souvent un lourd outillage : un JDK complet et Maven pour Java, Node et des centaines de node_modules pour le frontend. Mais pour exécuter le résultat, il ne faut qu'un JRE, ou qu'un serveur web. Garder l'outillage de build dans l'image finale, c'est trimballer une caisse à outils entière pour juste faire tourner l'objet fini.

flowchart LR
  subgraph BAD [" Une seule étape"]
    direction TB
    b1["JDK + Maven + code + sources + .jar"] --> b2["Image énorme<br/>(> 700 Mo)"]
  end
  subgraph GOOD [" Multi-stage"]
    direction TB
    g1["Étape build :<br/>JDK + Maven → .jar"] --> g2["Étape runtime :<br/>JRE + .jar seul"]
    g2 --> g3["Image légère<br/>(~200 Mo)"]
  end
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;
  style BAD fill:#EDF2FB,stroke:#B7C6DE,color:#12213A;
  style GOOD fill:#EDF2FB,stroke:#B7C6DE,color:#12213A;

Le principe : plusieurs FROM, une seule image finale

Un Dockerfile peut enchaîner plusieurs étapes, chacune démarrant par un FROM. On nomme les étapes avec AS, et on copie sélectivement d'une étape à l'autre avec COPY --from=. Seule la dernière étape constitue l'image finale ; tout le reste est jeté.

Exemple Java (Spring Boot) — mieux qu'au Chapitre 8

# ---------- Étape 1 : build ----------
FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /src
COPY pom.xml .
RUN mvn dependency:go-offline        # dépendances en cache
COPY src ./src
RUN mvn clean package -DskipTests    # produit /src/target/*.jar

# ---------- Étape 2 : runtime ----------
FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=build /src/target/*.jar app.jar
RUN useradd --create-home appuser
USER appuser
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

Exemple Node.js (frontend) — rappel

C'est exactement le patron du Chapitre 11 : étape node pour npm run build, puis étape nginx:alpine qui reçoit seulement le dossier de sortie via COPY --from=build.

Bénéfices, en résumé

Optimisation des images

Pourquoi optimiser ?

Une image légère se télécharge plus vite, démarre plus vite, coûte moins cher à stocker, se déploie plus souvent, et présente moins de failles. Ce n'est pas de la coquetterie : en production et en CI/CD, la taille des images a un impact réel sur la vitesse et la facture.

Les leviers, du plus efficace au plus fin

Avant / après : un cas concret

Avant

FROM python:3.12                 # image complète, lourde
WORKDIR /app
COPY . .                          # code copié avant les deps → casse le cache
RUN pip install -r requirements.txt
RUN apt-get update && apt-get install -y curl   # caches apt laissés dans la couche

Après

FROM python:3.12-slim            # base légère
WORKDIR /app

# Dépendances d'abord (cache), sans cache pip conservé
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Un seul RUN : install + nettoyage dans la MÊME couche
RUN apt-get update \
 && apt-get install -y --no-install-recommends curl \
 && rm -rf /var/lib/apt/lists/*

# Le code en dernier
COPY . .

Sécurité Docker

1. Ne pas tourner en root

Le réflexe déjà vu au Chapitre 7, et le plus important. Par défaut, un conteneur s'exécute en root ; une faille exploitée hérite alors de droits élevés. Créez un utilisateur dédié et basculez dessus :

RUN useradd --create-home appuser
USER appuser

2. Partir d'images de confiance

Une image, c'est du code exécuté sur vos machines. Préférez les images officielles ou d'éditeurs vérifiés, et fixez les versions (pas de latest) pour des builds reproductibles et audités. Une image obscure tirée au hasard peut contenir n'importe quoi.

3. Mettre à jour les dépendances

Une image « qui marche » vieillit : les vulnérabilités sont découvertes après coup. Reconstruisez régulièrement pour récupérer les correctifs de l'image de base et de vos dépendances. Une image figée pendant deux ans est une image à trous.

4. Ne jamais embarquer de secrets

On l'a martelé au Chapitre 14 : aucun mot de passe ni clé dans le Dockerfile ou l'image (révélés par docker history). Les secrets se fournissent au démarrage, et .env reste dans .gitignore et .dockerignore.

5. Réduire la surface d'attaque

Moins il y a de logiciels dans une image, moins il y a de failles possibles. C'est un bénéfice gratuit des chapitres précédents : image -slim/alpine (Ch.19) et multi-stage (Ch.18) réduisent mécaniquement la surface d'attaque. N'installez que le strict nécessaire.

6. Scanner ses images

Des outils analysent une image et listent ses vulnérabilités connues. Intégré à Docker, Docker Scout ; très répandu aussi, Trivy :

docker scout cves mon-app        # vulnérabilités connues (Docker Scout)
# ou avec Trivy :
trivy image mon-app

7. Le principe du moindre privilège

Le fil rouge de tout le chapitre : chaque composant ne reçoit que les droits dont il a strictement besoin. Utilisateur non-root, ports non publiés inutilement (Ch.12), pas de secrets superflus, image minimale. En cas de compromission, les dégâts restent contenus.

Récapitulatif : la mini-checklist sécurité

Docker Hub et Registry

Le concept : le registry, l'entrepôt d'images partagé

Jusqu'ici, vos images vivaient sur votre machine. Pour qu'un collègue ou un serveur les utilise, il faut les déposer dans un registry — un entrepôt d'images accessible à distance. Vous en connaissez déjà un : Docker Hub, d'où vous tirez postgres ou nginx. Vous pouvez y déposer les vôtres.

flowchart LR
  A["Votre machine<br/>image construite"] -->|docker push| R[" Registry<br/>(Docker Hub / privé)"]
  R -->|docker pull| B["Machine d'un collègue"]
  R -->|docker pull| C["Serveur de production"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Le cycle push / pull, en pratique

docker login                     # demande identifiant + mot de passe/token

# Format : <utilisateur>/<repository>:<tag>
docker tag mon-app moncompte/mon-app:1.0.0

docker push moncompte/mon-app:1.0.0

docker pull moncompte/mon-app:1.0.0
docker run moncompte/mon-app:1.0.0

Bien versionner ses tags

Un même repository contient plusieurs versions, distinguées par leur tag. Adoptez une convention claire :

Registry public vs privé

Docker Hub public convient au partage ouvert. Pour du code propriétaire, on utilise un registry privé : repositories privés sur Docker Hub, ou registry des fournisseurs Cloud (GitHub Container Registry, GitLab, AWS ECR, etc.). Le fonctionnement (login/tag/push/pull) est identique — seule l'adresse du registry change.

docker login registry.mon-entreprise.com
docker tag mon-app registry.mon-entreprise.com/equipe/mon-app:1.0.0
docker push registry.mon-entreprise.com/equipe/mon-app:1.0.0

Docker et CI/CD

Le concept : automatiser la chaîne du code à la production

CI/CD signifie Intégration Continue / Déploiement Continu. L'idée : dès que vous poussez du code, une chaîne automatique s'occupe de le construire, le tester, l'emballer en image et — si tout est vert — le déployer. Plus d'étapes manuelles oubliées, plus de « ça marchait sur ma machine ».

flowchart LR
  A["git push"] --> B["CI démarre"]
  B --> C[" docker build"]
  C --> D[" Tests"]
  D -->|verts| E[" push image<br/>vers le registry"]
  E --> F[" Déploiement"]
  D -->|rouges| X[" Arrêt<br/>rien n'est publié"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Un pipeline concret avec GitHub Actions

GitHub Actions exécute des workflows décrits dans des fichiers YAML placés dans .github/workflows/. Voici un pipeline qui construit et publie une image à chaque push sur main.

name: Build & Push Docker

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # 1) Récupérer le code
      - uses: actions/checkout@v4

      # 2) S'authentifier au registry (identifiants stockés en secrets)
      - name: Login Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USER }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      # 3) Construire et pousser l'image
      - name: Build & push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: moncompte/mon-app:latest,moncompte/mon-app:${{ github.sha }}

Ajouter une étape de tests

Le vrai intérêt du CI, c'est de bloquer une image qui casse les tests. On insère une étape avant la publication :

      - name: Lancer les tests dans le conteneur
        run: |
          docker build -t app-test .
          docker run --rm app-test pytest      # échoue → le job s'arrête

Si pytest renvoie une erreur, GitHub Actions arrête le job : l'image défectueuse n'est jamais publiée ni déployée. Exactement le comportement voulu.

Docker et déploiement

Le principe : la même image, sur un serveur

Bonne nouvelle : déployer, c'est faire tourner votre image ailleurs. Toute la reproductibilité que vous avez construite prend ici tout son sens. Le schéma le plus courant pour une application simple :

flowchart LR
  D[" Développeur"] -->|push| R[" Registry"]
  S[" Serveur / VPS"] -->|pull| R
  U[" Internet"] -->|HTTPS 443| P[" Reverse proxy<br/>(HTTPS, routage)"]
  P --> A[" Conteneurs<br/>(compose)"]
  A --> DB[" Base + volume"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Les étapes d'un déploiement simple

1. Un serveur — souvent un VPS (serveur virtuel loué), avec Docker Engine installé (Chapitre 3).
2. Récupérer l'image — docker pull depuis votre registry, ou copier le docker-compose.yml et laisser le serveur tirer les images.
3. Fournir la configuration — les variables et secrets via un .env présent sur le serveur (jamais dans l'image, Chapitre 14).
4. Lancer — docker compose up -d, exactement comme en local.
5. Exposer proprement — un reverse proxy devant, pour le HTTPS et le nom de domaine.

Le reverse proxy et le HTTPS

Vos conteneurs écoutent en HTTP sur des ports internes. Pour servir le public sur https://mon-site.com, on place devant un reverse proxy (Nginx, Traefik, Caddy…). Il s'occupe de :

• HTTPS : chiffrer les échanges, avec un certificat souvent obtenu et renouvelé automatiquement (Let's Encrypt) ;
• Routage : diriger mon-site.com vers le frontend, mon-site.com/api vers le backend ;
• Point d'entrée unique : un seul port public (443), les conteneurs restent privés derrière.

Variables et logs en production

• Variables/secrets : fournis par le serveur (fichier .env protégé, ou gestionnaire de secrets de la plateforme). La même image qu'en test, spécialisée par sa config.
• Logs : vos applications écrivent sur la sortie standard ; docker compose logs les consulte. En production, on les collecte souvent vers un système centralisé pour les conserver et les chercher.
• Redémarrage : ajoutez une politique restart: unless-stopped dans Compose pour qu'un conteneur qui plante redémarre tout seul.

services:
  api:
    image: moncompte/mon-app:1.4.2   # version précise, pas latest
    restart: unless-stopped
    env_file: .env

Où Kubernetes s'insère-t-il ?

Vous entendrez beaucoup parler de Kubernetes. Situons-le simplement, sans entrer dans le détail (ce n'est pas l'objet de ce livre). Docker Compose suffit largement pour une application sur un serveur. Mais quand il faut faire tourner de nombreux conteneurs sur plusieurs machines, avec mise à l'échelle automatique, auto-réparation et déploiements sans coupure, on utilise un orchestrateur : Kubernetes en est le standard.

Pourquoi Docker + IA ?

Le problème : l'IA, un cauchemar de reproductibilité

Si vous avez déjà tenté de faire tourner un projet d'IA trouvé en ligne, vous connaissez la scène : des dizaines de dépendances, des versions qui se contredisent, un modèle de plusieurs gigaoctets à télécharger, et une erreur cryptique liée au GPU. Les applications d'IA cumulent tous les problèmes d'environnement du Chapitre 1, en pire.

La réponse de Docker : figer l'environnement, une fois pour toutes

C'est exactement le problème que Docker résout, transposé à l'IA. En emballant l'application, ses dépendances précises, son runtime Python et (quand il le faut) l'accès au GPU dans une image, Docker rend l'environnement d'IA reproductible : le même comportement sur votre machine, celle d'un collègue, un serveur, ou en production.

flowchart TD
  A[" Application IA"] --> D[" Docker"]
  D --> DEP[" Dépendances figées<br/>(Python + bibliothèques)"]
  D --> MOD[" Modèle<br/>(API distante ou fichier local)"]
  D --> HW[" Matériel / GPU<br/>(accès contrôlé)"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Deux grandes façons d'utiliser un modèle d'IA

Tout au long de cet axe, vous rencontrerez deux approches — souvent combinées. Autant les nommer dès maintenant :

Exercices

FROM python:3.12-slim
RUN pip install --no-cache-dir numpy

docker build -t test-ia .
docker images test-ia   # notez la taille

API IA avec Python + FastAPI + Docker

L'architecture visée

Une bonne API d'IA sépare nettement deux responsabilités : la couche API (recevoir les requêtes, valider, répondre) et le service d'IA (la logique qui « pense »). Cette séparation vous permettra, au chapitre suivant, de brancher un vrai modèle sans toucher à l'API.

flowchart LR
  C["Client"] -->|HTTP| A["FastAPI<br/>(couche API)"]
  A --> S["Service d'IA<br/>(logique / modèle)"]
  S --> A
  A -.->|conteneurisé| D[" Docker"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

La structure du projet

Le service d'IA (pour l'instant, un substitut)

On isole la logique d'IA dans un module dédié. Aujourd'hui, il renvoie une réponse factice ; au Chapitre 26, on remplacera uniquement l'intérieur de cette fonction par un appel à un vrai modèle — sans rien changer d'autre.

# Le « cerveau » de l'application, isolé du reste.
# Au chapitre suivant, seul l'intérieur de generer() changera.

def generer(prompt: str) -> str:
    # TODO (Ch.26) : appeler un vrai modèle d'IA ici.
    # Substitut pédagogique pour l'instant :
    return f"Réponse simulée à : '{prompt}'"

from fastapi import FastAPI
from pydantic import BaseModel
from app.ai_service import generer

app = FastAPI(title="API IA")

class Requete(BaseModel):
    prompt: str

@app.get("/sante")
def sante():
    return {"status": "ok"}

@app.post("/generer")
def generer_texte(req: Requete):
    reponse = generer(req.prompt)
    return {"prompt": req.prompt, "reponse": reponse}

fastapi==0.115.0
uvicorn[standard]==0.30.6

Le Dockerfile

Identique au patron du Chapitre 10 — c'est tout l'intérêt d'avoir bien appris les bases :

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY ./app ./app
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Construire, lancer, tester

docker build -t ai-api .
docker run -d -p 8000:8000 --name ia ai-api

curl -X POST http://localhost:8000/generer \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Bonjour"}'
# → {"prompt":"Bonjour","reponse":"Réponse simulée à : 'Bonjour'"}

Si ça ne fonctionne pas

Connecter une application Docker à une API d'IA

Le principe d'une API de modèle

Un fournisseur d'IA expose un modèle de langage (LLM) derrière une API HTTP. Vous envoyez un message (le prompt), le service renvoie une réponse générée. Votre conteneur n'héberge pas le modèle : il l'appelle.

flowchart LR
  A["Votre application"] --> D[" Conteneur"]
  D -->|HTTPS + clé API| API[" API d'IA<br/>/v1/chat/completions"]
  API --> L[" LLM"]
  L --> API --> D --> A
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Le standard qui vous rend agnostique : l'API compatible OpenAI

En 2026, la grande majorité des fournisseurs d'IA — et même les runtimes locaux comme Ollama ou Docker Model Runner (Chapitre 29) — exposent le même format d'API, dit « compatible OpenAI » : un point d'entrée /v1/chat/completions. Conséquence formidable : un seul code peut parler à n'importe lequel d'entre eux, en changeant juste deux variables — l'adresse (base_url) et la clé.

Brancher le vrai modèle

On reprend le projet ai-api du Chapitre 25 et on ne modifie que ai_service.py. On ajoute le client au requirements.txt :

fastapi==0.115.0
uvicorn[standard]==0.30.6
openai==1.51.0          # client compatible avec toute API « OpenAI-compatible »

import os
from openai import OpenAI, APIError, APITimeoutError

# Tout vient de l'environnement : rien n'est codé en dur.
client = OpenAI(
    base_url=os.environ["AI_BASE_URL"],   # ex. l'URL du fournisseur ou du modèle local
    api_key=os.environ["AI_API_KEY"],     # la clé, JAMAIS dans le code
)
MODELE = os.environ.get("AI_MODEL", "gpt-4o-mini")

def generer(prompt: str) -> str:
    try:
        reponse = client.chat.completions.create(
            model=MODELE,
            messages=[{"role": "user", "content": prompt}],
            timeout=30,
        )
        return reponse.choices[0].message.content
    except APITimeoutError:
        return " Le modèle a mis trop de temps à répondre. Réessayez."
    except APIError as e:
        # On journalise l'erreur réelle, on renvoie un message propre.
        print(f"Erreur API IA : {e}")
        return " Le service d'IA est momentanément indisponible."

Passer la clé, sans jamais l'exposer

On fournit la configuration au démarrage, via un .env (Chapitre 14). Ce fichier reste dans .gitignore et .dockerignore.

AI_BASE_URL=https://api.mon-fournisseur.com/v1
AI_API_KEY=sk-votre-cle-secrete
AI_MODEL=gpt-4o-mini

docker run -d -p 8000:8000 --env-file .env --name ia ai-api

curl -X POST http://localhost:8000/generer \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Explique Docker en une phrase."}'

Requêtes, réponses, et le rôle des « messages »

Le format compatible OpenAI structure la conversation en messages ayant un rôle : system (les consignes de comportement), user (la demande), assistant (les réponses passées). Pour donner une personnalité ou des règles à votre IA :

messages=[
    {"role": "system", "content": "Tu es un assistant concis qui répond en français."},
    {"role": "user", "content": prompt},
]

La question des coûts

Une API d'IA distante est en général facturée à l'usage, selon la quantité de texte échangé (mesurée en tokens). Quelques réflexes :

• Choisir un modèle adapté : les plus petits suffisent souvent et coûtent bien moins cher.
• Limiter la longueur des réponses (paramètre max_tokens).
• Éviter d'envoyer un contexte inutilement long à chaque requête.
• Surveiller sa consommation, et poser des limites de dépenses côté fournisseur.

Si ça ne fonctionne pas

Comprendre le RAG

Le problème : un modèle ne connaît pas vos documents

Un LLM a été entraîné sur des textes généraux ; il ignore le contenu de votre entreprise, de vos notes, de votre documentation interne. Lui poser une question sur vos documents donne, au mieux, une réponse vague, au pire une invention. Comment lui faire répondre à partir de votre savoir ?

Visualisation : le trajet d'une question

flowchart TD
  Q[" Question de l'utilisateur"] --> R[" Recherche des passages pertinents<br/>dans vos documents"]
  R --> C[" Contexte<br/>(les meilleurs extraits)"]
  C --> P[" Question + Contexte<br/>assemblés dans un prompt"]
  P --> L[" LLM"]
  L --> A[" Réponse fondée sur VOS documents"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Le vocabulaire, expliqué simplement

Les embeddings : transformer du sens en nombres

Un embedding est une liste de nombres qui représente le sens d'un texte. L'idée clé, sans mathématiques : deux textes qui parlent de la même chose obtiennent des embeddings proches. « Comment réinitialiser mon mot de passe ? » et « procédure de récupération d'accès » seront proches, même sans mots communs. C'est ce qui permet une recherche par le sens, et non par mots-clés exacts.

Les chunks : découper pour mieux retrouver

On ne calcule pas un embedding sur un document entier de 50 pages : trop gros, trop imprécis. On le découpe en morceaux (chunks) de quelques paragraphes, et on calcule un embedding par chunk. Ainsi, la recherche retrouve le passage précis qui répond, pas tout le document.

La base vectorielle : ranger et retrouver par proximité

Une base vectorielle (vector database) stocke ces embeddings et sait répondre très vite à : « quels sont les chunks dont l'embedding est le plus proche de celui de la question ? ». C'est un moteur de recherche par similarité de sens. Exemples courants : Qdrant, Chroma, ou l'extension pgvector de PostgreSQL.

Le retrieval et le contexte

Le retrieval (la récupération), c'est l'étape de recherche : on transforme la question en embedding, on interroge la base vectorielle, on récupère les meilleurs chunks. Ces extraits forment le contexte que l'on ajoute au prompt envoyé au LLM.

Les deux temps du RAG

Un système RAG fonctionne en deux phases distinctes. Bien les séparer clarifie tout :

Quels composants devront tourner en conteneurs ?

Regardez la liste : une base vectorielle, un backend qui orchestre indexation et interrogation, un accès à un modèle d'embeddings et à un LLM (via API ou local), et un frontend. Autant de services à conteneuriser et orchestrer avec Docker Compose — exactement le projet du chapitre suivant.

Exercices

docker run -d -p 6333:6333 --name qdrant qdrant/qdrant

# Vérifiez que son API répond
curl http://localhost:6333/collections
# → {"result":{"collections":[]}, ...}  (aucune collection pour l'instant)

Projet RAG Dockerisé

Architecture

flowchart TB
  U["Navigateur"] --> F[" frontend"]
  F -->|/index, /ask| B[" backend<br/>FastAPI (orchestre le RAG)"]
  B -->|embeddings + LLM| API[" API d'IA<br/>(compatible OpenAI)"]
  B -->|stocke / cherche vecteurs| Q[" base vectorielle<br/>Qdrant"]
  Q --> V[" volume qdrant"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Structure du projet

Le backend : le cœur du RAG

fastapi==0.115.0
uvicorn[standard]==0.30.6
openai==1.51.0
qdrant-client==1.11.3

import os, uuid
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
from openai import OpenAI
from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct

app = FastAPI(title="RAG Chatbot")
app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])

# --- Clients, tout depuis l'environnement ---
ai = OpenAI(base_url=os.environ["AI_BASE_URL"], api_key=os.environ["AI_API_KEY"])
EMBED_MODEL = os.environ.get("EMBED_MODEL", "text-embedding-3-small")
CHAT_MODEL  = os.environ.get("AI_MODEL", "gpt-4o-mini")
VECTOR_SIZE = int(os.environ.get("VECTOR_SIZE", "1536"))

qdrant = QdrantClient(url=os.environ["QDRANT_URL"])   # ex. http://qdrant:6333
COLLECTION = "documents"

@app.on_event("startup")
def setup():
    if not qdrant.collection_exists(COLLECTION):
        qdrant.create_collection(COLLECTION,
            vectors_config=VectorParams(size=VECTOR_SIZE, distance=Distance.COSINE))

def embed(texte: str):
    return ai.embeddings.create(model=EMBED_MODEL, input=texte).data[0].embedding

def decouper(texte: str, taille: int = 500):
    # Découpage simple en chunks de ~500 caractères
    return [texte[i:i+taille] for i in range(0, len(texte), taille)]

class Doc(BaseModel):
    texte: str
class Question(BaseModel):
    question: str

# ---------- PHASE 1 : INDEXATION ----------
@app.post("/index")
def indexer(doc: Doc):
    points = []
    for chunk in decouper(doc.texte):
        points.append(PointStruct(id=str(uuid.uuid4()),
            vector=embed(chunk), payload={"texte": chunk}))
    qdrant.upsert(COLLECTION, points=points)
    return {"chunks_indexes": len(points)}

# ---------- PHASE 2 : INTERROGATION ----------
@app.post("/ask")
def demander(q: Question):
    # 1) retrouver les chunks proches de la question
    trouves = qdrant.search(COLLECTION, query_vector=embed(q.question), limit=3)
    contexte = "\n\n".join(p.payload["texte"] for p in trouves)
    # 2) construire le prompt avec le contexte
    prompt = (f"Réponds à la question en te basant UNIQUEMENT sur le contexte.\n\n"
              f"Contexte :\n{contexte}\n\nQuestion : {q.question}")
    # 3) demander au LLM
    r = ai.chat.completions.create(model=CHAT_MODEL,
        messages=[{"role": "user", "content": prompt}])
    return {"reponse": r.choices[0].message.content, "sources": len(trouves)}

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Le frontend (minimal)

<textarea id="doc" placeholder="Collez un document…"></textarea>
<button onclick="indexer()">Indexer</button>
<input id="q" placeholder="Votre question">
<button onclick="demander()">Demander</button>
<pre id="rep"></pre>
<script>
  const API = "http://localhost:8000";
  async function indexer(){
    await fetch(API+"/index",{method:"POST",headers:{"Content-Type":"application/json"},
      body:JSON.stringify({texte:doc.value})});
    alert("Document indexé !");
  }
  async function demander(){
    const r=await fetch(API+"/ask",{method:"POST",headers:{"Content-Type":"application/json"},
      body:JSON.stringify({question:q.value})});
    rep.textContent=(await r.json()).reponse;
  }
</script>

FROM nginx:alpine
COPY index.html /usr/share/nginx/html/index.html
EXPOSE 80

L'orchestration

AI_BASE_URL=https://api.mon-fournisseur.com/v1
AI_API_KEY=sk-votre-cle
AI_MODEL=gpt-4o-mini
EMBED_MODEL=text-embedding-3-small
VECTOR_SIZE=1536

services:
  frontend:
    build: ./frontend
    ports: ["8080:80"]
    depends_on: [backend]

  backend:
    build: ./backend
    ports: ["8000:8000"]
    environment:
      AI_BASE_URL: ${AI_BASE_URL}
      AI_API_KEY: ${AI_API_KEY}
      AI_MODEL: ${AI_MODEL}
      EMBED_MODEL: ${EMBED_MODEL}
      VECTOR_SIZE: ${VECTOR_SIZE}
      QDRANT_URL: http://qdrant:6333        # nom du service (Ch.12) !
    depends_on: [qdrant]

  qdrant:
    image: qdrant/qdrant:latest
    volumes:
      - qdrant:/qdrant/storage               # persistance des vecteurs (Ch.13)

volumes:
  qdrant:

Lancer, indexer, interroger

docker compose up --build -d
# Ouvrez http://localhost:8080
# 1) collez un texte, cliquez « Indexer »
# 2) posez une question sur ce texte, cliquez « Demander »

Résultat attendu : la réponse est fondée sur le document que vous avez fourni — même si le modèle ne « connaissait » pas ce contenu. Testez la persistance : docker compose down puis up ; grâce au volume qdrant, vos documents restent indexés.

Erreurs possibles

• Dimension d'embedding incohérente → VECTOR_SIZE doit correspondre à la taille des vecteurs du modèle d'embeddings choisi. Une erreur Qdrant sur la dimension pointe ici.
• Le backend ne joint pas Qdrant → utilisez le nom de service qdrant, pas localhost (Chapitre 12).
• 401 sur les embeddings/LLM → clé absente ou fournisseur qui ne propose pas d'endpoint d'embeddings (vérifiez son API).
• Réponses hors-sujet → augmentez le nombre de chunks récupérés (limit) ou affinez la taille des chunks.

Exécuter un modèle IA localement

Le concept : faire « penser » un modèle sur votre machine

Faire tourner un modèle localement, c'est exécuter l'inference — le calcul par lequel un modèle produit une réponse — sur votre matériel plutôt que chez un fournisseur. Trois notions à connaître :

Deux outils pour l'IA locale en 2026

Architecture

flowchart LR
  A["Votre application"] --> D[" Conteneur app"]
  D -->|API compatible OpenAI| O[" Conteneur Ollama<br/>(runtime d'inference)"]
  O --> M[" Modèle local<br/>(fichier quantizé)"]
  M --> V[" volume<br/>(modèles persistés)"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Ollama en conteneur, en pratique

# Démarrer Ollama en conteneur, avec un volume pour garder les modèles
docker run -d -p 11434:11434 -v ollama:/root/.ollama --name ollama ollama/ollama

# Télécharger un modèle léger (exemple)
docker exec -it ollama ollama pull llama3.2

AI_BASE_URL=http://ollama:11434/v1   # le conteneur Ollama, par son nom
AI_API_KEY=ollama                    # clé factice : Ollama n'en exige pas
AI_MODEL=llama3.2

Orchestrer app + Ollama avec Compose

services:
  app:
    build: .
    ports: ["8000:8000"]
    environment:
      AI_BASE_URL: http://ollama:11434/v1
      AI_API_KEY: ollama
      AI_MODEL: llama3.2
    depends_on: [ollama]

  ollama:
    image: ollama/ollama
    volumes:
      - ollama:/root/.ollama          # modèles persistés (Ch.13)

volumes:
  ollama:

API distante vs locale : que choisir ?

Comprendre Docker et GPU

Pourquoi un GPU pour l'IA ?

L'inference d'un modèle, c'est une avalanche de calculs matriciels. Un GPU (processeur graphique) est conçu pour faire un très grand nombre de ces calculs en parallèle — bien plus vite qu'un CPU. Résultat : des réponses en secondes plutôt qu'en dizaines de secondes. Pour l'IA locale, le GPU fait souvent la différence entre « utilisable » et « frustrant ».

Les pièces du puzzle

flowchart TD
  A[" Conteneur (app IA)"] --> B[" Docker + NVIDIA Container Toolkit"]
  B --> C[" Pilote GPU (hôte)"]
  C --> D[" GPU physique (CUDA)"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Les prérequis, en toute honnêteté

Donner le GPU à un conteneur

Une fois le NVIDIA Container Toolkit installé sur l'hôte, l'option --gpus expose le GPU au conteneur. Un test rapide :

docker run --gpus all --rm nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

Si tout est en place, nvidia-smi affiche votre carte graphique depuis l'intérieur du conteneur : la preuve que le conteneur a bien accès au GPU.

Exemple concret : Ollama avec GPU

Reprenons Ollama du Chapitre 29 et donnons-lui le GPU pour accélérer l'inference.

docker run -d --gpus all -p 11434:11434 -v ollama:/root/.ollama --name ollama ollama/ollama

En Compose, on déclare la réservation de GPU ainsi :

services:
  ollama:
    image: ollama/ollama
    volumes:
      - ollama:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  ollama:

Toujours prévoir l'alternative CPU

C'est une règle d'or de ce livre : votre projet doit rester utilisable sans GPU. La bonne nouvelle, c'est qu'Ollama (et la plupart des runtimes) basculent automatiquement sur le CPU si aucun GPU n'est disponible. Concrètement :

• Avec GPU : ajoutez --gpus all (ou la section deploy) → inference rapide.
• Sans GPU : retirez simplement cette partie → même conteneur, inference sur CPU (plus lente, mais fonctionnelle).

Si ça ne fonctionne pas

Comment aborder ces projets

Chaque projet réutilise des chapitres précédents. Vous avez déjà écrit une grande partie du code : ces projets vous apprennent à assembler et à décider seul.

Projet 1 Débutant

« Mon premier environnement Docker »

Contexte & objectif

Une application minimale connectée à une base de données PostgreSQL. Objectif : maîtriser les briques fondamentales — un Dockerfile, un conteneur applicatif, un volume, un réseau, des variables — sans encore utiliser Compose, pour bien sentir chaque geste.

Architecture

flowchart LR
  A[" Application<br/>(API simple)"] -->|réseau Docker| D[" PostgreSQL"]
  D --> V[" Volume (données)"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Cahier des charges

• Une petite application (Node.js, Python ou autre) qui se connecte à PostgreSQL et lit/écrit une donnée.
• Un Dockerfile propre pour l'application (base -slim, cache des dépendances, non-root).
• PostgreSQL lancé avec un volume pour la persistance et ses variables (POSTGRES_*).
• Les deux conteneurs sur un réseau commun, l'app joignant la base par son nom de conteneur.
• La configuration (URL de base, identifiants) passée par variables d'environnement.

Étapes suggérées

1. Créer le réseau : docker network create projet1-net.
2. Lancer PostgreSQL sur ce réseau, avec volume et mot de passe (Chapitres 4, 13, 14).
3. Écrire l'application et son Dockerfile (Chapitres 6, 7, 9 ou 10).
4. Construire l'image, lancer l'app sur le réseau, connectée à la base par son nom (Chapitres 8, 12).

Critères de réussite (tests)

• L'application démarre et lit/écrit dans PostgreSQL.
• Après docker stop + docker start de la base, les données sont toujours là (volume OK).
• Changer un identifiant se fait par variable, sans reconstruire l'image.

Projet 2 Intermédiaire

« Application Web complète »

Contexte & objectif

Une vraie application web à quatre services, orchestrée par Docker Compose. Objectif : maîtriser l'assemblage frontend + backend + base + cache, avec réseau automatique, volumes et healthchecks.

Architecture

flowchart TB
  U["Navigateur"] --> F[" Frontend"]
  F --> B[" Backend (API REST)"]
  B --> P[" PostgreSQL"]
  B --> R[" Redis (cache)"]
  P --> V[" volume"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Cahier des charges

• Une application réaliste (ex. gestionnaire de tâches, mini-blog, liste de réservations) avec des opérations de lecture/écriture.
• Backend REST connecté à PostgreSQL (persistance) et Redis (cache ou compteur).
• Frontend qui consomme l'API.
• Un unique docker-compose.yml avec réseau automatique, volume pour la base, variables via .env, et depends_on + healthcheck.

Critères de réussite (tests)

• Un seul docker compose up démarre les 4 services.
• Les données persistent après docker compose down puis up.
• Le backend attend que la base soit saine (healthcheck) avant de démarrer.
• Redis apporte une valeur réelle (cache accéléré, compteur, sessions…).

Projet 3 Avancé ·

« API IA Dockerisée »

Contexte & objectif

Une application qui génère du texte via un modèle d'IA, avec historique et gestion robuste des erreurs. Objectif : intégrer proprement une IA dans une architecture conteneurisée.

Architecture

flowchart LR
  U["Navigateur"] --> F[" Frontend"]
  F --> B[" Backend<br/>FastAPI"]
  B -->|génération| API["/ API d'IA<br/>(distante ou locale)"]
  B -->|historique| P[" PostgreSQL"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Cahier des charges

• Un frontend où l'utilisateur saisit un prompt et voit la réponse générée.
• Un backend FastAPI qui appelle un modèle via l'API compatible OpenAI (Chapitre 26), agnostique (distant ou local).
• Historique des échanges stocké en PostgreSQL.
• Gestion des erreurs et des timeouts (le modèle peut être lent ou indisponible).
• Clé d'API et configuration par variables d'environnement ; logs lisibles.

Critères de réussite (tests)

• Une question renvoie une réponse générée par le modèle.
• L'historique se retrouve après redémarrage (persistance).
• Si le modèle est indisponible, l'application affiche un message clair au lieu de planter.
• Basculer d'une API distante à un modèle local (Ollama) se fait par variables, sans changer le code.

Objectif

Construire une application RAG de production miniature, entièrement conteneurisée, qui : reçoit des documents, en extrait le texte, calcule des embeddings, les stocke dans une base vectorielle, effectue une recherche vectorielle à chaque question, et génère une réponse fondée sur les documents — le tout avec une interface web, un backend, une base de données et une orchestration Compose.

Architecture

flowchart TB
  U["Navigateur"] --> F[" Frontend"]
  F -->|upload / questions| B[" Backend · FastAPI"]
  B --> P[" PostgreSQL<br/>(documents, historique)"]
  B --> Q[" Base vectorielle<br/>(Qdrant)"]
  B --> AI["/ API d'IA<br/>(embeddings + LLM)"]
  P --> VP[" volume"]
  Q --> VQ[" volume"]
  classDef default fill:#EAF2FE,stroke:#2079E8,color:#12213A,stroke-width:1.5px;

Fonctionnalités attendues

Plan de construction suggéré

1. Repartez du chatbot RAG du Chapitre 28 (backend FastAPI + Qdrant + API d'IA). C'est votre socle.
2. Ajoutez PostgreSQL (Chapitres 8, 13, 16) pour stocker les métadonnées des documents et l'historique des questions/réponses.
3. Gérez l'upload de fichiers : un endpoint qui reçoit un fichier, en extrait le texte, puis lance l'indexation existante.
4. Enrichissez le frontend : zone de téléversement, liste des documents indexés, zone de question, affichage de la réponse et des extraits sources.
5. Orchestrez tout dans un docker-compose.yml : frontend, backend, PostgreSQL, Qdrant — avec volumes, .env, depends_on + healthchecks.
6. Soignez la robustesse : erreurs d'IA gérées, logs clairs, images propres (multi-stage pour le frontend, non-root).

Critères de réussite

• Un seul docker compose up --build démarre toute l'application.
• L'utilisateur téléverse un document, puis obtient des réponses fondées sur ce document.
• Les documents indexés et l'historique persistent après redémarrage (volumes).
• Chaque service joint les autres par leur nom ; aucune clé n'est dans le code.
• L'application ne plante pas si l'IA est momentanément indisponible.

Démarrer un projet Docker de zéro

La bonne posture : penser en services

Devant un nouveau projet, ne commencez pas par écrire du Dockerfile. Commencez par lister les services : de quoi l'application a-t-elle besoin pour tourner ? Un backend, une base, un cache, un frontend, un modèle d'IA ? Chaque brique deviendra un conteneur. Cette vue d'ensemble guide tout le reste.

La checklist de démarrage en 12 étapes

Checklist Docker professionnelle

Gardez cette page sous la main : c'est le récapitulatif de tout le livre, condensé en points à vérifier. Avant de considérer un projet « prêt », passez-la en revue.

Cheat sheets

Commandes Docker essentielles

# Conteneurs
docker run -d -p 8080:80 --name web nginx   # créer + démarrer (arrière-plan)
docker ps -a                                # lister (tous)
docker stop|start|restart web               # cycle de vie
docker rm -f web                            # supprimer (forcé)
docker logs -f web                          # suivre les logs
docker exec -it web sh                      # entrer dans le conteneur
docker inspect web                          # détails (JSON)

# Images
docker build -t mon-app .                   # construire
docker images                               # lister
docker rmi mon-app                          # supprimer
docker history mon-app                      # couches

# Registry
docker login
docker tag mon-app user/mon-app:1.0.0
docker push user/mon-app:1.0.0
docker pull user/mon-app:1.0.0

# Réseaux & volumes
docker network create net && docker network ls
docker volume create data && docker volume ls

# Nettoyage
docker system prune -a                      # tout ce qui est inutilisé (attention !)

Dockerfile cheat sheet

FROM python:3.12-slim        # base légère, versionnée
WORKDIR /app                  # dossier de travail
COPY requirements.txt .       # dépendances D'ABORD (cache)
RUN pip install --no-cache-dir -r requirements.txt
COPY . .                      # code ENSUITE
ENV APP_ENV=production        # variable
RUN useradd -m appuser && true
USER appuser                  # non-root
EXPOSE 8000                   # documentation du port
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

# Multi-stage : construire dans une étape, ne garder que le résultat
FROM node:22-slim AS build
WORKDIR /app
COPY . . && RUN npm ci && npm run build
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html

Docker Compose cheat sheet

services:
  api:
    build: .
    ports: ["8000:8000"]
    env_file: .env
    depends_on:
      db: { condition: service_healthy }
    restart: unless-stopped
  db:
    image: postgres:16
    environment: { POSTGRES_PASSWORD: secret }
    volumes: ["pgdata:/var/lib/postgresql/data"]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 5
volumes: { pgdata: {} }

docker compose up -d --build     # construire + démarrer (arrière-plan)
docker compose ps                # état des services
docker compose logs -f api       # logs d'un service
docker compose down              # arrêter + supprimer
docker compose down -v           # + supprimer les volumes (efface les données)

Debugging cheat sheet

docker ps -a                     # 1. le conteneur tourne-t-il ?
docker logs <nom>                 # 2. que dit l'application ?  (n°1 !)
docker inspect <nom>              # 3. config, réseau, variables
# 4. ports  5. réseau  6. variables  7. volumes
docker exec -it <nom> sh          # déboguer de l'intérieur

Docker + IA cheat sheet

# API distante
AI_BASE_URL=https://api.fournisseur.com/v1
AI_API_KEY=sk-...
AI_MODEL=gpt-4o-mini

# Modèle local (Ollama) : on change juste ces valeurs
AI_BASE_URL=http://ollama:11434/v1
AI_API_KEY=ollama
AI_MODEL=llama3.2

docker run -d -p 11434:11434 -v ollama:/root/.ollama --name ollama ollama/ollama
docker exec -it ollama ollama pull llama3.2
docker run --gpus all --rm nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi   # test GPU

from openai import OpenAI
client = OpenAI(base_url=os.environ["AI_BASE_URL"], api_key=os.environ["AI_API_KEY"])
r = client.chat.completions.create(model=MODELE,
    messages=[{"role":"user","content":prompt}])

Glossaire

Les termes clés du livre, définis simplement.

Évaluation finale

Le test de vérité. Répondez sans regarder le livre ; les corrections sont repliées. Si un domaine vous met en difficulté, relisez le chapitre correspondant — c'est le but.

1. Théorie

2. Commandes à écrire

docker run -d -p 9090:80 nginx
docker logs -f api
docker build -t monsite:1.0 .
docker exec -it db sh

3. Déboguer

4. Compléter un Dockerfile

FROM python:3.12-slim
WORKDIR /app
# … à compléter …
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
RUN useradd -m appuser
USER appuser
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

5. Corriger un docker-compose.yml

services:
  api:
    build: .
    environment:
      DATABASE_URL: postgresql://user:pass@localhost:5432/app
  db:
    image: postgres:16
    environment: { POSTGRES_PASSWORD: pass }

6. Problèmes IA, réseau et volume

7. Concevoir une architecture

Vous êtes arrivé au bout

Souvenez-vous du premier docker run hello-world. Vous étiez peut-être un débutant complet. Aujourd'hui, vous concevez des architectures conteneurisées intégrant de l'intelligence artificielle. Ce chemin, vous l'avez parcouru avec vos mains.

Vous avez traversé toute la trajectoire promise en ouverture :

La dernière page : pouvez-vous répondre « oui » ?

La formation est réussie si vous répondez « oui » à ces questions. Sinon, le chapitre indiqué vous attend.

Kelenix Tech — Docker + IA

Fin du livre · De Zéro à Professionnel · Édition 2026