# Docker

Docker empaquette un programme avec tout ce qu'il lui faut pour tourner : le langage, les bibliothèques, les fichiers. Le paquet obtenu se lance de la même façon sur n'importe quelle machine qui a Docker.

## Le problème

L'[API des scores](/reseau/api) marche sur le poste où elle a été écrite. Pour la lancer ailleurs, il faut refaire à la main : installer la bonne version de Python, créer l'environnement virtuel, installer les dépendances, lancer `uvicorn` avec les bonnes options.

Chaque étape peut différer d'une machine à l'autre. C'est la phrase la plus connue du métier : « chez moi, ça marche ».

Docker remplace cette liste d'étapes par un fichier, que la machine exécute toujours de la même façon.

## La notion

### Image et conteneur

| Mot | Sens | Comparaison avec Python |
| --- | --- | --- |
| Image | Un modèle figé : système de fichiers, programme, commande de démarrage | Une classe |
| Conteneur | Une image en train de tourner | Un objet créé à partir de la classe |
| Dockerfile | La recette qui construit une image | Le code source de la classe |
| Registre | Le dépôt où l'on publie et télécharge des images, Docker Hub par défaut | pypi.org |

À partir d'une image, on peut lancer autant de conteneurs qu'on veut. Supprimer un conteneur ne touche pas à l'image.

<Mermaid
  chart={`flowchart LR
    df[Dockerfile] -- docker build --> img[Image<br/>scores-api]
    img -- docker run --> c1[Conteneur]
    img -- docker run --> c2[Conteneur]
    hub[(Docker Hub)] -- docker pull --> base[Image de base<br/>python 3.13-slim]
    base -.-> df`}
/>

### Ce qu'un conteneur isole

Un conteneur a ses propres fichiers, ses propres programmes et son propre réseau. Il ne voit ni les fichiers de l'hôte ni ses ports, sauf ce qu'on lui ouvre explicitement. Contrairement à une [machine virtuelle](/virtualisation/virtualbox), il n'embarque pas de système complet : il utilise le noyau de l'hôte, ce qui le rend léger et rapide à démarrer.

## Installer Docker

| Système | Méthode |
| --- | --- |
| macOS, Windows | Docker Desktop, à télécharger sur docker.com, ou `brew install --cask docker` sur macOS |
| Ubuntu, Debian | Docker Engine, en suivant la page d'installation de docs.docker.com |

```bash
docker --version
docker run hello-world     # télécharge une image d'essai et la lance
```

## Lancer une image existante

Avant d'écrire la sienne, on peut utiliser celles des autres. Ici, un Python 3.13 sans rien installer sur la machine :

```bash
docker run -it --rm python:3.13-slim python
```

| Morceau | Sens |
| --- | --- |
| `docker run` | Crée un conteneur et le démarre |
| `-it` | Mode interactif, avec un terminal |
| `--rm` | Supprime le conteneur à la sortie |
| `python:3.13-slim` | L'image, sous la forme `nom:étiquette` |
| `python` | La commande à lancer dedans |

L'étiquette désigne une version. Sans elle, Docker prend `latest`, qui change avec le temps : on précise toujours l'étiquette, pour la même raison qu'on [fige les versions](/terminal/gestionnaires-de-paquets) dans `requirements.txt`.

## Écrire un Dockerfile

Le fichier s'appelle `Dockerfile`, sans extension, et se place dans `server/`.

```text
server/
├── Dockerfile
├── main.py
└── requirements.txt
```

```dockerfile
FROM python:3.13-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY main.py .

EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```

| Instruction | Rôle |
| --- | --- |
| `FROM` | L'image de départ. Ici un Linux minimal avec Python 3.13 |
| `WORKDIR` | Le dossier courant dans l'image, créé s'il n'existe pas |
| `COPY` | Copie des fichiers de l'hôte vers l'image |
| `RUN` | Exécute une commande **pendant la construction** |
| `EXPOSE` | Indique le port écouté. Purement informatif |
| `CMD` | La commande lancée **au démarrage du conteneur** |

Deux détails qui comptent.

**`--host 0.0.0.0`.** Dans un conteneur, `127.0.0.1` désigne le conteneur lui-même. Un serveur qui n'écoute que là est injoignable de l'extérieur. Voir [Le serveur](/reseau/serveur).

**L'ordre des `COPY`.** Docker garde en cache le résultat de chaque instruction, et ne refait que ce qui suit la première ligne modifiée. En copiant `requirements.txt` avant le code, l'installation des dépendances n'est refaite que si elles changent. Modifier `main.py` reconstruit l'image en une seconde.

## Construire et lancer

```bash
cd server
docker build -t scores-api .
```

`-t` donne un nom à l'image. Le point final désigne le dossier dont Docker peut copier les fichiers.

```bash
docker run -d --name scores -p 8000:8000 scores-api
```

| Morceau | Sens |
| --- | --- |
| `-d` | En arrière-plan : le terminal rend la main |
| `--name scores` | Un nom pour retrouver le conteneur |
| `-p 8000:8000` | Relie le port 8000 de l'hôte au port 8000 du conteneur |

L'ordre de `-p` est toujours **hôte, puis conteneur**.

<Mermaid
  chart={`flowchart LR
    subgraph hote [Hôte]
      curl[curl ou le jeu]
      ph((port 8000))
    end
    subgraph cont [Conteneur scores]
      pc((port 8000))
      uv[uvicorn]
    end
    curl --> ph
    ph -- "-p 8000:8000" --> pc
    pc --> uv`}
/>

```bash
curl http://localhost:8000/scores
```

```text
[]
```

L'API répond, sans que Python ni FastAPI soient installés sur l'hôte.

## Les commandes du quotidien

| Commande | Effet |
| --- | --- |
| `docker ps` | Les conteneurs qui tournent |
| `docker ps -a` | Tous, y compris les arrêtés |
| `docker logs scores` | Les journaux du conteneur |
| `docker logs -f scores` | Les suit en direct |
| `docker exec -it scores bash` | Ouvre un terminal **dans** le conteneur |
| `docker stop scores` | Arrête |
| `docker start scores` | Redémarre un conteneur arrêté |
| `docker rm scores` | Supprime le conteneur |
| `docker images` | Les images présentes |
| `docker rmi scores-api` | Supprime une image |

## Le fichier .dockerignore

Comme `.gitignore`, il liste ce que Docker ne doit pas copier dans l'image. À placer à côté du `Dockerfile`.

```text
.venv
__pycache__
*.pyc
.env
```

Sans lui, un `COPY . .` embarquerait l'environnement virtuel de l'hôte, et les éventuels secrets du fichier `.env`.

## Les données ne survivent pas au conteneur

Tout ce qu'un conteneur écrit disparaît quand on le supprime. Pour l'API, les scores sont de toute façon en mémoire. Mais le problème serait le même s'ils étaient écrits dans un fichier.

La réponse est le **volume** : un espace de stockage géré par Docker, qui vit en dehors du conteneur.

```bash
docker run -d --name scores -p 8000:8000 -v scores-data:/app/data scores-api
```

`-v scores-data:/app/data` branche le volume `scores-data` sur le dossier `/app/data` du conteneur. Le cours [Docker Compose](/virtualisation/docker-compose) s'en sert pour garder les scores dans une base de données.

## Les erreurs fréquentes

| Message ou symptôme | Cause | Solution |
| --- | --- | --- |
| `port is already allocated` | Un autre programme ou conteneur occupe déjà le port de l'hôte | Changer le premier nombre : `-p 8001:8000` |
| `Cannot connect to the Docker daemon` | Docker n'est pas démarré | Lancer Docker Desktop, ou le service Docker |
| `container name is already in use` | Un conteneur arrêté porte déjà ce nom | `docker rm scores` |
| Le conteneur s'arrête tout de suite | Le programme a planté au démarrage | `docker logs scores` |
| Le code modifié n'est pas pris en compte | L'image n'a pas été reconstruite | `docker build`, puis relancer un conteneur |
| `curl` ne répond pas alors que le conteneur tourne | Port non publié, ou serveur sur `127.0.0.1` | Vérifier `-p` et `--host 0.0.0.0` |

## Dans le projet

Tout ne gagne pas à être mis dans un conteneur.

| Partie du projet | Conteneur ? | Pourquoi |
| --- | --- | --- |
| L'API des scores | Oui | Un serveur sans écran, à faire tourner ailleurs que sur son poste |
| Les tests `pytest` | Possible | Même version de Python pour tout le monde |
| Ce site de documentation | Possible | Pour le publier |
| Le jeu Pygame | Non | Il a besoin d'une fenêtre, d'un clavier et du son. Un conteneur n'a pas d'écran |

C'est une raison de plus de séparer les règles du jeu de l'affichage : des règles sans Pygame peuvent tourner dans un conteneur, donc sur un serveur.

## À retenir

- Une image est un modèle, un conteneur est une image qui tourne.
- Le Dockerfile est la recette : `FROM`, `COPY`, `RUN`, `CMD`.
- `-p hôte:conteneur` ouvre un port, `-v` branche un volume.
- Dans un conteneur, un serveur écoute sur `0.0.0.0`.
- Ce qu'un conteneur écrit disparaît avec lui, sauf dans un volume.

## Exercices

1. Lancer un interpréteur Python 3.13 dans un conteneur, sans rien installer. Vérifier la version, puis sortir.
2. Écrire le `Dockerfile` de l'API, construire l'image, lancer le conteneur et ajouter un score avec `curl`.
3. Modifier `main.py`, reconstruire, et observer dans la sortie quelles étapes viennent du cache. Inverser les deux `COPY` et comparer.
4. Ajouter deux scores, supprimer le conteneur, en relancer un. Que sont devenus les scores ?
5. Lancer un deuxième conteneur de la même image sur le port 8001. Les deux partagent-ils leurs scores ? Pourquoi ?
6. Ouvrir un terminal dans le conteneur avec `docker exec` et lister le contenu de `/app`.
