feat: docs

2026-07-17 16:15:54 +02:00
parent 0c2f42b4a3
commit 1542a991b9
38 changed files with 6366 additions and 19 deletions
@@ -0,0 +1,64 @@
+---
+title: Conteneur vs machine virtuelle
+description: Deux formes d'isolation qui ne travaillent pas au même niveau.
+---
+
+C'est la distinction fondamentale : une machine virtuelle et un conteneur isolent tous les deux une application, mais pas de la même manière.
+
+## Machine virtuelle
+
+Une VM virtualise le **matériel**. Un hyperviseur simule une machine physique complète sur laquelle on installe un système d'exploitation invité, noyau compris.
+
+```text
+┌──────────────────────────────────────────┐
+│ App A       │ App B       │ App C        │
+├─────────────┼─────────────┼──────────────┤
+│ Bins / libs │ Bins / libs │ Bins / libs  │
+├─────────────┼─────────────┼──────────────┤
+│ OS invité   │ OS invité   │ OS invité    │
+│ + noyau     │ + noyau     │ + noyau      │
+├──────────────────────────────────────────┤
+│ Hyperviseur                             │
+├──────────────────────────────────────────┤
+│ OS hôte + matériel                      │
+└──────────────────────────────────────────┘
+```
+
+Chaque VM doit démarrer un OS complet. Cela demande plusieurs gigaoctets de stockage ou de mémoire et des dizaines de secondes de démarrage.
+
+## Conteneur
+
+Un conteneur ne virtualise ni le matériel ni le noyau. Il partage le noyau de l'hôte et isole la vue qu'a le processus du système.
+
+Deux mécanismes du noyau Linux rendent cela possible :
+
+- **namespaces** : chaque conteneur voit ses propres processus, son réseau et son système de fichiers ;
+- **cgroups** : le système peut limiter sa consommation de CPU et de mémoire.
+
+```text
+┌──────────────────────────────────────────┐
+│ App A       │ App B       │ App C        │
+├─────────────┼─────────────┼──────────────┤
+│ Bins / libs │ Bins / libs │ Bins / libs  │
+├──────────────────────────────────────────┤
+│ Docker Engine                           │
+├──────────────────────────────────────────┤
+│ OS hôte - noyau partagé                 │
+└──────────────────────────────────────────┘
+```
+
+Le conteneur contient uniquement le userspace minimal nécessaire : binaires, bibliothèques et application. Il emprunte le noyau à l'hôte.
+
+## Comparaison
+
+| Critère | Machine virtuelle | Conteneur |
+| --- | --- | --- |
+| Niveau d'isolation | Matériel, avec noyau invité dédié | Processus, avec noyau partagé |
+| Poids | Plusieurs Go | Quelques Mo à quelques centaines de Mo |
+| Démarrage | Dizaines de secondes | Secondes ou moins |
+| Densité | Quelques VM par machine | Des dizaines ou centaines de conteneurs |
+| Frontière de sécurité | Plus forte | Plus légère, mais suffisante pour beaucoup d'usages |
+
+<Callout title="Un conteneur n'est pas une mini-VM" type="warning">
+  Dans l'usage, le résultat peut sembler proche. Techniquement, un conteneur reste un processus isolé. Sur Mac et Windows, tous les conteneurs partagent le noyau de la même VM Docker Desktop, au lieu d'utiliser une VM par service.
+</Callout>
@@ -0,0 +1,48 @@
+---
+title: Docker Engine et Docker Desktop
+description: Distinguer le moteur Docker de l'application qui l'exécute sur Mac et Windows.
+---
+
+## Docker Engine
+
+Docker Engine est le cœur de Docker. Il comprend :
+
+- le daemon `dockerd`, qui construit les images et fait tourner les conteneurs ;
+- la CLI `docker`, utilisée depuis le terminal pour parler au daemon.
+
+Docker Engine est nativement Linux. Il s'appuie sur des fonctionnalités du noyau Linux, notamment les namespaces et les cgroups.
+
+## Sur Mac et Windows
+
+Le noyau requis étant un noyau Linux, Docker fait tourner une petite VM Linux en arrière-plan. Docker Engine vit dans cette VM et les conteneurs tournent dans ce Linux, pas directement dans macOS ou Windows.
+
+Docker Desktop orchestre cet ensemble :
+
+- il crée et maintient la VM Linux ;
+- il expose la commande `docker` dans le terminal hôte ;
+- il fournit une interface graphique ;
+- il gère le partage des fichiers et des ports entre l'hôte et la VM.
+
+| Plateforme | Où tourne Docker Engine ? |
+| --- | --- |
+| Linux | Directement sur le système hôte |
+| macOS | Dans la VM Linux gérée par Docker Desktop |
+| Windows | Dans la VM Linux gérée par Docker Desktop |
+
+## Conséquences pratiques
+
+### Bind mounts sur Mac et Windows
+
+Quand un dossier de l'hôte est monté dans un conteneur, les fichiers traversent la frontière entre l'hôte et la VM Linux. Les entrées-sorties peuvent être moins rapides qu'avec un accès Linux natif, notamment sur de gros dossiers comme `node_modules`.
+
+### Volumes Docker
+
+Un volume Docker vit dans le système de fichiers du Docker Engine. Sur Mac et Windows, il se trouve donc dans la VM Linux. Il reste rapide et persiste indépendamment du dossier du projet.
+
+### Serveur Linux
+
+Sur un VPS Linux de production, il n'y a pas cette VM intermédiaire : Docker Engine tourne directement sur l'OS. C'est le cas le plus simple et le plus efficace.
+
+<Callout title="À retenir" type="info">
+  Docker Desktop n'est pas le moteur lui-même. C'est l'application qui rend Docker Engine utilisable sur Mac et Windows en gérant une VM Linux discrète.
+</Callout>
@@ -0,0 +1,5 @@
+{
+  "title": "Fondamentaux",
+  "description": "Comprendre le rôle et le fonctionnement de Docker",
+  "pages": ["pourquoi-docker", "engine-et-desktop", "conteneur-vs-vm"]
+}
@@ -0,0 +1,46 @@
+---
+title: Pourquoi Docker ?
+description: Résoudre le problème « ça marche sur ma machine » avec un environnement reproductible.
+---
+
+## Le problème : « ça marche sur ma machine »
+
+Une application ne tourne jamais dans le vide. Elle dépend de tout un environnement :
+
+- une version de runtime, par exemple Node.js 25 ou Python 3.12 ;
+- des binaires système, comme OpenSSL ou un client PostgreSQL ;
+- des services externes : PostgreSQL 16, un broker, un stockage S3 ;
+- une configuration : variables d'environnement, chemins et ports.
+
+Sur une machine de développement, ce contexte existe parce qu'il a été installé au fil du temps. Sur la machine d'un collègue ou sur le serveur de production, il peut être différent ou absent. Le code identique fonctionne alors ici et casse ailleurs : le bug est dans l'environnement.
+
+## La réponse apportée par Docker
+
+Docker empaquette **l'application et son environnement** dans une unité reproductible : l'image.
+
+La même image peut tourner sur le poste de développement, dans la CI et sur le serveur de production. L'environnement n'est plus installé manuellement sur chaque machine : il est livré avec le code.
+
+## Les gains concrets
+
+| Gain | Ce que cela apporte |
+| --- | --- |
+| Iso dev / prod | La stack locale est construite avec les mêmes briques que la production. |
+| Isolation | Chaque service possède ses dépendances. PostgreSQL 16 d'un projet ne gêne pas PostgreSQL 14 d'un autre. |
+| Agnostique OS | L'image embarque son userspace Linux ; l'application voit le même environnement sur Mac, Windows ou Linux. |
+| Reproductibilité | Un Dockerfile versionné constitue une recette de construction exacte et partageable. |
+| Légèreté | Un conteneur partage le noyau de l'hôte, démarre rapidement et consomme moins de mémoire qu'une VM complète. |
+| Onboarding | Un nouveau développeur clone le dépôt et lance toute la stack sans installer chaque service à la main. |
+
+## Exemple d'onboarding
+
+Une stack de développement complète peut regrouper PostgreSQL, MinIO, Mailpit, un frontend, un backend et Nginx dans un seul fichier Compose.
+
+```bash
+docker compose -f docker-compose.dev.yml up
+```
+
+Cette commande remplace une longue liste d'installations manuelles et donne à toute l'équipe le même environnement.
+
+<Callout title="Idée centrale" type="success">
+  Docker déplace la complexité de l'installation de la machine vers une description versionnée : le Dockerfile pour une image, puis le fichier Compose pour toute la stack.
+</Callout>