Docker on kenji.blog

Steps to Build a Reproducible Local Development Environment Using Docker

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

1. Introduction: Breaking Free from “It Works on My Machine”

In the field of software development, the “It works on my machine” problem, caused by differences in developers’ environments, has long been a factor in wasting time on many projects. Local environments are constantly exposed to “state uncertainty,” such as OS differences, installed language versions, library dependencies, and conflicts between globally installed tools.

What fundamentally solves these issues is container technology like Docker and the Infrastructure as Code (IaC) paradigm. By containerizing the local development environment, OS-level isolation is achieved, and the environment itself can be version-controlled alongside the codebase.

In this article, we will thoroughly explain the steps to build a “reproducible local development environment that results in the exact same state, no matter who, when, or on what machine it is launched,” by leveraging Docker, Docker Compose, and VSCode DevContainers. We will also explore the deep technical mechanisms behind it from a mathematical perspective.

2. The Synergy Between Infrastructure as Code (IaC) and Container Technology

IaC Principles and Application to Local Environments

Infrastructure as Code (IaC) is an approach to managing infrastructure configuration and provisioning through machine-readable definition files rather than manual processes. The core principles of IaC include the following elements:

Declarative Approach: Defines “what the final state should be” rather than “how to change the state.”
Idempotency: Guarantees the exact same result (state) no matter how many times the script is executed.
Version Control: The infrastructure state is stored as code in a VCS like Git, enabling change history tracking and peer reviews.

Practicing IaC in a local development environment means codifying the “ideal state” of the development environment using Dockerfile, docker-compose.yml, and devcontainer.json. This provides an onboarding experience where new team members can clone the repository and start developing immediately by running a single command.

Kernel Features Supporting Container Technology

Unlike hypervisor-based virtualization like virtual machines (VMs), container technology is a lightweight virtualization technique that isolates processes while sharing the host OS kernel. To achieve this, it primarily relies on the following Linux kernel features:

Namespaces: Provides independent views of system resources (PID, network, mount points, users, etc.) for each process.
Cgroups (Control Groups): Limits and allocates the physical resources (CPU, memory, disk I/O, etc.) that processes can use.
UnionFS (Union File System): A technology that transparently overlays multiple directory trees (layers) to present them as a single file system. Docker’s image layers rely on this technology.

Let’s consider a mathematical model of resource limitation. Let the total memory capacity of the host machine be $M_{\text{total}}$, and the memory limit of $n$ containers running on the host be $m_i$. Taking into account the base memory $M_{\text{os}}$ consumed by the host OS and other processes, the necessary condition for the system to operate stably can be expressed by the following inequality:

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

By strictly defining $m_i$ for each container using Cgroups, even if a specific container causes a memory leak, the OOM (Out Of Memory) Killer can prevent other containers or the entire host system from going down.

3. Efficient Dockerfile Design: Mastering Multi-Stage Builds

The first step to a reproducible environment is designing the Dockerfile that defines the application’s runtime environment. Here, using Python (FastAPI) as an example, we will explain the best practices for a secure and lightweight Dockerfile leveraging multi-stage builds.

A multi-stage build is a technique that uses multiple FROM instructions within a single Dockerfile to separate the build environment (a heavy environment containing compilers and development tools) from the runtime environment (a lightweight environment holding only the necessary artifacts).

Practical Python FastAPI Dockerfile

The following code is an example of an advanced Dockerfile that combines dependency management using Poetry and multi-stage builds.

 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 (Build Environment)
# ---------------------------------------------------------
FROM python:3.11-slim AS builder

# Set necessary environment variables
ENV PYTHONUNBUFFERED=1 \
 PYTHONDONTWRITEBYTECODE=1 \
 POETRY_VERSION=1.6.1 \
 POETRY_HOME="/opt/poetry" \
 POETRY_VIRTUALENVS_IN_PROJECT=true \
 POETRY_NO_INTERACTION=1

# Install dependencies
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

# Copy dependency files and install
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-root --only main

# ---------------------------------------------------------
# Stage 2: Runtime (Execution Environment)
# ---------------------------------------------------------
FROM python:3.11-slim AS runtime

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

# Create a minimal non-root user
RUN groupadd -r appuser && useradd -r -g appuser appuser

WORKDIR /app

# Copy only the virtual environment (dependencies) from the builder
COPY --from=builder --chown=appuser:appuser /app/.venv /app/.venv

# Copy application code
COPY --chown=appuser:appuser ./src /app/src

# Switch to the non-root user
USER appuser

# Default command upon container startup
ENTRYPOINT ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

Mathematical Evaluation of Image Size via Multi-Stage Builds

Let the image size when built with a single stage be $S_{\text{single}}$, and the image size when a multi-stage build is applied be $S_{\text{multi}}$. The size reduction rate $R$ is calculated as follows:

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

For example, suppose $S_{\text{single}}$ includes the OS base image (approx. 110MB), development packages (like gcc, approx. 150MB), Poetry itself (approx. 40MB), project dependency libraries (approx. 80MB), and source code (approx. 5MB), totaling 385MB. On the other hand, in $S_{\text{multi}}$, only the dependency libraries (80MB) and source code (5MB) are copied into the base image (110MB), resulting in a total of 195MB.

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

In this way, introducing multi-stage builds can reduce the image size by about half. Reducing the image size directly leads to improved security by shortening pull times from the registry, saving disk space, and shrinking the attack surface.

4. Orchestrating Multiple Containers with Docker Compose

In modern web application development, a microservices architecture where multiple components like web servers, databases, and cache servers collaborate is common. We use docker-compose.yml to centrally manage these in a local environment.

Here, we will build a 3-tier system locally consisting of “Web (FastAPI),” “Database (PostgreSQL),” and “Cache (Redis).”

Architecture Diagram (Mermaid)

The following diagram is a block diagram illustrating the relationships among each container, network, and volume on the local machine.

graph TD
User["Host Machine (Browser/curl)"] -->|Localhost:8000| Web["FastAPI Web Container"]
subgraph "Docker Bridge Network (app-network)"
Web -->|Port 5432| DB["PostgreSQL Container"]
Web -->|Port 6379| Redis["Redis Container"]
end
DB --> Volume1["Named Volume (postgres_data)"]
Redis --> Volume2["Named Volume (redis_data)"]
HostDir["Host Source Code (./src)"] -.->|Bind Mount| Web

Implementation and Detailed Explanation of docker-compose.yml

Below is an example of a robust docker-compose.yml that can withstand practical environment construction.

 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  # Mount the host code as read-only (for hot reloading)
 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 and Data Persistence

Containers are generally “stateless” and “ephemeral” entities. When a container is destroyed, the data inside it is also lost. To retain database data and caches, it is necessary to mount an area of the host machine’s file system into the container.

Bind Mount: This corresponds to ./src:/app/src:ro in the web service above. It directly maps a specific directory on the host into the container. This is used to immediately reflect local code edits in the container (hot reloading). For security reasons, it is a best practice to add the :ro (Read-Only) option to prevent the container from altering the host’s source code.
Named Volume: This corresponds to postgres_data and redis_data. This is an area internally managed by Docker (like /var/lib/docker/volumes/), which offers better I/O performance than bind mounts and abstracts the differences in file systems across OSes. Be sure to use this for database persistence.

Networking and Service Discovery

Docker Compose creates a unique bridge network for each project by default. This is the app-network mentioned above. Containers belonging to the same network can resolve names (DNS resolution) using the “service name” (e.g., db, redis) as the hostname instead of an IP address. For example, the Web container can access the database using the URL postgresql://postgres:password@db:5432/mydb. This allows connections to be switched transparently via environment variables, regardless of whether it’s a local or production environment.

Health Checks and Controlling Startup Order

The depends_on directive controls the startup order of containers, but simply specifying depends_on will start the Web container as soon as the “DB container has started.” In reality, the DB initialization process (starting the PostgreSQL process and preparing tables) takes several seconds, so connections from the Web container might fail. To prevent this, you can define a healthcheck and specify condition: service_healthy, which ensures the Web container starts only after confirming that “the DB is ready to accept connection requests.”

5. Environment Variable Management and Security (.env)

Hardcoding sensitive information, such as database passwords and API keys, into docker-compose.yml is an anti-pattern that must be strictly avoided. Instead, inject these values using an environment variable file .env.

Create a .env file in the project root.

1
2
3
4


# .env file (add it to .gitignore to keep it out of Git tracking)
POSTGRES_PASSWORD=supersecretpassword
POSTGRES_DB=devdb
API_SECRET_KEY=dev_secret_key_12345

By default, Docker Compose reads the .env file in the execution directory and expands placeholders like ${VAR_NAME} in the YAML file. This method makes it possible to safely manage different configuration values for various environments like local, staging, and production without altering the infrastructure code.

6. The Ultimate Development Experience with VSCode DevContainers

So far, we have built a robust backend environment using Docker. However, we can take it a step further. By using the VSCode DevContainers (Remote - Containers) feature, you can run the backend of the editor (VSCode) itself inside the container.

This eliminates the need to install Python or Node.js on your local machine, allowing everything from linters (flake8/eslint) and formatters (black/prettier) to IDE extensions to be defined within the codebase and shared with the entire team.

Configuring devcontainer.json

Create a .devcontainer directory in the project root and place the configuration file inside it.

.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"
}

By including this file in the repository, a “Reopen in Container” prompt will appear the moment you open the project in VSCode. A single click will spin up all the necessary containers, install the extensions, and make it instantly ready for coding. It’s truly a magical experience.

7. Request Processing Sequence and Performance Modeling

We will review the request processing lifecycle of the web application in our newly built local development environment using a sequence diagram and examine the mathematical model of its performance.

Sequence Diagram (Request Flow)

sequenceDiagram
participant Client as "Browser / VSCode"
participant Web as "FastAPI (Web)"
participant Redis as "Redis Cache"
participant DB as "PostgreSQL"
Client->>Web: "GET /api/users/123"
activate Web
Web->>Redis: "Check Cache for user:123"
activate Redis
alt "Cache Hit (Data exists)"
Redis-->>Web: "Return Cached User Data"
Web-->>Client: "200 OK (Fast Response)"
else "Cache Miss (Data does not exist)"
Redis-->>Web: "Null (Not Found)"
deactivate Redis
Web->>DB: "SELECT * FROM users WHERE id = 123"
activate DB
DB-->>Web: "Return Database Row"
deactivate DB
Web->>Redis: "SET user:123 Data (TTL: 60s)"
activate Redis
Redis-->>Web: "OK"
deactivate Redis
Web-->>Client: "200 OK (Standard Response)"
end
deactivate Web

Mathematical Model of Processing Latency

We mathematically model the average request processing time $T_{\text{total}}$ in the above system. We define the latency of each process as follows:

$T_{\text{net}}$: Network latency between the client and the Web container
$T_{\text{app}}$: Pure processing time on the application side (serialization, etc.)
$T_{\text{cache}}$: Time required to read/write from/to Redis
$T_{\text{db}}$: Time required to execute queries on PostgreSQL
$p_{\text{miss}}$: Cache miss rate ($0 \le p_{\text{miss}} \le 1$)

At this time, the average response time is represented by the following expected value formula:

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

In a local development environment (inside Docker), $T_{\text{net}}$ is close to 0, but what’s noteworthy is the I/O performance during bind mounts. Especially when using Docker Desktop on Windows/macOS, the file sharing overhead between the host OS and the VM (container) tends to bloat $T_{\text{app}}$ (such as code load time). To eliminate this bottleneck, it is highly recommended to use the aforementioned DevContainers to place the entire source code inside a named volume, or to adopt an architecture that runs the Docker engine natively on a WSL2 (Windows Subsystem for Linux 2) environment.

8. Performance Optimization of Docker Builds: Layer Caching Strategy

When writing a Dockerfile, your understanding of the “layer cache” mechanism will drastically change build times. Docker creates file system differences (layers) for each instruction in a Dockerfile (like FROM, RUN, COPY) and holds them as caches. On rebuild, cached layers that haven’t changed are reused.

The critical principle is to “write instructions in order from the least frequently changed to the most frequently changed.”

Let’s model the impact of source code changes on build time. Let the total build time be $T_{\text{build}}$, the execution time of each step be $T_{\text{layer}_i}$, and the presence or absence of a cache hit be a boolean value $c_i \in \{0, 1\}$ (1 for a cache hit).

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

Once a cache miss ($c_k = 0$) occurs at layer $k$, caches for all subsequent layers $j > k$ are invalidated ($c_j = 0$).

1
2
3
4


# Bad example (Source code is copied first)
COPY ./src /app/src
COPY pyproject.toml poetry.lock ./
RUN poetry install

In the above case, changing even one line of code causes the first COPY to miss the cache, resulting in the time-consuming RUN poetry install being executed every time.

1
2
3
4


# Good example (Resolve dependencies first)
COPY pyproject.toml poetry.lock ./
RUN poetry install
COPY ./src /app/src

If written this way, even if the source code changes, the layer cache for poetry install ($c_i = 1$) remains effective, drastically reducing build time from several minutes to just a few seconds.

9. Troubleshooting and Tips

Here are common problems encountered during local environment operations and their solutions.

Port Conflict Error If you get an error like Bind for 0.0.0.0:8000 failed: port is already allocated, another process on your local machine is using that port. You can avoid this by changing the port number on the host side, like ports: - "8080:8000".
Disk Space Exhaustion If you use Docker for a long period, unused images and volumes (Dangling Images / Volumes) can accumulate and consume tens of gigabytes of disk space. It is recommended to periodically clean up the system with the following command:
1

docker system prune -a --volumes
File Permission Issues When using bind mounts in a Linux environment, files created inside the container may be owned by root, preventing you from editing them on the host side. You can resolve this issue by creating a non-root user in your Dockerfile and matching their UID/GID to your own on the host OS (e.g., 1000:1000).

10. Conclusion: Accelerated Development Speeds Brought by Reproducibility

By combining Docker, Docker Compose, and VSCode DevContainers, a robust local development environment is achieved, resulting in “the exact same state no matter who launches the environment.”

Bringing the IaC paradigm into your local environment goes beyond merely reducing initial setup times. It eliminates anxiety regarding infrastructure configuration changes, facilitates experimenting with new tech stacks, enables smooth transitions to CI/CD pipelines, and dramatically improves the speed and quality of the entire development cycle.

By leveraging the best practices explained in this article—optimizing image sizes with multi-stage builds, controlling dependencies with health checks, and writing Dockerfiles with layer caching in mind—we highly encourage you to introduce the best Developer Experience (DX) to your own projects.

The Ultimate Development Environment Setup Guide for WSL2 (Windows Subsystem for Linux)

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

WSL2 (Windows Subsystem for Linux 2), which provides a Linux-native development environment on Windows, has become an indispensable tool in modern software development. However, there is a world of difference in performance and development experience between continuing to use it in its default state and understanding the architecture to apply appropriate tuning.

In this article, starting with an explanation of the architecture that forms the foundation of WSL2, we will thoroughly explain all the steps to build the “ultimate development environment” demanded by professional engineers in a volume of over 10,000 characters. This covers settings to maximize performance, building a comfortable terminal environment, seamless integration with Docker and VS Code, and advanced network configurations.

1. WSL2 Architecture and Evolution from WSL1

To fully unleash the potential of WSL2, it is important to first understand its internal structure. The approach to running Linux binaries on Windows is fundamentally different between the first-generation WSL (WSL1) and WSL2.

WSL1: System Call Translation Layer

WSL1 adopted a mechanism that translates Linux system calls into Windows NT APIs in real-time. Because this did not use a virtual machine (VM), it had the advantage of very low resource overhead. However, it was difficult to perfectly emulate complex system calls, such as file system I/O operations, which led to devastating performance degradation, especially in processes dealing with large numbers of small files, such as Node.js npm install and Git repository operations.

WSL2: Lightweight Utility VM and a Complete Linux Kernel

In WSL2, the architecture was revamped, and an authentic Linux kernel built by Microsoft now runs directly on a “lightweight utility VM” utilizing a subset of the Hyper-V architecture. This ensures 100% compatibility for system calls and dramatically improves file I/O performance compared to WSL1 by using a virtual disk (VHDX) that utilizes the Linux-native ext4 file system.

The following Mermaid diagram shows the structural differences between WSL1 and WSL2.

flowchart TD
subgraph "Windows OS Environment"
A["Windows NT Kernel"]
A --> F["NTFS File System (C: Drive)"]
end
subgraph "WSL2 Architecture"
B["Hyper-V Hypervisor"]
B --> C["Lightweight Utility VM"]
C --> D["Linux Kernel (Microsoft)"]
D --> E["Ubuntu User Space (glibc, bash, etc.)"]
D --> G["ext4 Virtual Disk (.vhdx)"]
end
A -.->|"Plan 9 (9P) Protocol Network File Share"| D
style B fill:#f9f,stroke:#333,stroke-width:2px
style D fill:#bbf,stroke:#333,stroke-width:2px

An important lesson to be learned from this structure is: “Access to files on the Linux side (inside the VHDX) is extremely fast, but access to files on the Windows side (/mnt/c/) is very slow because it goes through the 9P protocol.” The source code of your projects must always be placed under the home directory (~) on the WSL side.

2. Mathematical Analysis of Performance: Why is WSL2 so fast?

Let’s quantitatively evaluate the performance improvement of WSL2 using a mathematical model. One of the most time-consuming operations in software development is processing that involves a large amount of file I/O (e.g., library installation or building).

The total execution time $T_{total}$ of a certain process is expressed as the sum of the computing time by the CPU $T_{compute}$ and the time taken for disk I/O $T_{io}$.

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

In the case of WSL1, because an overhead occurs in translating Linux-side operations into NTFS operations, the I/O time is modeled as follows. Here, $n$ is the number of file operations, $t_{ntfs\_syscall}$ is the execution time of the Windows-side system call, and $t_{trans}$ is the overhead of the translation layer.

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

On the other hand, in WSL2, since the kernel issues I/O directly to the ext4 file system, the overhead is only a very small delay $t_{virt}$ due to virtualization.

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

In a general file system, since $t_{ext4} \ll t_{ntfs\_syscall} + t_{trans}$, when $n$ is very large (performing tens to hundreds of thousands of file operations), the difference in I/O time between WSL1 and WSL2 grows exponentially.

Also, assuming the overhead ratio of CPU computation in a virtualized environment is $\rho$, with modern hardware-assisted virtualization (Intel VT-x / AMD-V), it stays around $\rho \approx 0.01 \sim 0.03$ (1 to 3%). Therefore, even in pure computational tasks, it delivers a performance of $97\% \sim 99\%$ which is comparable to a native Linux environment.

3. Installation and Foundation Building

On Windows 10/11, installing WSL2 has become very simple. Just open PowerShell with administrator privileges and run the following command.

1
2
3
4
5
6


# WSL2 and Ubuntu are installed by default
wsl --install

# When specifying a specific distribution
# You can check this with wsl --list --online
wsl --install -d Ubuntu-24.04

After installation, following a reboot, you will be prompted to set up a UNIX username and password upon the first launch. This user is independent of the Windows user and is only valid within WSL.

If you are already using WSL1, convert it to WSL2 with the following command.

1
2
3
4
5


# Convert an existing distribution to WSL2
wsl --set-version Ubuntu 2

# Set WSL2 as the default version for any future distributions you add
wsl --set-default-version 2

4. The Secret of Resource Control: .wslconfig and wsl.conf

One of the biggest traps in WSL2 is the “unlimited consumption of memory (bloating of the Vmmem process)”. Since WSL2 utilizes the Linux kernel’s page cache, it will endlessly consume the host’s (Windows) memory every time it performs I/O. To prevent this, it is essential to limit resources using configuration files.

WSL2 configuration files are divided into two: .wslconfig which affects the entire Windows system, and wsl.conf which affects the inside of each distribution.

4.1. .wslconfig (Windows side)

Create a file in the Windows user profile directory (C:\Users\<username>\.wslconfig) to control resource allocation for the 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\<username>\.wslconfig
[wsl2]
# Maximum memory allocated to the VM. We recommend about 50% to 75% of the host's total memory
memory=16GB

# Number of CPU cores to use (uses all cores if omitted)
processors=8

# Size of the swap file
swap=8GB

# Destination to save the swap file (useful if you want to save space on the C drive)
# swapfile=D:\\wsl\\swap.vhdx

# Enable localhost forwarding (to access WSL from the Windows side using localhost)
localhostForwarding=true

# Automatically free up memory (Windows 11 only)
# Dynamically releases page cache to prevent Vmmem bloating
autoMemoryReclaim=dropcache

[experimental]
# Advanced networking features available in Windows 11 22H2 and later
# This enables IPv6 support and allows sharing the same IP address between WSL and Windows
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

4.2. wsl.conf (Linux side)

Edit /etc/wsl.conf inside WSL to control the distribution-specific behavior.

 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 (edit inside WSL)
[network]
# Disable the automatic generation of /etc/resolv.conf when WSL starts
# Useful when you want to set your own DNS (e.g., 8.8.8.8)
generateResolvConf=false

# Set a custom hostname
hostname=WSL-DevNode

[automount]
# Settings for mounting Windows drives
enabled=true
options="metadata,uid=1000,gid=1000,umask=022"
# Change the mount point of the C drive from /mnt/c to /c (to shorten the path)
root=/

[boot]
# Enable systemd (WSL 0.67.6 or later)
# This allows snaps and various daemons (like Docker) to run natively
systemd=true

[user]
# Default user to log in as
default=kenji

To apply these settings, you need to run wsl --shutdown in PowerShell to completely stop the WSL VM and then restart it.

5. The Ultimate Terminal Environment: Zsh + Powerlevel10k

Productivity won’t improve if you stick with the default bash. Combine Zsh, which boasts powerful completion features and visibility, with the ultra-fast theme “Powerlevel10k” to build the strongest prompt.

5.1. Installing and Configuring Windows Terminal

Install “Windows Terminal” from the Microsoft Store. Open the JSON settings (settings.json), set the default profile to WSL (Ubuntu), and change the font to a Nerd Font for development (e.g., HackGen Console NF or MesloLGS NF).

5.2. Installing Zsh and Oh My Zsh

Run the following commands in the WSL terminal.

1
2
3
4
5
6


# Update packages and install Zsh
sudo apt update && sudo apt upgrade -y
sudo apt install -y zsh git curl

# Run the Oh My Zsh installation script
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

5.3. Introducing Powerlevel10k and Plugins

Introduce plugins that further enhance Zsh (syntax highlighting and auto-suggestions) and the Powerlevel10k theme.

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

Edit ~/.zshrc to enable the theme and plugins.

1
2
3
4
5


# Changes in ~/.zshrc
ZSH_THEME="powerlevel10k/powerlevel10k"

# Add to the plugins array
plugins=(git zsh-autosuggestions zsh-syntax-highlighting)

After saving, running source ~/.zshrc will launch the Powerlevel10k configuration wizard (p10k configure). Follow the on-screen instructions to customize the prompt to your liking (prompt style, presence of icons, information to display, etc.). Information such as the Git branch name and status, Node.js version, and command execution time will be displayed in real-time, dramatically improving your development efficiency.

6. Seamless Integration with VS Code Remote - WSL

For development in WSL2, the “Remote - WSL” extension is the mechanism that seamlessly accesses files inside WSL from the IDE (Visual Studio Code) installed on the Windows side.

Architecture Explanation

The following sequence diagram shows how VS Code communicates with WSL2.

sequenceDiagram
autonumber
participant U as "Developer"
participant V as "VS Code UI (Windows)"
participant S as "VS Code Server (WSL2)"
participant F as "ext4 File System (WSL2)"
U->>V: "Type `code .` in WSL Terminal"
V->>S: "Establish RPC Connection via Vsock"
Note over V,S: Communicates via Hyper-V sockets without using TCP/IP
S->>F: "Read Source Files / Run Linter"
F-->>S: "Return Data & Analysis"
S-->>V: "Stream Language Server results to UI"
V-->>U: "Display syntax highlighting & errors"

The VS Code on the Windows side acts merely as a “thin client (UI)”, and heavy processing such as the Language Server, debugger, and terminal execution are all handled by the “VS Code Server” on the WSL side. This allows you to keep your environment clean on the WSL side without installing Node.js or Python on the Windows side.

Essential VS Code Settings

Install “WSL” (ms-vscode-remote.remote-wsl) from the “Extensions” in VS Code. After that, simply navigate to your project directory in the WSL terminal and run code ., which will launch the Windows-side VS Code with that directory open.

Important Note (Line Ending Issue): Windows and Linux have different line endings (Windows uses CRLF, while Linux uses LF). When developing on WSL, be sure to unify Git’s core.autocrlf setting and VS Code’s default file setting to LF. Neglecting this will cause you to suffer from mysterious errors when executing shell scripts or Docker containers.

1
2


# Git line ending setting on the WSL side
git config --global core.autocrlf input

Also add the following to VS Code’s settings.json (remote settings).

1
2
3
4


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

7. Optimizing Docker Desktop and WSL2 Integration

There are mainly two approaches to using Docker in a WSL2 environment:

Install Docker Desktop for Windows and enable the WSL2 integration feature.
Directly install native Docker Engine inside WSL2 (e.g., Ubuntu).

Approach 1: Docker Desktop (Recommended)

This is recommended in most cases because it is easy to manage via a GUI and allows transparent access to containers between Windows and WSL. Check the following in the Docker Desktop settings (Settings):

Check General -> Use the WSL 2 based engine.
Check Resources -> WSL Integration -> Enable integration with my default WSL distro, and turn on the toggle button for the distribution you use (Ubuntu).

This allows you to execute the docker command directly from the WSL2 terminal, and communication with the Docker daemon is done through dedicated lightweight VMs (docker-desktop and docker-desktop-data) managed by Docker Desktop.

Approach 2: Direct Installation of Native Docker Engine

If there are corporate network restrictions (like avoiding paid Docker Desktop plans) or if you want to minimize performance overhead to the limit, enable systemd in /etc/wsl.conf and install Docker as a pure Ubuntu server.

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


# Excerpt of the official Docker installation steps on WSL2 Ubuntu with systemd enabled
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

# Add repository
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

# Add the current user to the docker group (to execute without sudo)
sudo usermod -aG docker $USER

After a reboot, systemctl start docker will function exactly like a native Linux environment and deliver high performance.

8. SSH Key Integration: Seamless Authentication between Windows and WSL

Managing separate SSH keys on the Windows side and the WSL side when doing Git SSH cloning or SSH connecting to remote servers is extremely tedious. To balance security and convenience, configure a bridge for the SSH agent running on the Windows side (or a password manager like 1Password) to the WSL side.

Here, we will explain the most secure and modern approach: using the 1Password SSH Agent feature or the Windows OpenSSH Authentication Agent, and forwarding it to a UNIX domain socket in WSL2 using npiperelay or socat.

Socket Forwarding for ssh-agent

You need to convert the SSH agent typically provided as a Named Pipe in Windows into a socket file on the WSL side. This is easy if you use wsl-ssh-agent or the features provided by 1Password.

From the 1Password settings screen, enable “Developer” -> “Use SSH agent”. Next, add the following configuration to ~/.zshrc or ~/.bashrc on the WSL side so that it automatically binds to the socket upon login.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Addition to ~/.zshrc (Example when using 1Password SSH Agent)
export SSH_AUTH_SOCK=$HOME/.ssh/agent.sock
# If the socket doesn't exist at WSL startup, or the process isn't bound, forward using socat and npiperelay
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
 # Launch socat in the background to connect the Windows-side Named Pipe to the WSL-side UNIX socket
 (setsid socat UNIX-LISTEN:$SSH_AUTH_SOCK,fork EXEC:"npiperelay.exe -ei -s //./pipe/openssh-ssh-agent",nofork &) >/dev/null 2>&1
fi

Note: You must install npiperelay.exe on the Windows side and add it to your PATH beforehand.

Once this setup is complete, when you run ssh-add -l from the WSL terminal, a list of public keys for the SSH keys registered in 1Password or on the Windows side will be displayed. This allows you to securely pass authentication without copying your private key files into WSL.

9. Maintenance: Optimizing (Compacting) the Bloated VHDX

One of the biggest drawbacks of WSL2 is its behavior where “the file size of the virtual disk (.vhdx) on the Windows side is not automatically reduced even when Docker images or files are deleted”. If you continue developing for a long time, the ext4.vhdx file will swell to tens or hundreds of gigabytes.

To free up disk space, you need to regularly optimize (Compact) the VHDX from the Windows side.

First, completely shut down WSL.
1

wsl --shutdown
Open PowerShell with administrator privileges and run the following diskpart command, or the Optimize-VHD command of the Hyper-V module (the latter can only be used if Hyper-V is enabled).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# When the Hyper-V module is available
Optimize-VHD -Path "$env:LOCALAPPDATA\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx" -Mode Full

# When using diskpart
diskpart
# Enter interactively in the following prompt
DISKPART> select vdisk file="C:\Users\<username>\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx"
DISKPART> attach vdisk readonly
DISKPART> compact vdisk
DISKPART> detach vdisk
DISKPART> exit

By performing this operation regularly, you can reclaim unnecessarily consumed space on your C drive.

10. Conclusion

WSL2 has completely transcended the framework of being just a “bonus Linux running on Windows” and has evolved into a powerful development platform that is equal to, or even better than, MacOS and native Linux machines.

By applying all the configurations explained here (resource optimization via .wslconfig, terminal enhancement with Zsh + Powerlevel10k, transparent access with VS Code Remote, and SSH integration and VHDX maintenance), a stress-free, fast, and secure “ultimate development environment” is completed.

Although setting up the environment takes a little effort, once the settings are solidified, there is no doubt that your future engineering productivity will improve dramatically. Please explore further customizations based on this guide to suit your projects and preferences.