Configuration WSL2 qui ne casse pas Docker (oui, il y a une bonne méthode)

La bonne méthode : ce que vous construisez réellement

Vous n’êtes pas en train « d’installer Linux sur Windows ». Vous construisez une petite pile de virtualisation gérée :

• Windows héberge l’infrastructure voisine du noyau (composants Hyper-V) que WSL2 utilise.
• WSL2 exécute une ou plusieurs distributions Linux à l’intérieur d’une VM légère. Chaque distribution a son propre disque virtuel (un VHDX).
• Docker s’exécute soit :
  • Docker Desktop, qui exécute sa propre VM Linux et peut s’intégrer aux distributions WSL2, ou
  • le moteur Docker à l’intérieur d’une distribution WSL2 (sans Docker Desktop), avec systemd et un comportement natif Linux.

La configuration « qui ne casse pas » repose sur trois thèmes :

1. Placez les bons fichiers sur le bon système de fichiers. Linux-sur-Linux pour les builds, node_modules et les couches d’images. Chemins Windows seulement si vous avez réellement besoin des outils Windows.
2. Contrôlez les ressources délibérément. WSL2 peut absorber la RAM et le disque jusqu’à ce que votre portable devienne un radiateur avec clavier.
3. Choisissez un modèle de propriété Docker. Soit Docker Desktop possède Docker, soit votre distribution Linux le fait. Les mélanger sans intention, c’est la garantie du « ça marchait hier ».

Une citation à garder au-dessus de votre écran : L’espoir n’est pas une stratégie. — General Gordon R. Sullivan

Faits et contexte intéressants (pour arrêter de faire des erreurs de 2019)

• WSL1 n’était pas une VM. Il traduisait les appels système Linux en appels du noyau Windows. Astuce ingénieuse, mais ce n’était pas du « vrai Linux », et Docker dans WSL1 était un projet scientifique.
• WSL2 est passé à un vrai noyau Linux. C’est pourquoi Docker est devenu pratique. C’est aussi la raison pour laquelle vous avez maintenant un vrai disque virtuel qui peut se remplir et se fragmenter.
• Les premières versions de WSL2 avaient des problèmes d’E/S sur /mnt/c. C’est pourquoi « cloner dans le home Linux » est devenu le conseil par défaut — et c’est toujours correct pour la plupart des charges de travail dev.
• Docker Desktop a déplacé son backend plusieurs fois. Backend Hyper-V, puis backend WSL2, avec des comportements d’intégration changeants selon les versions. Les anciens billets de blog deviennent trompeurs.
• Le réseau WSL2 utilise du NAT. C’est pourquoi la VM WSL2 a sa propre IP et pourquoi certains VPN/DNS se comportent comme s’ils étaient hantés.
• Le « shrink » du VHDX n’est pas automatique. Supprimer des fichiers dans Linux ne rend pas forcément l’espace à Windows. Il faut des étapes explicites de compactage.
• Le support systemd dans WSL est récent. Pendant des années, il n’y avait pas de systemd, ce qui changeait le comportement des services et de Docker. Aujourd’hui on peut l’activer, mais beaucoup de guides partent de l’idée qu’on ne peut pas.
• Les différences de sensibilité à la casse sont réelles. Les systèmes de fichiers Windows sont généralement insensibles à la casse ; Linux est sensible. Ça se manifeste par des diffs Git étranges, des builds cassés ou des fichiers dupliqués.

WSL2 + Docker : architecture et zones sensibles

Deux modèles supportés (choisissez-en un)

Modèle A : Docker Desktop + intégration WSL2. Docker Desktop possède le démon. Votre distro WSL obtient l’accès CLI Docker et peut exécuter des conteneurs, mais l’état « réel » de Docker vit dans l’environnement géré par Docker Desktop.

Modèle B : Docker Engine à l’intérieur d’une distribution WSL2. Votre distribution possède le démon et le stockage. C’est plus proche d’un serveur Linux. Idéal si vous voulez un comportement natif Linux et moins de surprises liées à une appli GUI.

La réalité du stockage : où la performance vit ou meurt

Le système de fichiers Linux WSL2 (votre ext4 à l’intérieur du VHDX) est rapide pour les outils Linux. Les fichiers montés depuis Windows sous /mnt/c sont plus lents et ont un surcoût de traduction des métadonnées. Les bind mounts Docker et les contextes de build amplifient ce surcoût.

Si vous exécutez des builds sur des chemins Windows et les montez dans des conteneurs Linux, vous demandez des problèmes de performance. Vous demandez peut‑être aussi des bizarreries pour les watchers de fichiers (particulièrement avec Node, Python ou tout outil qui utilise inotify).

Réseau : « localhost fonctionne » jusqu’à ce que ça ne fonctionne plus

WSL2 a sa propre interface réseau virtuelle. Windows et WSL2 coopèrent pour que « localhost » marche souvent dans les deux sens, mais le chemin n’est pas symétrique et n’est pas garanti avec les VPN, pare-feu ou DNS personnalisés.

Docker ajoute ses propres espaces de noms réseau et ponts à l’intérieur de l’environnement Linux. Les couches de traduction s’empilent, et chaque couche de traduction est un endroit supplémentaire où la latence, les problèmes MTU ou la résolution de noms peuvent échouer.

Blague n°1 : le NAT, c’est comme la hiérarchie intermédiaire — utile en théorie, mais parfois vos paquets ressortent de la réunion plus confus qu’en y entrant.

Règles non négociables pour que Docker ne casse pas

Règle 1 : Gardez le code source dans le système de fichiers Linux sauf raison forte

Par défaut : clonez dans ~/src à l’intérieur de WSL. Buildez là. Lancez Docker depuis là. Votre vie s’améliore.

Il existe des exceptions (flux IDE Windows-only, contraintes de scans d’endpoints d’entreprise), mais traitez les exceptions comme des demandes de changement en production : documentées, justifiées, réversibles.

Règle 2 : N’autorisez pas la dérive des données Docker entre frontières de propriété

Si vous utilisez Docker Desktop, laissez-le posséder le moteur et son stockage. N’exécutez pas en plus un dockerd séparé dans votre distro sauf si vous voulez intentionnellement deux démons (la plupart des gens non).

Règle 3 : Contrôlez les ressources WSL avec un .wslconfig

WSL sans limites peut affamer Windows. Ça ressemble à « Docker est lent », « VS Code est laggy » ou « mon ventilateur est maintenant mon principal dispositif d’entrée ». Mettez des limites, puis ajustez.

Règle 4 : Traitez les distros WSL comme du bétail, mais exportez avant chirurgie

WSL rend facile de supprimer et recréer une distro. C’est une fonctionnalité. Mais les images Docker, volumes et bases de données à l’intérieur de WSL sont de l’état. Exportez ou faites un snapshot avant de « réinstaller Ubuntu vite fait ».

Règle 5 : Ne déboguez jamais les performances sans mesurer la frontière du système de fichiers

Quand Docker semble lent, vous devez répondre : faisons-nous des E/S lentes sur /mnt/c, ou est-ce le CPU/mémoire/réseau ? Deviner est la façon de griller des après-midis.

Tâches pratiques (commandes, sorties, décisions)

Ce sont les commandes du quotidien qui gardent WSL2 + Docker ennuyeux. Chaque tâche inclut : commande, ce que la sortie signifie, et la décision à prendre ensuite.

Tâche 1 : Confirmer les versions WSL et la distro par défaut

cr0x@server:~$ wsl -l -v
  NAME                   STATE           VERSION
* Ubuntu-22.04           Running         2
  docker-desktop         Running         2
  docker-desktop-data    Running         2

Sens : Vous avez Ubuntu sur WSL2, plus les distros internes de Docker Desktop. C’est normal pour le Modèle A.

Décision : Si vous ne voulez pas Docker Desktop, vous ne devriez pas voir les distros docker-desktop. Si vous les voyez, vous êtes en Modèle A que vous l’admettiez ou non.

Tâche 2 : Vérifier la version du kernel WSL (sanity + contexte bugs)

cr0x@server:~$ wsl --status
Default Distribution: Ubuntu-22.04
Default Version: 2
WSL version: 2.1.5.0
Kernel version: 5.15.133.1-1
WSLg version: 1.0.59
MSRDC version: 1.2.4677
Direct3D version: 1.611.1-81528511
DXCore version: 10.0.26091.1-240325-1447.ge-release
Windows version: 10.0.22631.3085

Sens : WSL moderne avec un kernel basé sur 5.15. Beaucoup d’anciens problèmes réseau et systemd dépendent de la version du kernel/WSL.

Décision : Si vous êtes sur une version WSL beaucoup plus ancienne, mettez à jour d’abord avant de chasser des fantômes. Déboguer d’anciennes builds WSL, c’est payer des intérêts sur la dette technique.

Tâche 3 : Vérifier la propriété de Docker (Desktop vs in-distro)

cr0x@server:~$ docker context ls
NAME                DESCRIPTION                               DOCKER ENDPOINT                  ERROR
default *           Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
desktop-linux       Docker Desktop                            unix:///var/run/docker.sock

Sens : Des contexts existent ; dans WSL, les deux peuvent pointer vers un socket Unix selon l’intégration.

Décision : Choisissez un context et tenez-vous-y par workflow. Si les contexts changent sous vos pieds, c’est un problème de configuration, pas « Docker est instable ».

Tâche 4 : Vérifier si systemd est activé dans la distro WSL (prérequis Modèle B)

cr0x@server:~$ cat /etc/wsl.conf
[boot]
systemd=true

Sens : systemd est activé. Vous pouvez exécuter docker.service correctement à l’intérieur de WSL (Modèle B).

Décision : Si vous voulez le Modèle B et que ceci manque, ajoutez-le et redémarrez WSL. Si vous voulez le Modèle A (Docker Desktop), vous n’avez généralement pas besoin d’un dockerd dans la distro.

Tâche 5 : Redémarrer WSL proprement après des changements de config

cr0x@server:~$ wsl --shutdown
The operation completed successfully.

Sens : Toutes les VMs WSL se sont arrêtées. Le prochain lancement relira la config.

Décision : Faites ceci après avoir changé .wslconfig ou /etc/wsl.conf. Si vous ne le faites pas, vous déboguez une configuration que vous n’avez pas réellement appliquée.

Tâche 6 : Mesurer où se trouve votre repo (Linux vs montage Windows)

cr0x@server:~$ pwd
/home/cr0x/src/myapp

Sens : Le repo est dans le système de fichiers Linux. Bon pour les contextes de build Docker et les bind mounts.

Décision : Si vous êtes sous /mnt/c/..., attendez-vous à des E/S plus lentes. Déplacez le repo à moins d’avoir une contrainte stricte de le garder sur Windows.

Tâche 7 : Montrer rapidement la limite de performance (fio)

cr0x@server:~$ fio --name=randread --filename=/home/cr0x/fio.test --size=256M --bs=4k --rw=randread --iodepth=32 --numjobs=1 --runtime=10 --time_based --direct=1
randread: (g=0): rw=randread, bs=(R) 4096B-4096B, (W) 4096B-4096B, (T) 4096B-4096B, ioengine=psync, iodepth=32
fio-3.33
Starting 1 process
randread: Laying out IO file (1 file / 256MiB)
randread: (groupid=0, jobs=1): err= 0: pid=221: Fri Feb  2 10:01:16 2026
  read: IOPS=21.4k, BW=83.5MiB/s (87.6MB/s)(835MiB/10000msec)

Sens : Vous obtenez des IOPS de lecture aléatoire saines sur le système de fichiers Linux.

Décision : Lancez le même test sur /mnt/c. Si les IOPS s’effondrent, arrêtez de blâmer Docker et arrêtez de build sur des montages Windows.

Tâche 8 : Vérifier le driver de stockage Docker et le répertoire racine (où vivent réellement vos couches)

cr0x@server:~$ docker info --format 'RootDir={{.DockerRootDir}} Driver={{.Driver}} Cgroup={{.CgroupDriver}}'
RootDir=/var/lib/docker Driver=overlay2 Cgroup=systemd

Sens : Docker utilise overlay2 et stocke les données dans /var/lib/docker à l’intérieur de l’environnement Linux qui possède le démon.

Décision : Si vous voyez un RootDir inattendu ou un driver non prévu, vous n’exécutez pas le démon que vous pensez utiliser.

Tâche 9 : Trouver où le VHDX se situe sous Windows (planification capacité)

cr0x@server:~$ powershell.exe -NoProfile -Command "Get-ChildItem -Recurse $env:LOCALAPPDATA\Packages\*Ubuntu*\LocalState\ext4.vhdx | Select-Object FullName,Length"
FullName                                                             Length
--------                                                             ------
C:\Users\cr0x\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu22.04LTS_79rhkp1fndgsc\LocalState\ext4.vhdx  64424509440

Sens : Le disque virtuel de votre distro Ubuntu occupe 60 Gio sur C:. C’est là que vit votre système de fichiers Linux.

Décision : Si C: est petit ou protégé par des politiques d’entreprise, planifiez un déplacement contrôlé en utilisant export/import (tâches ultérieures). Déplacer des dossiers au hasard est la façon de créer des états WSL irrécupérables.

Tâche 10 : Vérifier l’usage du disque WSL depuis Linux (avant de « nettoyer »)

cr0x@server:~$ df -hT /
Filesystem     Type  Size  Used Avail Use% Mounted on
/dev/sdb       ext4   251G   96G  143G  41% /

Sens : Le système de fichiers root Linux a de l’espace. C’est à l’intérieur du VHDX.

Décision : Si le Use% est élevé, nettoyez d’abord à l’intérieur de Linux (docker prune, nettoyage des logs). N’assumez pas que Windows voit l’espace libéré ensuite.

Tâche 11 : Identifier les plus gros consommateurs d’espace de Docker (images/volumes)

cr0x@server:~$ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          24        6         18.3GB    12.7GB (69%)
Containers      11        2         1.4GB     1.1GB (78%)
Local Volumes   13        5         22.9GB    9.6GB (41%)
Build Cache     0         0         0B        0B

Sens : Les volumes sont les plus gros postes. Les images sont aussi récupérables.

Décision : Si vous devez libérer du disque, prunez d’abord images/containers, puis auditez les volumes soigneusement. Pruner les volumes à l’aveugle, c’est là que vous « effacez accidentellement » la base de quelqu’un.

Tâche 12 : Nettoyage « raisonnablement sûr » (prune avec intention)

cr0x@server:~$ docker image prune -a
WARNING! This will remove all images without at least one container associated to them.
Are you sure you want to continue? [y/N] y
Deleted Images:
deleted: sha256:3f1e2a0f7c8d...
Total reclaimed space: 9.8GB

Sens : Images inutilisées supprimées, ~10 Go récupérés dans le stockage Docker.

Décision : Si vos builds sont lents, le prune n’aidera pas. Si votre disque est plein, le prune aide. Problèmes différents, leviers différents.

Tâche 13 : Vérifier le risque de performance des bind mounts (montez-vous des chemins Windows?)

cr0x@server:~$ docker run --rm -v /mnt/c/Users/cr0x/src:/src alpine ls -la /src | head
total 64
drwxrwxrwx    1 root     root          4096 Feb  2 10:22 .
drwxr-xr-x    1 root     root          4096 Feb  2 10:22 ..
-rwxrwxrwx    1 root     root          1962 Feb  1 19:04 README.md
-rwxrwxrwx    1 root     root           372 Feb  1 19:04 docker-compose.yml

Sens : Vous montez un chemin Windows. Ça marche, mais c’est un piège de performance pour des charges I/O lourdes.

Décision : Si votre stack fait beaucoup de lectures de fichiers (Node, PHP, webpack, Python), déplacez le repo dans Linux et montez depuis /home à la place.

Tâche 14 : Confirmer la connectivité de ports depuis Windows vers des conteneurs WSL

cr0x@server:~$ docker run --rm -d -p 8080:80 nginx:alpine
c7c51d1c65b98a0c2a5c2b9d9a3a9b10f1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

cr0x@server:~$ powershell.exe -NoProfile -Command "Test-NetConnection -ComputerName 127.0.0.1 -Port 8080 | Select-Object TcpTestSucceeded"
TcpTestSucceeded
----------------
True

Sens : Le publication de port fonctionne et Windows peut y accéder sur localhost.

Décision : Si cela échoue sous VPN, le problème est généralement la résolution de noms, des règles de pare-feu, ou le comportement NAT de WSL — pas « nginx est cassé ».

Tâche 15 : Diagnostiquer le DNS dans WSL (le tueur silencieux de productivité)

cr0x@server:~$ cat /etc/resolv.conf
nameserver 172.22.48.1
search corp.example

cr0x@server:~$ getent hosts registry-1.docker.io | head -n 1
2600:1f18:2148:bc02:7fd3:1c63:6f57:fc3a registry-1.docker.io

Sens : WSL utilise un résolveur fourni par le NAT ; les recherches DNS fonctionnent.

Décision : Si les requêtes trainent ou retournent de mauvaises réponses sous VPN, vous devrez peut-être désactiver le resolv.conf auto-généré et définir un DNS explicitement (avec prudence — voir erreurs courantes).

Tâche 16 : Exporter une distro avant des changements risqués (votre bouton « annuler »)

cr0x@server:~$ wsl --export Ubuntu-22.04 D:\wsl-backups\Ubuntu-22.04.tar
The operation completed successfully.

Sens : Vous avez maintenant une sauvegarde hors ligne que vous pouvez importer ailleurs.

Décision : Faites ceci avant de déplacer des disques, réinstaller, ou « nettoyer WSL ». Si vous ne le faites pas, vous misez votre travail sur la chance.

Tâche 17 : Déplacer une distro sur un autre disque (la bonne méthode)

cr0x@server:~$ wsl --unregister Ubuntu-22.04
The operation completed successfully.

cr0x@server:~$ wsl --import Ubuntu-22.04 D:\wsl\Ubuntu-22.04 D:\wsl-backups\Ubuntu-22.04.tar --version 2
The operation completed successfully.

Sens : La distro est maintenant stockée sous D:\wsl\Ubuntu-22.04 (y compris son nouveau VHDX). C’est ainsi que vous déplacez le stockage WSL sans corruption.

Décision : Faites cela si C: est contraint ou si les politiques de chiffrement d’entreprise rendent les E/S WSL pénibles sur le disque système.

Tâche 18 : Vérifier que Docker pointe toujours là où vous pensez après un déplacement

cr0x@server:~$ wsl -d Ubuntu-22.04 -- bash -lc "docker ps"
CONTAINER ID   IMAGE           COMMAND                  CREATED       STATUS       PORTS                  NAMES
c7c51d1c65b9   nginx:alpine    "/docker-entrypoint.…"   2 min ago     Up 2 min     0.0.0.0:8080->80/tcp   nostalgic_borg

Sens : La CLI Docker peut toujours parler à un démon et l’état de vos conteneurs existe.

Décision : Si les conteneurs/images « disparaissent », vous avez changé de démon ou de contextes. Diagnostiquez d’abord la dérive du modèle de propriété, pas « Docker a mangé mes devoirs ».

Recette de diagnostic rapide

Voici l’ordre qui trouve rapidement le goulot d’étranglement, sans courir après le folklore.

1) Identifier le modèle de propriété en 30 secondes

• Vérifier : wsl -l -v pour les distros docker-desktop ; docker info pour RootDir et driver.
• Pourquoi : Si vous n’êtes pas sûr du démon auquel vous parlez, toute autre observation est suspecte.
• Décision : Engagez-vous sur le Modèle A ou B pour cette machine et équipe. « Les deux » est une taxe de débogage.

2) Mesurer la frontière du système de fichiers (Linux vs /mnt/c)

• Vérifier : Où se situe le repo (pwd), où pointent les bind mounts, et lancez un test fio rapide dans les deux emplacements.
• Pourquoi : La plupart des rapports « Docker sur WSL est lent » sont en fait « je fais des builds Linux sur un chemin monté Windows ».
• Décision : Si /mnt/c est le point chaud, déplacez le code dans le système de fichiers Linux et ajustez le workflow de l’éditeur.

3) Confirmer les limites de ressources (RAM/swap) et signaux de pression

• Vérifier : Usage mémoire WSL, comportement du swap, et si Windows utilise intensément la pagination.
• Pourquoi : Sous pression mémoire, tout semble être un problème d’E/S.
• Décision : Définissez des limites dans .wslconfig ; augmentez la mémoire pour les workloads lourd en build ; gardez le swap raisonnable.

4) Valider le DNS et le proxy (surtout sur VPN)

• Vérifier : getent hosts, pulls depuis les registries, et si /etc/resolv.conf est auto-généré.
• Pourquoi : Les étapes de build récupèrent souvent des dépendances ; un DNS cassé ressemble à « Docker build bloque ».
• Décision : Corrigez la génération du DNS ou définissez un DNS statique avec une politique contrôlée.

5) Ensuite seulement : performance spécifique Docker (buildkit, cache, overlay2)

• Vérifier : Logs de build, cache misses, motifs d’invalidation de couches, et si les bind mounts provoquent des reconstructions excessives.
• Pourquoi : Le tuning Docker est inutile si le système de fichiers sous-jacent est mauvais.
• Décision : Optimisez l’ordre des instructions Dockerfile, utilisez BuildKit, et réduisez le churn des bind mounts.

Erreurs courantes : symptôme → cause racine → correctif

1) « Docker est terriblement lent »

Symptôme : npm install, composer install, pip install, ou les builds webpack prennent 5–20× plus de temps que prévu.

Cause racine : Le repo vit sous /mnt/c et vous le montez dans des conteneurs ; les opérations sur les métadonnées sont coûteuses à travers la frontière Windows↔Linux.

Correctif : Déplacez le repo dans le système de fichiers Linux (/home/.../src). Si vous avez besoin d’accès IDE Windows, utilisez VS Code Remote / WSL ou accédez via \\wsl$\\ depuis Windows.

2) « Mes images/containeurs ont disparu après un reboot »

Symptôme : Les images d’hier ont disparu ; docker ps est vide ; les volumes ne sont pas là.

Cause racine : Vous parlez à un démon/context différent (Desktop vs in-distro), ou Docker Desktop a réinitialisé sa distro de données.

Correctif : Lancez docker context ls, puis docker info pour confirmer RootDir. Décidez Modèle A ou B et supprimez l’autre démon pour éviter la dérive.

3) « Le build Docker bloque sur ‘Downloading…’ »

Symptôme : Les builds stagnent en récupérant des images de base ou des dépendances ; réessayer fonctionne parfois.

Cause racine : Problèmes de résolution DNS sous VPN, ou variables proxy non appliquées dans l’environnement WSL/Docker.

Correctif : Testez la résolution de noms avec getent hosts. Si besoin, désactivez le resolv.conf auto-généré et définissez des résolveurs connus ; alignez les variables proxy pour WSL et Docker.

4) « Les ports publiés arrêtent aléatoirement de fonctionner »

Symptôme : -p 8080:80 fonctionnait avant ; maintenant Windows ne peut plus y accéder sur localhost.

Cause racine : Le NAT WSL et des changements de pare-feu après une mise en veille / toggles VPN ; parfois le switch virtuel WSL est dans un état mauvais.

Correctif : Redémarrez WSL (wsl --shutdown). Si vous utilisez Docker Desktop, redémarrez-le aussi. Retestez avec Test-NetConnection.

5) « Le disque est plein mais j’ai supprimé plein de trucs »

Symptôme : L’espace disque Windows n’augmente pas après la suppression d’images Docker ou de fichiers Linux.

Cause racine : Le VHDX ne se réduit pas automatiquement ; l’espace reste alloué dans le disque virtuel.

Correctif : Nettoyez à l’intérieur de Linux, puis compactez le VHDX avec des outils supportés. Si vous ne pouvez pas compacter facilement, export/import vers un nouveau VHDX est une réinitialisation pragmatique.

6) « Le file watching ne marche pas (hot reload cassé) »

Symptôme : L’application ne se recharge pas sur changements de fichiers ; les watchers manquent des événements ou font monter le CPU.

Cause racine : Surveiller un système de fichiers monté depuis Windows depuis des conteneurs Linux peut dégrader les sémantiques inotify ; ou trop de fichiers saturent les watchers.

Correctif : Gardez le code dans le système de fichiers Linux ; pour de grands monorepos, configurez le polling avec des intervalles raisonnables en dernier recours, mais considérez-le comme une solution de réserve.

7) « Git montre des renommages uniquement par casse ou des doublons »

Symptôme : Le CI passe sur Linux mais localement c’est étrange ; des fichiers diffèrent seulement par la casse.

Cause racine : Mismatch de sensibilité à la casse quand on travaille sur un système de fichiers Windows.

Correctif : Travaillez dans le système de fichiers Linux pour les repos qui supposent les sémantiques Linux ; imposez une nomenclature cohérente sur la casse dans le dépôt.

Trois mini-récits d’entreprise tirés du terrain

Incident : la mauvaise hypothèse (« WSL, c’est en gros juste un dossier »)

Une équipe produit a déployé WSL2 pour standardiser les environnements dev. Le mandat était raisonnable : Docker, outils Linux, builds cohérents. L’implémentation ne l’était pas. Quelqu’un a supposé que les distros WSL étaient juste des répertoires que l’on pouvait déplacer comme n’importe quel cache.

Un ingénieur a donc « économisé de l’espace » en copiant le répertoire LocalState de la distro WSL sur D: puis en supprimant l’original sur C:. Ça a marché un jour, en gros. Puis Docker Desktop s’est mis à jour, l’état enregistré par WSL ne correspondait plus au contenu du disque et la distro a refusé de démarrer. Le symptôme immédiat était « Docker ne démarre pas », mais l’échec réel était « le disque VM n’est plus où WSL pense qu’il est ».

La récupération a été douloureuse. Ils ont dû unregister et réimporter depuis la copie qui restait. Certaines personnes ont perdu des bases locales stockées dans des volumes parce que personne n’avait de politique d’export avant chirurgie.

La leçon n’était pas « ne pas utiliser WSL ». C’était : traitez les distros WSL comme des actifs VM gérés. Si vous voulez les placer sur un autre disque, utilisez export/import. Si vous voulez réduire l’espace, prunez et compacte, ne jouez pas à la roulette des systèmes de fichiers.

Optimisation qui a mal tourné : « Mettons tout sur /mnt/c pour que les outils Windows voient tout »

Une autre organisation voulait une expérience fluide pour les développeurs centrés Windows. Leur idée : garder les repos sur C:\ pour que les outils de sécurité et les IDE Windows « voient tout », puis lancer les builds dans WSL2 et les conteneurs en bind-montant les mêmes chemins Windows.

Sur les petits projets, ça avait l’air correct. Sur le monorepo principal, c’était un incident en slow-motion. Les builds incrémentiels n’étaient plus incrémentiels. Les étapes de scan de fichiers (linters, découverte de tests, compilation TypeScript) sont devenues le nouveau goulot. Les gens ont compensé en désactivant les vérifications localement — parce que les délais ne se soucient pas de votre diagramme d’architecture.

Puis le vrai retour de bâton : les builds Docker ont commencé à expirer dans des scripts locaux type CI. Pas parce que le CPU était faible, mais parce que la création du tar du contexte et les opérations overlay dépensaient leur temps dans la couche de traduction Windows↔Linux. Les développeurs appelaient ça « l’overhead Docker ». Ce n’était pas ça. C’était le placement du stockage.

Ils ont fini par basculer vers des emplacements natifs Linux pour les repos et ont utilisé des intégrations d’éditeur pour maintenir l’UX Windows. L’accélération a été immédiate et ennuyeuse, ce qui est le type de succès souhaitable en opérations.

Pratique ennuyeuse mais correcte qui a sauvé la mise : « Exporter avant les changements »

Une équipe plateforme maintenait une image WSL2 standard pour des développeurs travaillant sur plusieurs services containerisés. Ils avaient une règle : tout changement susceptible de toucher le stockage de la distro WSL nécessite un export d’abord. Pas d’exceptions, pas de « ça ira », pas d’héroïsme.

Un trimestre, une mise à jour Windows plus une mise à jour d’un agent de sécurité ont causé des stalls d’E/S disque sur C:. Les développeurs ont signalé des builds Docker qui mettaient une éternité, plus des timeouts WSL occasionnels. La solution a été de relocaliser les distros vers un disque où la politique de scan de l’agent était moins agressive. C’est le genre de phrase qui fait soupirer tout le monde, mais ça arrive.

Parce qu’ils avaient un export récent, le déplacement a été procédural : shutdown WSL, export, unregister, import à l’emplacement cible, vérification. Ils n’ont pas eu à déboguer des fichiers VHDX corrompus à 2h du matin. Ils n’ont pas non plus demandé à des centaines d’ingénieurs de reconstruire leurs environnements à partir de zéro.

Ce n’était pas glamour. C’était discipliné. Et ça a transformé une migration potentiellement chaotique en une opération de maintenance contrôlée.

Checklists / plan pas à pas

Étape 0 : Décidez votre modèle Docker (n’improvisez pas plus tard)

• Choisissez le Modèle A si vous voulez l’expérience bureau la plus simple, la gestion GUI, et que vous n’avez pas besoin du contrôle natif du démon Linux.
• Choisissez le Modèle B si vous voulez un comportement type serveur Linux, le contrôle explicite de /var/lib/docker, et moins de surprises Docker Desktop.

Étape 1 : Installer WSL2 proprement et vérifier

• Installez WSL et une distribution.
• Exécutez wsl -l -v et confirmez VERSION=2.
• Exécutez wsl --status et confirmez que vous êtes sur une version WSL moderne.

Étape 2 : Configurer les ressources WSL (les garde‑fous ennuyeux)

Créez ou éditez %UserProfile%\.wslconfig sur Windows. Exemple de politique (ajustez selon votre machine) :

• Mémoire : limitez à quelque chose de raisonnable (par ex., 8–16 GB sur un laptop de dev).
• Swap : ne le mettez pas à 0 à moins d’aimer les OOM pendant les builds.
• Processeurs : limitez si vous voulez que vos ventilateurs arrêtent de négocier des primes de risque.

Puis wsl --shutdown pour appliquer.

Étape 3 : Mettre le code au bon endroit

• Créez ~/src à l’intérieur de WSL.
• Clonez les repos là.
• Exécutez les builds Docker depuis là.

Étape 4 : Configuration Docker selon le modèle

Modèle A : Docker Desktop + intégration WSL2

• Activez le backend WSL2 dans les paramètres de Docker Desktop.
• Activez l’intégration pour la distro choisie.
• Confirmez que docker ps fonctionne dans la distro.
• N’installez pas et n’exécutez pas un dockerd séparé dans WSL sauf si vous voulez intentionnellement deux démons.

Modèle B : Docker Engine à l’intérieur de WSL2

• Activez systemd dans /etc/wsl.conf.
• Redémarrez WSL.
• Installez les paquets Docker Engine dans la distro.
• Démarrez et activez docker via systemd ; confirmez que docker info montre overlay2 et un répertoire racine sensé.

Étape 5 : Rendre la récupération d’incident ennuyeuse

• Avant des changements majeurs, exportez la distro : wsl --export.
• Pour relocaliser sur un disque : export → unregister → import.
• Gardez une politique sur ce qui peut vivre dans les volumes Docker localement (bases, caches) et comment les sauvegarder si nécessaire.

Blague n°2 : Si votre seul plan de sauvegarde est « je me souviendrai de ce que j’ai fait », félicitations — vous avez inventé un point unique de défaillance mémoire.

FAQ

1) Dois‑je utiliser Docker Desktop ou Docker Engine dans WSL ?

Si vous voulez le moins de friction sur Windows, utilisez Docker Desktop (Modèle A). Si vous voulez un contrôle natif Linux et un comportement de démon prévisible, exécutez Docker Engine dans WSL (Modèle B). Choisissez un modèle par machine.

2) Pourquoi construire depuis /mnt/c est‑il tellement plus lent ?

Parce que vous traversez une frontière de système de fichiers avec traduction des métadonnées. Les builds effectuent beaucoup d’opérations de petits fichiers. Les petites opérations sont là où les coûts de frontière apparaissent.

3) Où sont réellement stockées mes images Docker ?

Exécutez docker info et regardez DockerRootDir. Dans Docker Desktop, le stockage sous-jacent est dans son environnement géré ; dans Docker in-distro, c’est généralement /var/lib/docker à l’intérieur du VHDX de cette distro.

4) Puis‑je déplacer WSL vers un autre disque en toute sécurité ?

Oui : exportez la distro en tar, unregister, puis importez-la dans un répertoire sur le disque cible. Ne copiez pas manuellement le VHDX LocalState et n’espérez pas que ça marche.

5) Pourquoi l’espace disque Windows ne revient‑t‑il pas après suppression de fichiers dans WSL ?

Parce que le fichier VHDX ne se réduit pas automatiquement. Vous avez libéré de l’espace dans ext4, mais Windows voit toujours l’allocation VHDX. Utilisez des workflows de compactage ou export/import pour recréer un VHDX plus petit.

6) Comment savoir si « Docker est lent » est vraiment du DNS ?

Si les pulls/étapes de build bloquent sur des fetchs réseau, testez avec getent hosts et un simple pull d’image. Si la résolution est lente ou incorrecte, corrigez le DNS avant de toucher aux Dockerfiles.

7) Est‑il sûr d’exécuter deux démons Docker (Desktop + in-distro) ?

C’est faisable, mais généralement c’est une panne auto-infligée. Vous allez confondre contexts, ports et emplacements d’images. Si vous devez le faire, documentez les contexts et figez-les par projet.

8) Pourquoi parfois les ports ne fonctionnent que depuis Windows ou que depuis WSL ?

Parce que le NAT et les règles de forwarding diffèrent selon la direction. De plus, des changements VPN/pare‑feu peuvent rompre la colle implicite. Redémarrez WSL et Docker Desktop, puis retestez avec un conteneur connu et Test-NetConnection.

9) Quelle est la façon la plus sûre de gérer des bases de données dans des volumes Docker locaux ?

Considérez les volumes comme jetables à moins de les sauvegarder. Pour tout ce qui est important, script les exports (ex., pg_dump) vers un emplacement connu dans le système de fichiers Linux et/ou un chemin de sauvegarde Windows.

10) Activer systemd dans WSL est‑il important pour Docker ?

Pour le Modèle B, oui : systemd fait que Docker se comporte comme sur un vrai Linux, y compris le cycle de vie des services et l’alignement du driver cgroup. Pour le Modèle A, c’est optionnel.

Prochaines étapes (faites celles‑ci, pas des intentions)

1. Décidez votre modèle Docker et éliminez l’ambiguïté : intégration Desktop ou démon in-distro.
2. Déplacez les dépôts actifs dans le système de fichiers Linux et arrêtez de bind-monter des chemins Windows pour les builds lourds.
3. Ajoutez des limites de ressources WSL pour que Windows reste réactif sous charge.
4. Exportez votre distro avant les changements comme les déplacements de disque, réinstallations ou « nettoyage ».
5. Utilisez la recette de diagnostic rapide la prochaine fois que les performances chutent : propriété → frontière FS → ressources → DNS → tuning Docker.

Quand WSL2 et Docker sont configurés correctement, ils ne donnent pas l’impression d’être une « stack ». Ils donnent l’impression que votre machine coopère enfin. C’est l’objectif : ennuyeux, rapide, récupérable.