infra / docker

Docker sous WSL2

Leçon 211 exercice

Explication

Ce que vous allez apprendre

Comprendre pourquoi Docker Desktop sur Windows s'appuie sur un vrai noyau Linux via WSL2
Identifier le piège de performance n°1 : la différence entre fichiers sous /mnt/c et fichiers natifs WSL2
Vérifier que le CLI Docker communique bien avec le bon contexte (desktop-linux)
Configurer les ressources allouées à WSL2 (.wslconfig) et savoir quand un redémarrage complet est nécessaire
Diagnostiquer un problème réseau ou de démon après une mise en veille prolongée de Windows

Dans quel contexte ?

Un développeur sous Windows se plaint que ses builds Docker prennent cinq fois plus de temps que ceux de ses collègues sous Linux, alors que le code et le Dockerfile sont identiques. En creusant, il découvre qu'il travaille depuis /mnt/c/Users/ned/projet, un chemin Windows monté dans WSL2 dont chaque accès disque traverse une couche de traduction réseau (le protocole 9P). En clonant son projet directement dans le filesystem natif de la distribution WSL2 (~/projet), ses temps de build reviennent à la normale.

Docker sur Windows n'exécute pas Docker "sur Windows"

Docker repose fondamentalement sur des mécanismes du noyau Linux (namespaces, cgroups, vus en toute première leçon). Windows ne dispose pas nativement de ces mécanismes. Docker Desktop contourne cette limite en s'appuyant sur WSL2 (Windows Subsystem for Linux version 2), qui fait tourner un véritable noyau Linux dans une machine virtuelle légère — le démon Docker s'exécute alors nativement dans ce Linux, et non "traduit" pour Windows. Comprendre cette architecture en une phrase permet d'anticiper la quasi-totalité des soucis de performance ou de réseau rencontrés en pratique.

Emplacement des fichiers	Performance I/O
`/mnt/c/...` (chemin Windows monté)	Lente, traverse le protocole 9P
`~/projet` (filesystem natif WSL2)	Quasi native Linux

Piège fréquent

Monter un dossier Windows (/mnt/c/...) en bind mount dans un conteneur multiplie les temps d'accès disque. La règle pratique à retenir : cloner et travailler sur son code depuis l'intérieur de WSL2, jamais depuis un chemin Windows monté.

Le piège de performance n°1 : où vivent les fichiers

C'est le point le plus important de cette leçon. Les fichiers situés sous /mnt/c/... sont en réalité stockés sur le disque Windows et accédés depuis Linux à travers une couche de traduction réseau (le protocole 9P), ce qui rend chaque opération disque nettement plus lente. Les fichiers situés directement dans le système de fichiers de la distribution WSL2 (par exemple sous ~/projet) bénéficient au contraire d'un accès disque quasi natif Linux. La règle pratique à retenir : cloner et travailler sur son code depuis l'intérieur de WSL2, jamais depuis un chemin Windows monté.

Le réseau, une bonne surprise

Contrairement à d'autres soucis d'intégration, le mapping de ports fonctionne de façon transparente entre la VM WSL2 et Windows : docker run -p 8000:8000 puis localhost:8000 depuis un navigateur Windows fonctionne directement, sans avoir besoin de connaître une quelconque adresse IP de machine virtuelle.

Un changement de configuration n'est jamais instantané

Modifier les ressources allouées à WSL2 (mémoire, nombre de processeurs) dans le fichier .wslconfig ne prend effet qu'après un arrêt complet de la machine virtuelle (wsl --shutdown) — un simple redémarrage de Docker Desktop ne suffit pas, contrairement à l'intuition.

Commandes & code

Docker sous WSL2

# Docker Desktop sur Windows utilise WSL2 (Windows Subsystem for Linux v2) comme moteur :
# un VRAI noyau Linux tourne dans une VM légère, Docker Engine s'exécute dedans nativement.
# Comprendre cette architecture évite la majorité des soucis de perf/réseau rencontrés.

# --- Vérifier l'intégration WSL2 <-> Docker Desktop ---
wsl --list --verbose                         # doit montrer "docker-desktop" et "docker-desktop-data"
wsl -d docker-desktop                          # entre dans la VM légère qui héberge le démon Docker

# Depuis une distro WSL2 (Ubuntu par ex.), vérifier que Docker CLI communique bien avec le démon
docker context ls                               # "desktop-linux" doit être le contexte actif
docker info | grep -i "operating system"          # confirme qu'on parle bien au démon Linux, pas un proxy Windows

# --- Le piège n°1 : emplacement des fichiers ---
# Fichiers sous /mnt/c/... (système de fichiers Windows monté dans WSL2) : accès TRÈS lent en I/O
# Fichiers sous ~/projet (système de fichiers EXT4 natif de la distro WSL2) : perf quasi native Linux

# MAUVAIS : bind mount vers un chemin Windows monté -> chaque accès disque traverse la frontière 9P
docker run -v /mnt/c/Users/ned/projet:/app mon-api:1.0

# BON : cloner/travailler directement dans le filesystem Linux de la distro WSL2
cd ~ && git clone https://github.com/moi/projet.git
docker run -v ~/projet:/app mon-api:1.0        # bind mount purement Linux -> Linux, rapide

# Depuis VS Code : l'extension "WSL" ouvre directement le dossier DANS la distro (pas via \\wsl$)
code ~/projet

# --- Réseau : docker run -p fonctionne "comme sous Linux", localhost partagé automatiquement ---
docker run -d -p 8000:8000 mon-api:1.0
curl http://localhost:8000/health          # accessible directement depuis Windows, pas besoin de l'IP de la VM

# --- Ressources allouées à la VM WSL2 (fichier de config global, pas par projet) ---
cat /mnt/c/Users/ned/.wslconfig
# [wsl2]
# memory=8GB
# processors=4
# swap=2GB
wsl --shutdown          # OBLIGATOIRE pour appliquer un changement de .wslconfig (redémarre toute la VM)

# --- Docker Compose : mêmes commandes qu'en natif Linux, aucune adaptation nécessaire ---
docker compose up -d
docker compose logs -f

# --- Diagnostiquer un problème typique WSL2 + Docker ---
wsl --status                              # version WSL active, distro par défaut
docker context inspect desktop-linux        # config réseau/socket du contexte Docker Desktop

# Si le démon semble "perdu" après une mise en veille prolongée de Windows
wsl --shutdown
# puis relancer Docker Desktop depuis Windows

# Espace disque : le disque virtuel WSL2 (.vhdx) grossit mais ne se réduit jamais automatiquement
docker system df                             # espace utilisé par Docker à l'intérieur de la VM
wsl --manage docker-desktop-data --set-sparse true    # (Windows 11) permet au vhdx de se réduire dynamiquement

Résumé

Docker Desktop exécute un vrai démon Linux dans une VM WSL2 ; les I/O sont natives Linux SEULEMENT si les fichiers vivent dans le filesystem WSL2, pas sous /mnt/c.
Tout changement dans .wslconfig (mémoire, CPU alloués) nécessite un wsl --shutdown complet pour être pris en compte.
Le port-forwarding -p fonctionne de façon transparente entre WSL2 et Windows : localhost suffit, aucune IP de VM à connaître.

Exercices pratiques

1 disponible

Mission : diviser par cinq le temps de build d'un développeur sous Windows

Objectif : Diagnostiquer un problème de performance lié à l'emplacement des fichiers sous WSL2 et appliquer un changement de ressources correctement.

Contexte

Un développeur sous Windows se plaint que ses builds Docker prennent cinq fois plus de temps que ceux de ses collègues Linux, avec un code et un Dockerfile strictement identiques. Son projet vit dans /mnt/c/Users/ned/projet.

Résoudre l’exercice →