Docker on kenji.blog

Étapes pour construire un environnement de développement local reproductible avec Docker

Sun, 13 Sep 2026 01:00:00 +0900

1. Introduction : Sortir du « Ça marche sur ma machine »

Dans le développement logiciel, le problème du « Ça marche sur ma machine » (It works on my machine), dû aux différences d’environnements entre les développeurs, est depuis longtemps un facteur de perte de temps dans de nombreux projets. En raison des différences de systèmes d’exploitation, de versions de langages installées, des dépendances de bibliothèques, ou des conflits d’outils installés globalement, l’environnement local est toujours exposé à une « incertitude d’état ».

Ce qui résout fondamentalement ces défis, c’est la technologie des conteneurs, notamment Docker, et le paradigme d’Infrastructure as Code (IaC). Conteneuriser l’environnement de développement local permet une isolation au niveau du système d’exploitation et de versionner l’environnement lui-même avec la base de code.

Cet article explique en détail, avec des perspectives mathématiques, la méthode pour construire « un environnement de développement local reproductible qui reste exactement le même peu importe qui, quand, et sur quelle machine il est lancé », en tirant parti de Docker, Docker Compose, et VSCode DevContainers.

2. Affinité entre l’Infrastructure as Code (IaC) et la technologie des conteneurs

Principes de l’IaC et son application à l’environnement local

L’Infrastructure as Code (IaC) est une approche qui gère la configuration et le provisionnement de l’infrastructure via des fichiers de définition lisibles par machine, plutôt que par un processus manuel. Les principes fondamentaux de l’IaC incluent :

Approche déclarative (Declarative Approach) : On définit « quel devrait être l’état final » plutôt que « comment changer l’état ».
Idempotence (Idempotency) : Quel que soit le nombre d’exécutions du script, le même résultat (état) est toujours garanti.
Contrôle de version (Version Control) : L’état de l’infrastructure est stocké sous forme de code dans des systèmes comme Git, ce qui permet le suivi de l’historique et la revue par les pairs.

Pratiquer l’IaC dans un environnement de développement local signifie coder « l’état idéal » de l’environnement de développement à l’aide de Dockerfile, docker-compose.yml, et devcontainer.json. Cela permet aux nouveaux membres de l’équipe de commencer immédiatement le développement en clonant simplement le dépôt et en exécutant une seule commande, offrant ainsi une excellente expérience d’intégration (onboarding).

Fonctionnalités du noyau derrière la technologie des conteneurs

Contrairement à la virtualisation par hyperviseur comme les machines virtuelles (VM), la technologie des conteneurs est une technologie de virtualisation légère qui isole les processus tout en partageant le noyau du système d’exploitation hôte. Pour y parvenir, les fonctionnalités suivantes du noyau Linux sont principalement utilisées :

Namespaces : Fournissent une vue isolée des ressources système (PID, réseau, points de montage, utilisateurs, etc.) pour chaque processus.
Cgroups (Control Groups) : Limitent et allouent les ressources physiques (CPU, mémoire, E/S disque, etc.) qu’un processus peut utiliser.
UnionFS (Union File System) : Technologie permettant de superposer de manière transparente plusieurs arborescences de répertoires (couches) et de les présenter comme un système de fichiers unique. Les couches d’images Docker reposent sur cette technologie.

Considérons un modèle mathématique de limitation de ressources. Soit $M_{\text{total}}$ la capacité de mémoire totale de la machine hôte et $m_i$ la limite de mémoire pour $n$ conteneurs s’exécutant sur l’hôte. En tenant compte de la mémoire de base $M_{\text{os}}$ consommée par l’OS hôte et d’autres processus, la condition nécessaire au fonctionnement stable du système peut être exprimée par l’inégalité suivante :

$$ \sum_{i=1}^{n} m_i \le M_{\text{total}} - M_{\text{os}} $$

En définissant strictement $m_i$ pour chaque conteneur à l’aide de Cgroups, même si un conteneur spécifique présente une fuite de mémoire, l’OOM (Out Of Memory) Killer empêchera les autres conteneurs et l’ensemble du système hôte de tomber en panne.

3. Conception efficace de Dockerfile : Maîtriser les builds multi-étapes

La première étape vers un environnement reproductible est la conception du Dockerfile, qui définit l’environnement d’exécution de l’application. Ici, en utilisant Python (FastAPI) comme exemple, nous expliquons les meilleures pratiques pour des Dockerfiles sécurisés et légers utilisant des builds multi-étapes (multi-stage builds).

Le build multi-étapes est une technique qui utilise plusieurs instructions FROM dans un seul Dockerfile pour séparer l’environnement de construction (un environnement lourd avec compilateurs et outils de développement) de l’environnement d’exécution (un environnement léger avec seulement les artefacts nécessaires).

Dockerfile pratique pour Python FastAPI

Le code suivant est un exemple de Dockerfile avancé combinant la gestion des dépendances avec Poetry et les builds multi-étapes.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


# ---------------------------------------------------------
# Stage 1: Builder (Environnement de construction)
# ---------------------------------------------------------
FROM python:3.11-slim AS builder

# Configuration des variables d'environnement nécessaires
ENV PYTHONUNBUFFERED=1 \
 PYTHONDONTWRITEBYTECODE=1 \
 POETRY_VERSION=1.6.1 \
 POETRY_HOME="/opt/poetry" \
 POETRY_VIRTUALENVS_IN_PROJECT=true \
 POETRY_NO_INTERACTION=1

# Installation des paquets de dépendances
RUN apt-get update && apt-get install -y --no-install-recommends \
 curl build-essential && \
 curl -sSL https://install.python-poetry.org | python3 - && \
 apt-get clean && rm -rf /var/lib/apt/lists/*

ENV PATH="$POETRY_HOME/bin:$PATH"

WORKDIR /app

# Copie des fichiers de dépendances et installation
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-root --only main

# ---------------------------------------------------------
# Stage 2: Runtime (Environnement d'exécution)
# ---------------------------------------------------------
FROM python:3.11-slim AS runtime

ENV PYTHONUNBUFFERED=1 \
 PYTHONDONTWRITEBYTECODE=1 \
 PATH="/app/.venv/bin:$PATH"

# Création d'un utilisateur non privilégié minimal
RUN groupadd -r appuser && useradd -r -g appuser appuser

WORKDIR /app

# Copier uniquement l'environnement virtuel (dépendances) depuis le constructeur
COPY --from=builder --chown=appuser:appuser /app/.venv /app/.venv

# Copie du code de l'application
COPY --chown=appuser:appuser ./src /app/src

# Passer à l'utilisateur non privilégié
USER appuser

# Commande par défaut au lancement du conteneur
ENTRYPOINT ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

Évaluation mathématique de la taille de l’image grâce au build multi-étapes

Soit $S_{\text{single}}$ la taille de l’image avec un build à une étape, et $S_{\text{multi}}$ la taille avec un build multi-étapes. Le taux de réduction de taille $R$ est calculé comme suit :

$$ R = \left( 1 - \frac{S_{\text{multi}}}{S_{\text{single}}} \right) \times 100 \ (\%) $$

Par exemple, supposons que $S_{\text{single}}$ comprenne l’image de base de l’OS (environ 110 Mo), les paquets de développement (gcc etc., environ 150 Mo), Poetry lui-même (environ 40 Mo), les bibliothèques de dépendances du projet (environ 80 Mo) et le code source (environ 5 Mo), pour un total de 385 Mo. D’autre part, $S_{\text{multi}}$ ne copie que les bibliothèques (80 Mo) et le code source (5 Mo) dans l’image de base (110 Mo), ce qui donne un total de 195 Mo.

$$ R = \left( 1 - \frac{195}{385} \right) \times 100 \approx 49.35\% $$

Ainsi, en introduisant le build multi-étapes, la taille de l’image peut être réduite d’environ la moitié. La réduction de la taille de l’image est directement liée à des temps de téléchargement (pull) plus courts depuis le registre, des économies d’espace disque, et une sécurité améliorée grâce à la réduction de la surface d’attaque (Attack Surface).

4. Orchestration de plusieurs conteneurs avec Docker Compose

Dans le développement d’applications Web modernes, il est courant d’avoir une architecture de microservices où plusieurs composants tels qu’un serveur Web, une base de données, et un serveur de cache interagissent. Pour gérer cela de manière centralisée dans un environnement local, nous utilisons docker-compose.yml.

Cette fois, nous allons construire localement un système à 3 couches : « Web (FastAPI) », « Database (PostgreSQL) », et « Cache (Redis) ».

Diagramme d’architecture (Mermaid)

Le diagramme suivant illustre la relation entre les conteneurs, le réseau, et les volumes sur la machine locale.

graph TD
User["Machine Hôte (Navigateur/curl)"] -->|Localhost:8000| Web["Conteneur Web FastAPI"]
subgraph "Réseau Bridge Docker (app-network)"
Web -->|Port 5432| DB["Conteneur PostgreSQL"]
Web -->|Port 6379| Redis["Conteneur Redis"]
end
DB --> Volume1["Volume Nommé (postgres_data)"]
Redis --> Volume2["Volume Nommé (redis_data)"]
HostDir["Code Source Hôte (./src)"] -.->|Bind Mount| Web

Implémentation de docker-compose.yml et explications détaillées

Voici un exemple de docker-compose.yml robuste adapté à un environnement pratique.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


version: '3.8'

services:
 web:
 build:
 context: .
 target: runtime
 container_name: dev_web
 ports:
 - "8000:8000"
 volumes:
 - ./src:/app/src:ro  # Monter le code de l'hôte en lecture seule (pour le rechargement à chaud)
 environment:
 - DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
 - REDIS_URL=redis://redis:6379/0
 env_file:
 - .env
 depends_on:
 db:
 condition: service_healthy
 redis:
 condition: service_started
 networks:
 - app-network
 command: ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

 db:
 image: postgres:15-alpine
 container_name: dev_db
 ports:
 - "5432:5432"
 environment:
 POSTGRES_USER: postgres
 POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
 POSTGRES_DB: ${POSTGRES_DB}
 volumes:
 - postgres_data:/var/lib/postgresql/data
 networks:
 - app-network
 healthcheck:
 test: ["CMD-SHELL", "pg_isready -U postgres -d ${POSTGRES_DB}"]
 interval: 5s
 timeout: 5s
 retries: 5

 redis:
 image: redis:7-alpine
 container_name: dev_redis
 ports:
 - "6379:6379"
 volumes:
 - redis_data:/data
 networks:
 - app-network
 command: ["redis-server", "--appendonly", "yes"]

volumes:
 postgres_data:
 redis_data:

networks:
 app-network:
 driver: bridge

Volumes et persistance des données

En principe, les conteneurs sont « stateless » (sans état) et « éphémères » (à courte durée de vie). Lorsqu’un conteneur est détruit, ses données internes sont également perdues. Pour conserver les données de base de données ou le cache, un espace système de fichiers de la machine hôte doit être monté dans le conteneur.

Bind Mount (Montage lié) : Dans le service web ci-dessus, ./src:/app/src:ro y correspond. Il mappe directement un répertoire spécifique de l’hôte à l’intérieur du conteneur. Il est utilisé pour refléter immédiatement les modifications de code locales dans le conteneur (rechargement à chaud). Pour des raisons de sécurité, la meilleure pratique est d’ajouter l’option :ro (Read-Only) afin que le conteneur ne puisse pas modifier le code source de l’hôte.
Named Volume (Volume nommé) : C’est le cas de postgres_data ou redis_data. C’est une zone gérée en interne par Docker (comme /var/lib/docker/volumes/), qui a de meilleures performances d’E/S qu’un bind mount et qui absorbe les différences de systèmes de fichiers entre les OS. Il faut toujours l’utiliser pour la persistance de base de données.

Réseau (Networking) et découverte de services

Docker Compose crée par défaut un réseau pont (bridge) distinct pour chaque projet. Il s’agit du app-network ci-dessus. Les conteneurs appartenant au même réseau peuvent se résoudre (résolution DNS) via leur « nom de service » (par exemple : db, redis) plutôt que par leur adresse IP. Par exemple, le conteneur Web peut accéder à la base de données via l’URL postgresql://postgres:password@db:5432/mydb. Cela permet de changer de manière transparente de cible de connexion via des variables d’environnement entre les environnements locaux, de pré-production, et de production sans modifier le code de l’infrastructure.

Bilan de santé (Healthcheck) et ordre de démarrage

La directive depends_on contrôle l’ordre de démarrage des conteneurs, mais si l’on spécifie simplement depends_on, le conteneur Web démarrera dès que le conteneur DB sera « lancé ». En réalité, le processus d’initialisation de la DB (démarrage du processus PostgreSQL, préparation des tables) prend quelques secondes, et une connexion depuis le conteneur Web pendant ce temps résultera en une erreur. Pour éviter cela, nous définissons un healthcheck et spécifions condition: service_healthy, ce qui permet de s’assurer que la « DB est prête à accepter les requêtes de connexion » avant de démarrer le conteneur Web.

5. Gestion des variables d’environnement et sécurité (.env)

C’est un anti-pattern à éviter absolument que de coder en dur des informations sensibles telles que les mots de passe de bases de données ou les clés d’API dans docker-compose.yml. À la place, utilisez un fichier de variables d’environnement .env pour injecter ces valeurs.

Créez un fichier .env à la racine du projet.

1
2
3
4


# Fichier .env (Assurez-vous de l'ajouter à .gitignore pour l'exclure de Git)
POSTGRES_PASSWORD=supersecretpassword
POSTGRES_DB=devdb
API_SECRET_KEY=dev_secret_key_12345

Docker Compose charge par défaut le fichier .env dans le répertoire d’exécution et développe les espaces réservés ${VAR_NAME} dans les fichiers YAML. Cette méthode permet de gérer en toute sécurité différentes valeurs de configuration pour des environnements tels que le local, la pré-production, et la production, sans modifier le code de l’infrastructure.

6. L’expérience de développement ultime avec VSCode DevContainers

À ce stade, nous avons construit un environnement backend robuste à l’aide de Docker. Cependant, nous pouvons aller encore plus loin. En utilisant la fonctionnalité VSCode DevContainers (Remote - Containers), il est possible d’exécuter le backend de l’éditeur (VSCode) lui-même à l’intérieur du conteneur.

Cela élimine le besoin d’installer Python ou Node.js sur la machine locale. Les linters (flake8/eslint), les formateurs (black/prettier) et même les extensions de l’IDE, tout peut être défini dans la base de code et partagé avec tous les membres de l’équipe.

Configuration de devcontainer.json

Créez un répertoire .devcontainer à la racine du projet, et placez-y le fichier de configuration.

.devcontainer/devcontainer.json :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


{
 "name": "Python FastAPI Dev Environment",
 "dockerComposeFile": ["../docker-compose.yml"],
 "service": "web",
 "workspaceFolder": "/app",
 "customizations": {
 "vscode": {
 "settings": {
 "python.defaultInterpreterPath": "/app/.venv/bin/python",
 "python.formatting.provider": "black",
 "editor.formatOnSave": true
 },
 "extensions": [
 "ms-python.python",
 "ms-python.vscode-pylance",
 "ms-python.black-formatter",
 "tamasfe.even-better-toml"
 ]
 }
 },
 "forwardPorts": [8000, 5432, 6379],
 "remoteUser": "appuser",
 "postCreateCommand": "poetry install"
}

En incluant ce fichier dans le dépôt, dès l’ouverture du projet dans VSCode, une invite « Reopen in Container » (Rouvrir dans le conteneur) apparaît. D’un simple clic, tous les conteneurs nécessaires démarrent, les extensions sont installées, et vous êtes immédiatement prêt à coder. C’est une expérience véritablement magique.

7. Séquence de traitement des requêtes et modélisation des performances

Examinons le cycle de vie du traitement d’une requête d’application Web dans l’environnement de développement local à l’aide d’un diagramme de séquence, puis analysons le modèle mathématique de ses performances.

Diagramme de séquence (Flux de requête)

sequenceDiagram
participant Client as "Navigateur / VSCode"
participant Web as "FastAPI (Web)"
participant Redis as "Cache Redis"
participant DB as "PostgreSQL"
Client->>Web: "GET /api/users/123"
activate Web
Web->>Redis: "Vérifier le cache pour user:123"
activate Redis
alt "Succès du cache (Données présentes)"
Redis-->>Web: "Retourner les données utilisateur en cache"
Web-->>Client: "200 OK (Réponse rapide)"
else "Échec du cache (Aucune donnée)"
Redis-->>Web: "Nul (Non trouvé)"
deactivate Redis
Web->>DB: "SELECT * FROM users WHERE id = 123"
activate DB
DB-->>Web: "Retourner la ligne de la base de données"
deactivate DB
Web->>Redis: "Définir les données user:123 (TTL: 60s)"
activate Redis
Redis-->>Web: "OK"
deactivate Redis
Web-->>Client: "200 OK (Réponse standard)"
end
deactivate Web

Modèle mathématique de la latence de traitement

Nous modélisons mathématiquement le temps de traitement moyen des requêtes $T_{\text{total}}$ dans le système ci-dessus. La latence de chaque processus est définie comme suit :

$T_{\text{net}}$ : Latence réseau entre le client et le conteneur Web
$T_{\text{app}}$ : Temps de traitement pur côté application (sérialisation, etc.)
$T_{\text{cache}}$ : Temps requis pour la lecture/écriture depuis Redis
$T_{\text{db}}$ : Temps requis pour l’exécution des requêtes vers PostgreSQL
$p_{\text{miss}}$ : Taux d’échec du cache ($0 \le p_{\text{miss}} \le 1$)

Le temps de réponse moyen est exprimé par l’équation d’espérance mathématique suivante :

$$ T_{\text{total}} = T_{\text{net}} + T_{\text{app}} + T_{\text{cache}} + p_{\text{miss}} \times (T_{\text{db}} + T_{\text{cache\_write}}) $$

Dans l’environnement de développement local (dans Docker), $T_{\text{net}}$ est proche de 0, mais ce qui requiert notre attention, ce sont les performances d’E/S du bind mount. En particulier, lors de l’utilisation de Docker Desktop sous Windows/macOS, la surcharge de partage de fichiers entre l’OS hôte et la VM (conteneur) a tendance à gonfler $T_{\text{app}}$ (comme les temps de lecture du code). Pour résoudre ce goulot d’étranglement, il est fortement recommandé d’utiliser DevContainers pour placer l’intégralité du code source dans un volume nommé, ou d’adopter une architecture exécutant le moteur Docker de manière native dans l’environnement WSL2 (Windows Subsystem for Linux 2).

8. Optimisation des performances de build Docker : Stratégie de mise en cache des couches

Lorsque vous rédigez un Dockerfile, comprendre le mécanisme de « cache de couche » (layer cache) peut considérablement modifier le temps de build. Docker crée un delta du système de fichiers (une couche) pour chaque instruction du Dockerfile (FROM, RUN, COPY, etc.) et la conserve comme cache. Lors d’une nouvelle construction, le cache des couches inchangées est réutilisé.

Le principe clé est de « décrire dans l’ordre de la fréquence de modification la plus faible ».

Considérons la modélisation de l’impact des modifications du code source sur le temps de build. Soit $T_{\text{build}}$ le temps de build total, $T_{\text{layer}_i}$ le temps d’exécution de chaque étape, et $c_i \in \{0, 1\}$ la valeur booléenne indiquant si le cache a été utilisé (1 en cas de succès du cache).

$$ T_{\text{build}} = T_{\text{init}} + \sum_{i=1}^{n} (1 - c_i) \times T_{\text{layer}_i} $$

Une fois qu’un échec de cache survient à la couche $k$ ($c_k = 0$), le cache est invalidé pour toutes les couches suivantes $j > k$ ($c_j = 0$).

1
2
3
4


# Mauvais exemple (Copie du code source en premier)
COPY ./src /app/src
COPY pyproject.toml poetry.lock ./
RUN poetry install

Dans ce cas, modifier une seule ligne de code invalidera le cache dès le premier COPY, ce qui entraînera l’exécution longue de RUN poetry install à chaque fois.

1
2
3
4


# Bon exemple (Résolution des dépendances en premier)
COPY pyproject.toml poetry.lock ./
RUN poetry install
COPY ./src /app/src

En écrivant ainsi, même si le code source change, le cache de la couche poetry install ($c_i = 1$) est effectif, réduisant considérablement le temps de build, passant de plusieurs minutes à quelques secondes.

9. Dépannage et conseils

Voici des problèmes fréquents rencontrés lors de l’utilisation d’un environnement local et leurs solutions.

Erreur de conflit de port Si vous obtenez une erreur telle que Bind for 0.0.0.0:8000 failed: port is already allocated, c’est qu’un autre processus sur la machine locale utilise ce port. Vous pouvez éviter cela en changeant le numéro de port côté hôte, comme ports: - "8080:8000".
Épuisement de l’espace disque L’utilisation de Docker sur une longue période peut accumuler des images et volumes inutilisés (Dangling Images / Volumes), occupant parfois des dizaines de Go d’espace disque. Il est recommandé de nettoyer périodiquement le système avec la commande suivante :
1

docker system prune -a --volumes
Problème de permissions de fichiers Lors de l’utilisation de bind mounts sous Linux, le propriétaire des fichiers créés dans le conteneur peut devenir root, les rendant non modifiables côté hôte. Vous pouvez résoudre cela en créant un utilisateur non privilégié dans le Dockerfile dont l’UID/GID (par ex. 1000:1000) correspond à celui de votre système d’exploitation hôte.

10. Conclusion : L’amélioration de la vitesse de développement grâce à la reproductibilité

La combinaison de Docker, Docker Compose et VSCode DevContainers permet de créer un environnement de développement local robuste, de sorte que « peu importe qui lance l’environnement, l’état sera exactement le même ».

Apporter le paradigme de l’IaC à l’environnement local ne se limite pas à raccourcir le temps de configuration initial. Il élimine les craintes liées aux modifications de la configuration de l’infrastructure, facilite l’expérimentation de nouvelles piles technologiques et permet une transition en douceur vers les pipelines CI/CD, améliorant considérablement la vitesse et la qualité globales du cycle de développement.

N’hésitez pas à introduire les meilleures pratiques abordées dans cet article, telles que l’optimisation de la taille de l’image via le build multi-étapes, le contrôle des dépendances avec les bilans de santé, et l’écriture de Dockerfile tenant compte du cache des couches, afin d’offrir la meilleure expérience de développement (DX: Developer Experience) à vos propres projets.

Le guide ultime de configuration de l'environnement de développement pour WSL2 (Windows Subsystem for Linux)

Sat, 12 Sep 2026 23:00:00 +0900

WSL2 (Windows Subsystem for Linux 2), qui offre un environnement de développement Linux natif sur Windows, est devenu un outil indispensable dans le développement de logiciels moderne. Cependant, il y a un monde de différence en termes de performances et d’expérience de développement entre l’utiliser dans son état par défaut et le régler de manière appropriée en comprenant son architecture.

Dans cet article, nous expliquerons de manière exhaustive, avec plus de 10 000 caractères, toutes les étapes pour construire l’« environnement de développement ultime » exigé par les ingénieurs professionnels, en commençant par l’explication de l’architecture fondamentale de WSL2, les paramètres pour maximiser les performances, la construction d’un environnement de terminal confortable, l’intégration transparente avec Docker et VS Code, et enfin les paramètres réseau avancés.

1. Architecture de WSL2 et évolution par rapport à WSL1

Afin de libérer tout le potentiel de WSL2, il est d’abord important de comprendre sa structure interne. L’approche pour exécuter des binaires Linux sur Windows est fondamentalement différente entre le premier WSL (WSL1) et WSL2.

WSL1 : Couche de traduction des appels système

WSL1 a adopté un mécanisme qui traduisait les appels système Linux en API Windows NT en temps réel. Cela avait l’avantage d’une surcharge de ressources très faible, car aucune machine virtuelle (VM) n’était utilisée. Cependant, il était difficile d’émuler complètement les appels système complexes, tels que les opérations d’E/S du système de fichiers, ce qui entraînait des baisses de performances désespérantes, notamment dans les processus traitant un grand nombre de petits fichiers, comme npm install de Node.js ou les opérations sur les dépôts Git.

WSL2 : VM utilitaire légère et noyau Linux complet

Dans WSL2, l’architecture a été remaniée pour qu’un véritable noyau Linux, construit par Microsoft, s’exécute directement sur une « VM utilitaire légère » qui utilise un sous-ensemble de l’architecture Hyper-V. Cela garantit une compatibilité à 100 % des appels système, et en utilisant un disque virtuel (VHDX) avec un système de fichiers natif Linux ext4, les performances d’E/S des fichiers ont été considérablement améliorées par rapport à WSL1.

Le diagramme Mermaid suivant illustre la différence structurelle entre WSL1 et WSL2.

flowchart TD
subgraph "Environnement du système d'exploitation Windows"
A["Noyau Windows NT"]
A --> F["Système de fichiers NTFS (Lecteur C:)"]
end
subgraph "Architecture WSL2"
B["Hyperviseur Hyper-V"]
B --> C["VM utilitaire légère"]
C --> D["Noyau Linux (Microsoft)"]
D --> E["Espace utilisateur Ubuntu (glibc, bash, etc.)"]
D --> G["Disque virtuel ext4 (.vhdx)"]
end
A -.->|"Partage de fichiers réseau par le protocole Plan 9 (9P)"| D
style B fill:#f9f,stroke:#333,stroke-width:2px
style D fill:#bbf,stroke:#333,stroke-width:2px

La leçon importante à tirer de cette structure est que « l’accès aux fichiers côté Linux (dans le VHDX) est extrêmement rapide, mais l’accès aux fichiers côté Windows (/mnt/c/) est très lent car il passe par le protocole 9P ». Le code source de vos projets doit toujours être placé dans le répertoire personnel côté WSL (~).

2. Analyse mathématique des performances : Pourquoi WSL2 est-il rapide ?

Évaluons quantitativement l’amélioration des performances de WSL2 à l’aide d’un modèle mathématique. L’une des opérations les plus chronophages dans le développement de logiciels est le traitement impliquant des E/S pour un grand nombre de fichiers (ex. : installation de bibliothèques ou compilation).

Le temps d’exécution global $T_{total}$ d’un traitement est exprimé par la somme du temps de calcul par le processeur $T_{compute}$ et du temps consacré aux E/S disque $T_{io}$.

$$ T_{total} = T_{compute} + T_{io} $$

Dans le cas de WSL1, une surcharge se produit lors de la conversion des opérations côté Linux en opérations NTFS, le temps d’E/S est donc modélisé comme suit. Ici, $n$ est le nombre d’opérations sur les fichiers, $t_{ntfs\_syscall}$ est le temps d’exécution de l’appel système côté Windows, et $t_{trans}$ est la surcharge de la couche de traduction.

$$ T_{wsl1\_io} = \sum_{i=1}^{n} (t_{ntfs\_syscall_i} + t_{trans_i}) $$

D’autre part, dans le cas de WSL2, le noyau émet directement des E/S vers le système de fichiers ext4, de sorte que la surcharge n’est qu’un très léger retard $t_{virt}$ dû à la virtualisation.

$$ T_{wsl2\_io} = \sum_{i=1}^{n} (t_{ext4_i} + t_{virt_i}) $$

Dans un système de fichiers classique, comme $t_{ext4} \ll t_{ntfs\_syscall} + t_{trans}$, lorsque $n$ est très grand (des dizaines à des centaines de milliers d’opérations sur les fichiers), la différence de temps d’E/S entre WSL1 et WSL2 augmente de manière exponentielle.

De plus, si le taux de surcharge des calculs du processeur dans un environnement virtualisé est $\rho$, avec la dernière virtualisation assistée par matériel (Intel VT-x / AMD-V), il se situe autour de $\rho \approx 0.01 \sim 0.03$ (1 à 3 %). Par conséquent, même dans des tâches purement de calcul, des performances comparables à un environnement Linux natif de $97\% \sim 99\%$ sont atteintes.

3. Installation et construction des bases

Sur Windows 10/11, l’installation de WSL2 est devenue très simple. Il suffit d’ouvrir PowerShell avec les privilèges d’administrateur et d’exécuter la commande suivante.

1
2
3
4
5
6


# WSL2 et Ubuntu sont installés par défaut
wsl --install

# Pour spécifier une distribution particulière
# Peut être vérifié avec wsl --list --online
wsl --install -d Ubuntu-24.04

Après l’installation et un redémarrage, il vous sera demandé de configurer un nom d’utilisateur et un mot de passe UNIX lors du premier lancement. Cet utilisateur est indépendant de l’utilisateur Windows et n’est valide qu’au sein de WSL.

Si vous utilisez déjà WSL1, vous pouvez le convertir en WSL2 avec les commandes suivantes.

1
2
3
4
5


# Convertir une distribution existante en WSL2
wsl --set-version Ubuntu 2

# Définir WSL2 comme version par défaut pour les distributions ajoutées à l'avenir
wsl --set-default-version 2

4. Les secrets du contrôle des ressources : .wslconfig et wsl.conf

L’un des plus grands pièges de WSL2 est la « consommation illimitée de mémoire (gonflement du processus Vmmem) ». Comme WSL2 utilise le cache de page du noyau Linux, chaque opération d’E/S consomme de la mémoire de l’hôte (Windows) de manière infinie. Pour éviter cela, il est impératif de limiter les ressources via des fichiers de configuration.

Les fichiers de configuration de WSL2 sont divisés en deux : .wslconfig qui affecte l’ensemble de Windows et wsl.conf qui affecte l’intérieur de chaque distribution.

4.1. .wslconfig (Côté Windows)

Créez un fichier dans le répertoire de profil utilisateur de Windows (C:\Users\<Nom_d_utilisateur>\.wslconfig) pour contrôler l’allocation des ressources à la VM.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# C:\Users\<Nom_d_utilisateur>\.wslconfig
[wsl2]
# Quantité maximale de mémoire allouée à la VM. Il est recommandé d'utiliser environ 50 % à 75 % de la mémoire totale de l'hôte
memory=16GB

# Nombre de cœurs de processeur à utiliser (tous les cœurs sont utilisés si omis)
processors=8

# Taille du fichier d'échange (swap)
swap=8GB

# Emplacement du fichier d'échange (si vous souhaitez économiser de l'espace sur le lecteur C)
# swapfile=D:\\wsl\\swap.vhdx

# Activer le transfert localhost (pour accéder à WSL depuis Windows via localhost)
localhostForwarding=true

# Libérer automatiquement la mémoire (Windows 11 uniquement)
# Libère dynamiquement le cache de page et empêche le gonflement de Vmmem
autoMemoryReclaim=dropcache

[experimental]
# Fonctionnalités réseau avancées disponibles dans Windows 11 22H2 et versions ultérieures
# Cela permet la prise en charge d'IPv6 et le partage de la même adresse IP entre WSL et Windows
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

4.2. wsl.conf (Côté Linux)

Modifiez /etc/wsl.conf à l’intérieur de WSL pour contrôler le comportement spécifique de la distribution.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# /etc/wsl.conf (Modifié à l'intérieur de WSL)
[network]
# Désactiver la génération automatique de /etc/resolv.conf au démarrage de WSL
# Utile si vous souhaitez configurer un DNS personnalisé (ex. : 8.8.8.8)
generateResolvConf=false

# Définir un nom d'hôte personnalisé
hostname=WSL-DevNode

[automount]
# Paramètres lors du montage de lecteurs Windows
enabled=true
options="metadata,uid=1000,gid=1000,umask=022"
# Changer le point de montage du lecteur C de /mnt/c à /c (pour raccourcir le chemin)
root=/

[boot]
# Activer systemd (WSL 0.67.6 et versions ultérieures)
# Cela permet à snap et à divers démons (tels que Docker) de fonctionner nativement
systemd=true

[user]
# Utilisateur connecté par défaut
default=kenji

Pour appliquer ces paramètres, vous devez exécuter wsl --shutdown dans PowerShell pour arrêter complètement la VM WSL avant de redémarrer.

5. L’environnement de terminal ultime : Zsh + Powerlevel10k

Rester avec le bash par défaut n’augmentera pas votre productivité. En combinant Zsh, qui se vante de puissantes capacités de complétion et de visibilité, avec le thème ultra-rapide « Powerlevel10k », nous allons construire l’invite de commande (prompt) la plus puissante.

5.1. Installation et configuration de Windows Terminal

Installez « Windows Terminal » à partir du Microsoft Store. Ouvrez la configuration JSON (settings.json), définissez le profil par défaut sur WSL (Ubuntu) et changez la police pour une Nerd Font orientée développement (par ex., HackGen Console NF ou MesloLGS NF).

5.2. Installation de Zsh et Oh My Zsh

Exécutez les commandes suivantes dans le terminal WSL.

1
2
3
4
5
6


# Mise à jour des paquets et installation de Zsh
sudo apt update && sudo apt upgrade -y
sudo apt install -y zsh git curl

# Exécuter le script d'installation de Oh My Zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

5.3. Introduction de Powerlevel10k et des plugins

Nous allons introduire des plugins pour améliorer encore Zsh (coloration syntaxique et auto-complétion) ainsi que le thème Powerlevel10k.

1
2
3
4
5
6
7
8


# Powerlevel10k
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

# zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

# zsh-syntax-highlighting
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

Modifiez ~/.zshrc pour activer le thème et les plugins.

1
2
3
4
5


# Changements dans ~/.zshrc
ZSH_THEME="powerlevel10k/powerlevel10k"

# Ajouter au tableau des plugins
plugins=(git zsh-autosuggestions zsh-syntax-highlighting)

Enregistrez et exécutez source ~/.zshrc, l’assistant de configuration de Powerlevel10k (p10k configure) se lancera. Suivez les instructions à l’écran pour personnaliser l’invite selon vos préférences (style de l’invite, présence d’icônes, informations à afficher, etc.). Le nom de la branche Git et son statut, la version de Node.js, le temps d’exécution des commandes, etc. seront affichés en temps réel, ce qui améliorera considérablement l’efficacité du développement.

6. Intégration transparente de VS Code Remote - WSL

Pour le développement dans WSL2, l’extension « Remote - WSL » est le mécanisme qui permet d’accéder de manière transparente aux fichiers dans WSL depuis l’IDE (Visual Studio Code) installé côté Windows.

Explication de l’architecture

Le diagramme de séquence suivant montre comment VS Code communique avec WSL2.

sequenceDiagram
autonumber
participant U as "Développeur"
participant V as "Interface utilisateur de VS Code (Windows)"
participant S as "Serveur VS Code (WSL2)"
participant F as "Système de fichiers ext4 (WSL2)"
U->>V: "Tapez `code .` dans le terminal WSL"
V->>S: "Établir une connexion RPC via Vsock"
Note over V,S: Communication via les sockets Hyper-V sans utiliser TCP/IP
S->>F: "Lire les fichiers sources / Exécuter le Linter"
F-->>S: "Retourner les données et l'analyse"
S-->>V: "Diffuser les résultats du serveur de langage vers l'UI"
V-->>U: "Afficher la coloration syntaxique et les erreurs"

Le VS Code côté Windows fonctionne comme un simple « client léger (UI) », et tous les traitements lourds tels que le Language Server, le débogueur et l’exécution du terminal sont gérés par le « VS Code Server » côté WSL. Cela vous permet de garder votre environnement propre uniquement du côté WSL, sans avoir à installer Node.js ou Python du côté Windows.

Paramètres essentiels de VS Code

Installez “WSL” (ms-vscode-remote.remote-wsl) depuis les « Extensions » de VS Code. Ensuite, allez simplement dans le répertoire de votre projet dans le terminal WSL et exécutez code ., VS Code se lancera côté Windows avec ce répertoire ouvert.

Point important (problème des codes de fin de ligne) : Les codes de fin de ligne diffèrent entre Windows et Linux (Windows utilise CRLF, Linux utilise LF). Lors d’un développement sur WSL, assurez-vous d’unifier le paramètre core.autocrlf de Git et les paramètres de fichier par défaut de VS Code à LF. Si vous négligez cela, vous rencontrerez des erreurs mystérieuses lors de l’exécution de scripts shell ou de conteneurs Docker.

1
2


# Configuration du code de fin de ligne de Git côté WSL
git config --global core.autocrlf input

Ajoutez également ce qui suit dans le fichier settings.json de VS Code (Paramètres distants).

1
2
3
4


{
 "files.eol": "\n",
 "terminal.integrated.defaultProfile.linux": "zsh"
}

7. Optimisation de Docker Desktop et de l’intégration WSL2

Pour utiliser Docker dans un environnement WSL2, il existe principalement deux approches.

Installer Docker Desktop pour Windows et activer la fonctionnalité d’intégration WSL2
Installer nativement le moteur Docker directement à l’intérieur de WSL2 (ex. : Ubuntu)

Approche 1 : Docker Desktop (Recommandé)

Dans la plupart des cas, cela est recommandé car la gestion via l’interface graphique et l’accès transparent aux conteneurs entre Windows/WSL sont faciles. Vérifiez les points suivants depuis les paramètres de Docker Desktop (Settings).

Cochez General -> Use the WSL 2 based engine.
Cochez Resources -> WSL Integration -> Enable integration with my default WSL distro et activez la distribution à utiliser (Ubuntu) avec le bouton à bascule.

Cela vous permet d’exécuter la commande docker directement depuis le terminal WSL2, et la communication avec le démon Docker s’effectue via des machines virtuelles légères dédiées (docker-desktop et docker-desktop-data) gérées par Docker Desktop.

Approche 2 : Installation directe du moteur Docker natif

Si vous avez des contraintes de réseau d’entreprise (comme éviter la monétisation de Docker Desktop) ou si vous souhaitez réduire au maximum la surcharge de performances, installez Docker en tant que pur serveur Ubuntu après avoir activé systemd dans /etc/wsl.conf.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# Extrait des instructions officielles d'installation de Docker sur WSL2 Ubuntu avec systemd activé
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Ajout du dépôt
echo \
 "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
 "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
 sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Ajouter l'utilisateur actuel au groupe docker (pour exécuter sans sudo)
sudo usermod -aG docker $USER

Après le redémarrage, systemctl start docker fonctionnera exactement comme dans un environnement Linux natif et offrira des performances élevées.

8. Intégration des clés SSH : Authentification transparente entre Windows et WSL

Lors de la réalisation de clones SSH Git ou de la connexion SSH à des serveurs distants, gérer des clés SSH séparées côté Windows et côté WSL est très fastidieux. Pour allier sécurité et commodité, nous allons configurer un pont pour transférer l’agent SSH en cours d’exécution côté Windows (ou un gestionnaire de mots de passe comme 1Password) vers le côté WSL.

Ici, nous expliquerons l’approche la plus sécurisée et moderne consistant à utiliser la fonctionnalité d’agent SSH de 1Password ou l’OpenSSH Authentication Agent de Windows, et à la transférer vers un socket de domaine UNIX de WSL2 en utilisant npiperelay et socat.

Transfert de socket ssh-agent

Habituellement, l’agent SSH, qui est fourni en tant que Named Pipe (tube nommé) sous Windows, doit être converti en un fichier socket côté WSL. Il est facile d’utiliser des fonctionnalités fournies par wsl-ssh-agent ou 1Password.

Depuis l’écran des paramètres de 1Password, activez « Developer » -> « Use the SSH agent » (Utiliser l’agent SSH). Ensuite, ajoutez la configuration suivante dans le fichier ~/.zshrc ou ~/.bashrc côté WSL pour lier automatiquement le socket lors de la connexion.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Ajout dans ~/.zshrc (exemple lors de l'utilisation de 1Password SSH Agent)
export SSH_AUTH_SOCK=$HOME/.ssh/agent.sock
# Transférer avec socat et npiperelay si le socket n'existe pas ou si le processus n'est pas lié au démarrage de WSL
ALREADY_RUNNING=$(ps -aux | grep "[n]piperelay.exe -ei -s //./pipe/openssh-ssh-agent" | wc -l)
if [ $ALREADY_RUNNING -eq 0 ]; then
 if [ -S $SSH_AUTH_SOCK ]; then
 rm $SSH_AUTH_SOCK
 fi
 # Démarrer socat en arrière-plan et connecter le Named Pipe côté Windows au socket UNIX côté WSL
 (setsid socat UNIX-LISTEN:$SSH_AUTH_SOCK,fork EXEC:"npiperelay.exe -ei -s //./pipe/openssh-ssh-agent",nofork &) >/dev/null 2>&1
fi

L’installation de npiperelay.exe et l’ajout à la variable d’environnement PATH côté Windows sont nécessaires au préalable.

Une fois cette configuration terminée, lors de l’exécution de ssh-add -l depuis le terminal WSL, la liste des clés publiques des clés SSH enregistrées dans 1Password ou côté Windows s’affichera. Cela vous permet de passer l’authentification en toute sécurité sans avoir à copier les fichiers de clé privée dans WSL.

9. Maintenance : Optimisation (compression) d’un VHDX gonflé

L’un des plus grands inconvénients de WSL2 est sa spécification selon laquelle « la taille du fichier du disque virtuel côté Windows (.vhdx) ne rétrécit pas automatiquement, même si vous supprimez des images Docker ou des fichiers ». Si vous continuez à développer pendant une longue période, le fichier ext4.vhdx va gonfler jusqu’à des dizaines ou des centaines de gigaoctets.

Pour libérer de l’espace disque, vous devez optimiser (Compacter) régulièrement le VHDX depuis le côté Windows.

Tout d’abord, arrêtez complètement WSL.
1

wsl --shutdown
Ouvrez PowerShell avec des privilèges d’administrateur et exécutez la commande diskpart suivante, ou la commande Optimize-VHD du module Hyper-V (cette dernière n’est disponible que si Hyper-V est activé).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Si le module Hyper-V est disponible
Optimize-VHD -Path "$env:LOCALAPPDATA\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx" -Mode Full

# Si vous utilisez diskpart
diskpart
# Entrez interactivement dans l'invite suivante
DISKPART> select vdisk file="C:\Users\<Nom_d_utilisateur>\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx"
DISKPART> attach vdisk readonly
DISKPART> compact vdisk
DISKPART> detach vdisk
DISKPART> exit

En effectuant cette opération régulièrement, vous pouvez récupérer la capacité du lecteur C inutilement consommée.

10. Conclusion

WSL2 a complètement dépassé le cadre d’être un simple « Linux bonus fonctionnant sur Windows » et a évolué vers une puissante plateforme de développement qui n’est pas inférieure, et peut-être même supérieure, à macOS et aux machines Linux natives.

En appliquant tous les paramètres expliqués cette fois-ci (optimisation des ressources avec .wslconfig, amélioration du terminal avec Zsh + Powerlevel10k, accès transparent avec VS Code Remote, intégration SSH et maintenance VHDX), un « environnement de développement ultime » rapide, sécurisé et sans stress est achevé.

La configuration de l’environnement demande un peu d’effort, mais une fois les paramètres fixés, il ne fait aucun doute que votre future productivité en ingénierie s’améliorera considérablement. N’hésitez pas à explorer des personnalisations supplémentaires sur la base de ce guide, en fonction de vos propres projets et préférences.