Docker on kenji.blog

Pasos para construir un entorno de desarrollo local reproducible usando Docker

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

1. Introducción: Escapando de “en mi máquina funciona”

En el ámbito del desarrollo de software, el problema de “en mi máquina funciona” (It works on my machine), causado por las diferencias en los entornos entre desarrolladores, ha sido durante mucho tiempo un factor de pérdida de tiempo en muchos proyectos. Las diferencias en el sistema operativo, las versiones de los lenguajes instalados, las dependencias de bibliotecas y los conflictos entre herramientas instaladas globalmente exponen constantemente a los entornos locales a la “incertidumbre de estado”.

Lo que resuelve estos problemas de raíz son las tecnologías de contenedores, como Docker, y el paradigma de Infrastructure as Code (IaC). Al contenerizar el entorno de desarrollo local, se logra el aislamiento a nivel del sistema operativo, haciendo posible controlar las versiones del propio entorno junto con el código base.

En este artículo, explicaremos exhaustivamente los pasos para construir un “entorno de desarrollo local reproducible, que tendrá exactamente el mismo estado sin importar quién, cuándo o en qué máquina lo inicie”, aprovechando Docker, Docker Compose y VSCode DevContainers, así como los profundos mecanismos técnicos detrás de ello, incorporando también una perspectiva matemática.

2. La afinidad entre Infrastructure as Code (IaC) y la tecnología de contenedores

Principios de IaC y su aplicación a entornos locales

Infrastructure as Code (IaC) es un enfoque que gestiona la configuración y el aprovisionamiento de la infraestructura a través de archivos de definición legibles por máquina, en lugar de procesos manuales. Los principios fundamentales de IaC incluyen los siguientes elementos:

Enfoque declarativo (Declarative Approach): Define “cuál debería ser el estado final” en lugar de “cómo cambiar el estado”.
Idempotencia (Idempotency): No importa cuántas veces se ejecute el script, siempre se garantiza el mismo resultado (estado).
Control de versiones (Version Control): El estado de la infraestructura se guarda como código en un VCS (como Git), lo que permite rastrear el historial de cambios y realizar revisiones por pares.

Practicar IaC en un entorno de desarrollo local significa codificar el “estado ideal” del entorno de desarrollo utilizando Dockerfile, docker-compose.yml y devcontainer.json. Esto permite que los nuevos miembros del equipo logren una experiencia de incorporación donde pueden comenzar a desarrollar inmediatamente con solo clonar el repositorio y ejecutar un comando.

Funciones del kernel que sustentan la tecnología de contenedores

La tecnología de contenedores, a diferencia de la virtualización basada en hipervisor como las máquinas virtuales (VM), es una tecnología de virtualización ligera que aísla procesos compartiendo el kernel del sistema operativo anfitrión. Para lograr esto, se utilizan principalmente las siguientes funciones del kernel de Linux:

Namespaces: Proporcionan una vista independiente de los recursos del sistema (PID, red, puntos de montaje, usuarios, etc.) para cada proceso.
Cgroups (Control Groups): Limitan y asignan los recursos físicos (CPU, memoria, E/S de disco, etc.) que pueden usar los procesos.
UnionFS (Union File System): Una tecnología que superpone de forma transparente múltiples árboles de directorios (capas) para presentarlos como un único sistema de archivos. Las capas de imagen de Docker dependen de esta tecnología.

Consideremos un modelo matemático para la limitación de recursos. Supongamos que la capacidad total de memoria de la máquina anfitriona es $M_{\text{total}}$ y el límite de memoria para los $n$ contenedores que se ejecutan en el host es $m_i$. La condición necesaria para que el sistema funcione de manera estable, considerando la memoria base $M_{\text{os}}$ consumida por el sistema operativo anfitrión y otros procesos, se puede expresar mediante la siguiente desigualdad:

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

Al definir estrictamente $m_i$ para cada contenedor utilizando Cgroups, se puede evitar que otros contenedores o todo el sistema anfitrión se caigan debido al OOM (Out Of Memory) Killer en caso de que un contenedor en particular sufra una fuga de memoria.

3. Diseño eficiente del Dockerfile: Dominando las construcciones en múltiples etapas

El primer paso hacia un entorno reproducible es diseñar un Dockerfile que defina el entorno de ejecución de la aplicación. Aquí, usando Python (FastAPI) como ejemplo, explicaremos las mejores prácticas para un Dockerfile seguro y ligero aprovechando las construcciones en múltiples etapas (multi-stage builds).

La construcción en múltiples etapas es una técnica que utiliza múltiples instrucciones FROM en un solo Dockerfile para separar el entorno de construcción (un entorno pesado que contiene compiladores y herramientas de desarrollo) del entorno de ejecución (un entorno ligero con solo los artefactos necesarios).

Dockerfile práctico para Python FastAPI

El siguiente código es un ejemplo de un Dockerfile avanzado que combina la gestión de dependencias con Poetry y la construcción en múltiples etapas.

 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 (Entorno de construcción)
# ---------------------------------------------------------
FROM python:3.11-slim AS builder

# Configuración de variables de entorno necesarias
ENV PYTHONUNBUFFERED=1 \
 PYTHONDONTWRITEBYTECODE=1 \
 POETRY_VERSION=1.6.1 \
 POETRY_HOME="/opt/poetry" \
 POETRY_VIRTUALENVS_IN_PROJECT=true \
 POETRY_NO_INTERACTION=1

# Instalación de paquetes de dependencias
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

# Copia e instalación de archivos de dependencias
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-root --only main

# ---------------------------------------------------------
# Stage 2: Runtime (Entorno de ejecución)
# ---------------------------------------------------------
FROM python:3.11-slim AS runtime

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

# Creación de un usuario sin privilegios mínimos
RUN groupadd -r appuser && useradd -r -g appuser appuser

WORKDIR /app

# Copiar solo el entorno virtual (dependencias) desde el builder
COPY --from=builder --chown=appuser:appuser /app/.venv /app/.venv

# Copia del código de la aplicación
COPY --chown=appuser:appuser ./src /app/src

# Cambio al usuario sin privilegios
USER appuser

# Comando por defecto al iniciar el contenedor
ENTRYPOINT ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

Evaluación matemática del tamaño de la imagen mediante la construcción en múltiples etapas

Supongamos que el tamaño de la imagen construida en una sola etapa es $S_{\text{single}}$ y el tamaño de la imagen al aplicar la construcción en múltiples etapas es $S_{\text{multi}}$. La tasa de reducción de tamaño $R$ se calcula de la siguiente manera:

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

Por ejemplo, supongamos que $S_{\text{single}}$ incluye la imagen base del SO (aprox. 110MB), paquetes de desarrollo (como gcc, aprox. 150MB), el propio Poetry (aprox. 40MB), las bibliotecas de dependencias del proyecto (aprox. 80MB) y el código fuente (aprox. 5MB), totalizando 385MB. Por otro lado, en $S_{\text{multi}}$, solo se copian a la imagen base (110MB) las bibliotecas de dependencias (80MB) y el código fuente (5MB), sumando un total de 195MB.

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

De esta manera, al introducir construcciones en múltiples etapas, el tamaño de la imagen se puede reducir a la mitad aproximadamente. La reducción en el tamaño de la imagen se traduce directamente en tiempos más cortos de extracción (Pull) desde el registro, ahorro de espacio en disco y una mejora en la seguridad mediante la reducción de la superficie de ataque (Attack Surface).

4. Orquestación de múltiples contenedores con Docker Compose

En el desarrollo de aplicaciones web modernas, es común utilizar una arquitectura de microservicios donde múltiples componentes colaboran, como servidores web, bases de datos y servidores de caché. Usamos docker-compose.yml para gestionar esto de forma centralizada en un entorno local.

Esta vez, construiremos localmente un sistema de tres capas compuesto por “Web (FastAPI)”, “Base de datos (PostgreSQL)” y “Caché (Redis)”.

Diagrama de arquitectura (Mermaid)

El siguiente diagrama de bloques ilustra la relación entre cada contenedor, red y volumen en la máquina local.

graph TD
User["Máquina Anfitriona (Navegador/curl)"] -->|Localhost:8000| Web["Contenedor Web FastAPI"]
subgraph "Red Bridge de Docker (app-network)"
Web -->|Puerto 5432| DB["Contenedor PostgreSQL"]
Web -->|Puerto 6379| Redis["Contenedor Redis"]
end
DB --> Volume1["Volumen Nombrado (postgres_data)"]
Redis --> Volume2["Volumen Nombrado (redis_data)"]
HostDir["Código Fuente del Anfitrión (./src)"] -.->|Montaje de Enlace| Web

Implementación y explicación detallada de docker-compose.yml

A continuación se muestra un ejemplo de un docker-compose.yml robusto, capaz de soportar la construcción de un entorno práctico.

 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  # Montaje de solo lectura del código del host (para recarga en caliente)
 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

Volúmenes (Volumes) y persistencia de datos

Los contenedores, por principio, son entidades “sin estado (stateless)” y “efímeras (ephemeral)”. Si se destruye un contenedor, sus datos internos también desaparecen. Para retener los datos de bases de datos y cachés, es necesario montar un área del sistema de archivos de la máquina anfitriona dentro del contenedor.

Montaje de enlace (Bind Mount): En el servicio web mencionado anteriormente, ./src:/app/src:ro corresponde a esto. Asigna un directorio específico del host directamente dentro del contenedor. Se utiliza para reflejar instantáneamente los cambios en el código local dentro del contenedor (recarga en caliente - hot reload). Desde una perspectiva de seguridad, la mejor práctica es agregar la opción :ro (Read-Only) para evitar que se pueda modificar el código fuente del host desde el lado del contenedor.
Volumen nombrado (Named Volume): Corresponde a postgres_data y redis_data. Es un área gestionada internamente por Docker (como /var/lib/docker/volumes/), la cual ofrece un rendimiento de E/S superior a los montajes de enlace y absorbe las diferencias de sistemas de archivos entre sistemas operativos. Siempre debe utilizarse este método para la persistencia de bases de datos.

Redes (Networking) y descubrimiento de servicios

Docker Compose crea de forma predeterminada una red bridge única por proyecto. Esto es la app-network mencionada anteriormente. Los contenedores que pertenecen a la misma red pueden resolverse por nombre (resolución DNS) utilizando su “nombre de servicio” (por ejemplo: db, redis) como nombre de host, en lugar de direcciones IP. Por ejemplo, desde el contenedor web se puede acceder a la base de datos con la URL postgresql://postgres:password@db:5432/mydb. Esto permite cambiar los destinos de conexión de manera transparente a través de variables de entorno, ya sea en el entorno local o en producción.

Health checks (Comprobación de estado) y control del orden de inicio

La directiva depends_on controla el orden de inicio de los contenedores, pero si solo se especifica depends_on, el contenedor web se iniciará tan pronto como el contenedor de la base de datos “haya arrancado”. En realidad, como el proceso de inicialización de la base de datos (iniciar el proceso de PostgreSQL, preparar tablas) toma unos segundos, la conexión a la base de datos desde el contenedor web puede generar un error. Para evitar esto, se puede definir un healthcheck y especificar condition: service_healthy, lo cual permite confirmar que “la base de datos está lista para aceptar peticiones de conexión” antes de iniciar el contenedor web.

5. Gestión de variables de entorno y seguridad (.env)

Codificar (hardcodear) información confidencial como contraseñas de bases de datos o claves API en docker-compose.yml es un antipatrón que debe evitarse estrictamente. En su lugar, utilice un archivo de variables de entorno .env para inyectar estos valores.

Cree un archivo .env en la raíz del proyecto.

1
2
3
4


# Archivo .env (Asegúrese de agregarlo a .gitignore para mantenerlo fuera del control de versiones de Git)
POSTGRES_PASSWORD=supersecretpassword
POSTGRES_DB=devdb
API_SECRET_KEY=dev_secret_key_12345

De forma predeterminada, Docker Compose lee el archivo .env en el directorio de ejecución y expande los marcadores de posición ${VAR_NAME} en los archivos YAML. Este enfoque permite gestionar de forma segura diferentes configuraciones para cada entorno (local, staging, producción) sin modificar el código de infraestructura.

6. La experiencia de desarrollo definitiva con VSCode DevContainers

Hasta este punto, se ha construido un entorno backend robusto usando Docker. Sin embargo, podemos ir un paso más allá. Al utilizar la función VSCode DevContainers (Remote - Containers), es posible ejecutar el backend del propio editor (VSCode) dentro de un contenedor.

Como resultado, ni siquiera es necesario instalar Python o Node.js en su máquina local, y todo —desde linters (flake8/eslint) y formateadores (black/prettier) hasta extensiones del IDE— se puede definir dentro del código base y compartir con todo el equipo.

Configuración de devcontainer.json

Cree un directorio .devcontainer en la raíz del proyecto y coloque el archivo de configuración dentro de él.

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

Al incluir este archivo en el repositorio, en el momento en que abra el proyecto en VSCode, aparecerá el aviso “Reopen in Container”. Con un solo clic, se iniciarán todos los contenedores necesarios, se instalarán las extensiones y estará listo para comenzar a programar de inmediato. Es verdaderamente una experiencia mágica.

7. Secuencia del procesamiento de peticiones y modelado de rendimiento

Revisaremos el ciclo de vida del procesamiento de peticiones (requests) de la aplicación web en el entorno de desarrollo local construido usando un diagrama de secuencia, y examinaremos un modelo matemático de su rendimiento.

Diagrama de secuencia (Flujo de peticiones)

sequenceDiagram
participant Client as "Navegador / VSCode"
participant Web as "FastAPI (Web)"
participant Redis as "Caché Redis"
participant DB as "PostgreSQL"
Client->>Web: "GET /api/users/123"
activate Web
Web->>Redis: "Comprobar Caché para user:123"
activate Redis
alt "Cache Hit (Datos encontrados)"
Redis-->>Web: "Retornar Datos del Usuario en Caché"
Web-->>Client: "200 OK (Respuesta Rápida)"
else "Cache Miss (Datos no encontrados)"
Redis-->>Web: "Nulo (No Encontrado)"
deactivate Redis
Web->>DB: "SELECT * FROM users WHERE id = 123"
activate DB
DB-->>Web: "Retornar Fila de Base de Datos"
deactivate DB
Web->>Redis: "SET Datos de user:123 (TTL: 60s)"
activate Redis
Redis-->>Web: "OK"
deactivate Redis
Web-->>Client: "200 OK (Respuesta Estándar)"
end
deactivate Web

Modelo matemático de la latencia (retraso en procesamiento)

Modelaremos matemáticamente el tiempo promedio de procesamiento de peticiones $T_{\text{total}}$ en el sistema anterior. Definimos la latencia de cada proceso de la siguiente manera:

$T_{\text{net}}$: Latencia de red entre el cliente y el contenedor web
$T_{\text{app}}$: Tiempo de procesamiento puro del lado de la aplicación (serialización, etc.)
$T_{\text{cache}}$: Tiempo requerido para leer y escribir en Redis
$T_{\text{db}}$: Tiempo requerido para ejecutar consultas en PostgreSQL
$p_{\text{miss}}$: Tasa de fallos en caché (cache miss rate) ($0 \le p_{\text{miss}} \le 1$)

Entonces, el tiempo promedio de respuesta se expresa mediante la siguiente fórmula de valor esperado:

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

En un entorno de desarrollo local (dentro de Docker), $T_{\text{net}}$ está cerca de 0. Sin embargo, lo que se debe notar es el rendimiento de E/S al usar montajes de enlace (bind mounts). Especialmente al usar Docker Desktop en Windows/macOS, $T_{\text{app}}$ (tiempo de lectura de código, etc.) tiende a inflarse debido a la sobrecarga de compartir archivos entre el sistema operativo anfitrión y la máquina virtual (contenedor). Para resolver este cuello de botella, se recomienda encarecidamente una arquitectura que coloque todo el código fuente en un volumen nombrado utilizando DevContainers, o ejecutar el motor de Docker nativamente en un entorno WSL2 (Windows Subsystem for Linux 2).

8. Optimización del rendimiento de la construcción en Docker: Estrategia de caché por capas

Al escribir un Dockerfile, si se comprende o no el mecanismo de “caché de capas (layer caching)”, el tiempo de construcción cambia drásticamente. Docker crea una diferencia en el sistema de archivos (capa) para cada instrucción del Dockerfile (como FROM, RUN, COPY) y la guarda como caché. Al volver a construir, se reutiliza la caché de las capas que no han cambiado.

El principio importante es “escribir en orden, comenzando por las cosas que cambian con menor frecuencia”.

Consideremos el modelado del impacto que los cambios en el código fuente tienen en el tiempo de construcción. Supongamos que el tiempo total de construcción es $T_{\text{build}}$, el tiempo de ejecución de cada paso es $T_{\text{layer}_i}$ y la existencia de un acierto de caché es un valor booleano $c_i \in \{0, 1\}$ (1 para aciertos de caché).

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

Una vez que ocurre un fallo de caché en la capa $k$ ($c_k = 0$), la caché se invalida ($c_j = 0$) para todas las capas subsecuentes $j > k$.

1
2
3
4


# Mal ejemplo (Copiando el código fuente primero)
COPY ./src /app/src
COPY pyproject.toml poetry.lock ./
RUN poetry install

En el caso anterior, con solo modificar una línea de código, se producirá un fallo de caché en el primer COPY, y el comando RUN poetry install, que consume mucho tiempo, se ejecutará cada vez.

1
2
3
4


# Buen ejemplo (Resolviendo las dependencias primero)
COPY pyproject.toml poetry.lock ./
RUN poetry install
COPY ./src /app/src

Si lo escribe de esta manera, incluso si cambia el código fuente, la caché de la capa de poetry install ($c_i = 1$) se mantendrá, lo que reduce drásticamente el tiempo de construcción de minutos a segundos.

9. Solución de problemas y consejos

Aquí listamos problemas comunes y soluciones encontrados al operar entornos locales.

Error de conflicto de puertos Si ocurre un error como Bind for 0.0.0.0:8000 failed: port is already allocated, otro proceso en su máquina local ya está usando ese puerto. Puede evitarlo cambiando el número de puerto en el lado del host, como ports: - "8080:8000".
Agotamiento del espacio en disco Si usa Docker por un largo período, las imágenes y volúmenes no utilizados (Dangling Images / Volumes) pueden acumularse y consumir decenas de GB de espacio en disco. Se recomienda limpiar el sistema regularmente con el siguiente comando.
1

docker system prune -a --volumes
Problemas de permisos de archivos Al usar montajes de enlace (bind mounts) en un entorno Linux, los archivos creados dentro del contenedor pueden ser propiedad de root, impidiendo que se editen en el lado del anfitrión. Puede resolver este problema creando un usuario sin privilegios en el Dockerfile y haciendo coincidir su UID/GID con el suyo en el sistema operativo anfitrión (por ejemplo: 1000:1000).

10. Conclusión: La mejora en la velocidad de desarrollo que trae la reproducibilidad

Al combinar Docker, Docker Compose y VSCode DevContainers, se logra un entorno de desarrollo local robusto donde “el estado será exactamente el mismo sin importar quién inicie el entorno”.

Llevar el paradigma de IaC a entornos locales no solo reduce el tiempo de configuración inicial. También elimina la ansiedad en torno a los cambios de configuración de infraestructura, facilita la experimentación con nuevas pilas tecnológicas y permite una transición fluida a las canalizaciones CI/CD, mejorando drásticamente la velocidad y la calidad de todo el ciclo de desarrollo.

Aprovechando las mejores prácticas explicadas en este artículo —como la optimización del tamaño de imagen con construcciones en múltiples etapas, el control de dependencias usando health checks y la redacción de un Dockerfile consciente de la caché de capas— lo animamos encarecidamente a introducir la mejor experiencia de desarrollo (DX: Developer Experience) en sus propios proyectos.

Guía de configuración definitiva del entorno de desarrollo para WSL2 (Windows Subsystem for Linux)

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

“WSL2 (Windows Subsystem for Linux 2)”, que proporciona un entorno de desarrollo nativo de Linux en Windows, se ha convertido en una herramienta indispensable en el desarrollo de software moderno. Sin embargo, existe una gran diferencia en el rendimiento y la experiencia de desarrollo entre usarlo en su estado predeterminado y aplicar los ajustes adecuados al comprender su arquitectura.

En este artículo, comenzando con una explicación de la arquitectura fundamental de WSL2, explicaremos exhaustivamente todos los pasos para construir el “entorno de desarrollo definitivo” exigido por ingenieros profesionales, abarcando configuraciones para maximizar el rendimiento, la construcción de un entorno de terminal cómodo, la integración perfecta con Docker y VS Code, y configuraciones de red avanzadas, en un volumen de más de 10,000 caracteres.

1. Arquitectura de WSL2 y su evolución desde WSL1

Para aprovechar todo el potencial de WSL2, es importante comprender primero su estructura interna. El enfoque para ejecutar binarios de Linux en Windows difiere fundamentalmente entre el WSL original (WSL1) y WSL2.

WSL1: Capa de traducción de llamadas al sistema

WSL1 adoptó un mecanismo que traducía (translation) las llamadas al sistema (system calls) de Linux a las APIs NT de Windows en tiempo real. Esto tenía la ventaja de una sobrecarga de recursos (overhead) muy pequeña porque no utilizaba máquinas virtuales (VM). Sin embargo, era difícil emular completamente llamadas al sistema complejas, como operaciones de E/S del sistema de archivos, lo que provocaba una degradación del rendimiento abismal, especialmente al manejar un gran número de archivos pequeños en procesos como npm install de Node.js u operaciones de repositorios de Git.

WSL2: Máquina Virtual de Utilidad Ligera y un Kernel de Linux completo

En WSL2, la arquitectura se renovó y un verdadero kernel de Linux construido por Microsoft ahora se ejecuta directamente sobre una “Máquina Virtual de Utilidad Ligera (Lightweight Utility VM)” que utiliza un subconjunto de la arquitectura de Hyper-V. Esto garantiza el 100% de compatibilidad de llamadas al sistema, y al utilizar un disco virtual (VHDX) que emplea el sistema de archivos nativo ext4 de Linux, el rendimiento de E/S de archivos ha mejorado drásticamente en comparación con WSL1.

El siguiente diagrama de Mermaid ilustra las diferencias estructurales entre WSL1 y WSL2.

flowchart TD
subgraph "Entorno del SO Windows"
A["Kernel de Windows NT"]
A --> F["Sistema de archivos NTFS (Disco C:)"]
end
subgraph "Arquitectura de WSL2"
B["Hipervisor de Hyper-V"]
B --> C["Máquina Virtual de Utilidad Ligera"]
C --> D["Kernel de Linux (Microsoft)"]
D --> E["Espacio de usuario de Ubuntu (glibc, bash, etc.)"]
D --> G["Disco virtual ext4 (.vhdx)"]
end
A -.->|"Recurso compartido de archivos de red del protocolo Plan 9 (9P)"| D
style B fill:#f9f,stroke:#333,stroke-width:2px
style D fill:#bbf,stroke:#333,stroke-width:2px

Una lección importante de esta estructura es que “el acceso a los archivos en el lado de Linux (dentro del VHDX) es extremadamente rápido, pero el acceso a los archivos en el lado de Windows (/mnt/c/) es muy lento porque pasa por el protocolo 9P”. El código fuente de tus proyectos siempre debe ubicarse bajo el directorio de inicio (~) en el lado de WSL.

2. Análisis matemático del rendimiento: ¿Por qué WSL2 es rápido?

Evaluemos cuantitativamente la mejora de rendimiento de WSL2 utilizando un modelo matemático. En el desarrollo de software, una de las operaciones que más tiempo consume es el procesamiento que implica operaciones intensivas de E/S de archivos (por ejemplo, instalación de bibliotecas o compilación).

El tiempo total de ejecución de cierto proceso $T_{total}$ se expresa como la suma del tiempo computacional por la CPU $T_{compute}$ y el tiempo que tardan las operaciones de E/S de disco $T_{io}$.

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

En el caso de WSL1, se produce una sobrecarga para traducir las operaciones del lado de Linux en operaciones NTFS, por lo que el tiempo de E/S se modela de la siguiente manera. Aquí, $n$ es el número de operaciones de archivo, $t_{ntfs\_syscall}$ es el tiempo de ejecución de la llamada al sistema en el lado de Windows y $t_{trans}$ es la sobrecarga de la capa de traducción.

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

Por otro lado, en el caso de WSL2, dado que el kernel emite E/S directamente al sistema de archivos ext4, la sobrecarga es solo el ligero retraso $t_{virt}$ debido a la virtualización.

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

En los sistemas de archivos generales, como $t_{ext4} \ll t_{ntfs\_syscall} + t_{trans}$, cuando $n$ es muy grande (realizando decenas de miles a cientos de miles de operaciones de archivo), la diferencia en el tiempo de E/S entre WSL1 y WSL2 crece exponencialmente.

Además, si la relación de sobrecarga del cálculo de la CPU en el entorno de virtualización es $\rho$, en la virtualización asistida por hardware moderna (Intel VT-x / AMD-V) se sitúa en alrededor de $\rho \approx 0.01 \sim 0.03$ (1 a 3%). Por lo tanto, incluso en tareas puramente computacionales, ofrece un rendimiento del $97\% \sim 99\%$, que es comparable al de un entorno Linux nativo.

3. Instalación y construcción de la base

En Windows 10/11, la instalación de WSL2 se ha vuelto muy sencilla. Simplemente abre PowerShell con privilegios de administrador y ejecuta el siguiente comando.

1
2
3
4
5
6


# WSL2 y Ubuntu se instalarán por defecto
wsl --install

# Si especificas una distribución en particular
# Se puede comprobar con wsl --list --online
wsl --install -d Ubuntu-24.04

Después de la instalación, tras reiniciar, se te pedirá que configures un nombre de usuario y una contraseña de UNIX en el primer inicio. Este usuario es independiente del usuario de Windows y sólo es válido dentro de WSL.

Si ya estás usando WSL1, conviértelo a WSL2 con los siguientes comandos.

1
2
3
4
5


# Convierte una distribución existente a WSL2
wsl --set-version Ubuntu 2

# Establece WSL2 como versión por defecto para las distribuciones que añadas en el futuro
wsl --set-default-version 2

4. El secreto del control de recursos: .wslconfig y wsl.conf

Una de las mayores trampas de WSL2 es el “consumo ilimitado de memoria (el aumento de tamaño del proceso Vmmem)”. Como WSL2 utiliza la caché de páginas (page cache) del kernel de Linux, devora la memoria del host (Windows) sin cesar cada vez que realiza E/S. Para evitar esto, es imprescindible limitar los recursos usando un archivo de configuración.

Los archivos de configuración de WSL2 se dividen en dos: .wslconfig que afecta a todo Windows y wsl.conf que afecta al interior de cada distribución.

4.1. .wslconfig (Lado de Windows)

Crea un archivo en el directorio de perfil de usuario de Windows (C:\Users\<nombre_de_usuario>\.wslconfig) para controlar la asignación de recursos a la máquina virtual.

 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\<nombre_de_usuario>\.wslconfig
[wsl2]
# Cantidad máxima de memoria para asignar a la VM. Se recomienda alrededor del 50% al 75% de la memoria total del host
memory=16GB

# Número de núcleos de CPU a utilizar (si se omite, se usarán todos)
processors=8

# Tamaño del archivo de intercambio (swap)
swap=8GB

# Destino donde guardar el archivo de intercambio (si quieres ahorrar espacio en el disco C)
# swapfile=D:\\wsl\\swap.vhdx

# Habilitar el reenvío de localhost (para acceder a WSL desde Windows a través de localhost)
localhostForwarding=true

# Liberar memoria automáticamente (solo Windows 11)
# Libera dinámicamente la caché de páginas y previene el crecimiento excesivo de Vmmem
autoMemoryReclaim=dropcache

[experimental]
# Funciones de red avanzadas disponibles en Windows 11 22H2 y posteriores
# Esto habilita el soporte de IPv6 y compartir la misma dirección IP entre WSL y Windows
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

4.2. wsl.conf (Lado de Linux)

Edita /etc/wsl.conf dentro de WSL para controlar el comportamiento específico de la distribución.

 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 (editar dentro de WSL)
[network]
# Deshabilitar la generación automática de /etc/resolv.conf al iniciar WSL
# Útil si quieres establecer tu propio DNS (ej. 8.8.8.8)
generateResolvConf=false

# Establecer tu propio nombre de host
hostname=WSL-DevNode

[automount]
# Configuración para cuando se montan unidades de Windows
enabled=true
options="metadata,uid=1000,gid=1000,umask=022"
# Cambiar el punto de montaje de la unidad C de /mnt/c a /c (hace la ruta más corta)
root=/

[boot]
# Habilitar systemd (WSL 0.67.6 y posteriores)
# Esto permite que snap y varios demonios (Docker, etc.) se ejecuten de forma nativa
systemd=true

[user]
# El usuario que inicia sesión por defecto
default=kenji

Para aplicar estas configuraciones, es necesario ejecutar wsl --shutdown en PowerShell para detener por completo la máquina virtual de WSL y luego reiniciarla.

5. El entorno de terminal definitivo: Zsh + Powerlevel10k

La productividad no mejorará con bash por defecto. Combinaremos Zsh, que cuenta con una gran capacidad de autocompletado y visibilidad, con el ultrarrápido tema “Powerlevel10k” para construir el prompt más potente.

5.1. Introducción y configuración de Windows Terminal

Instala “Windows Terminal” desde Microsoft Store. Abre la configuración JSON (settings.json), establece el perfil predeterminado en WSL (Ubuntu) y cambia la fuente a una fuente Nerd para desarrollo (por ejemplo: HackGen Console NF o MesloLGS NF).

5.2. Instalación de Zsh y Oh My Zsh

Ejecuta los siguientes comandos en el terminal de WSL.

1
2
3
4
5
6


# Actualizar los paquetes e instalar Zsh
sudo apt update && sudo apt upgrade -y
sudo apt install -y zsh git curl

# Ejecutar el script de instalación de Oh My Zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

5.3. Introducción a Powerlevel10k y plugins

Instala el tema Powerlevel10k y plugins (resaltado de sintaxis y autocompletado) que potencian aún más a Zsh.

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

Edita ~/.zshrc y activa el tema y los plugins.

1
2
3
4
5


# Cambios en ~/.zshrc
ZSH_THEME="powerlevel10k/powerlevel10k"

# Añadir a la matriz (array) de plugins
plugins=(git zsh-autosuggestions zsh-syntax-highlighting)

Al guardar y ejecutar source ~/.zshrc, se iniciará el asistente de configuración de Powerlevel10k (p10k configure). Sigue las instrucciones en pantalla para personalizar el prompt a tu gusto (estilo del prompt, con o sin iconos, información que mostrar, etc.). Podrás ver en tiempo real el nombre de la rama (branch) y el estado de Git, la versión de Node.js, el tiempo de ejecución del comando, lo que aumentará espectacularmente tu eficiencia en el desarrollo.

6. VS Code Remote - Integración perfecta con WSL

En el desarrollo con WSL2, la extensión “Remote - WSL” proporciona el mecanismo para acceder sin problemas a los archivos dentro de WSL desde un IDE (Visual Studio Code) instalado en el lado de Windows.

Explicación de la arquitectura

El siguiente diagrama de secuencia muestra cómo VS Code se comunica con WSL2.

sequenceDiagram
autonumber
participant U as "Desarrollador"
participant V as "Interfaz de usuario de VS Code (Windows)"
participant S as "Servidor de VS Code (WSL2)"
participant F as "Sistema de archivos ext4 (WSL2)"
U->>V: "Escribe `code .` en el terminal de WSL"
V->>S: "Establece una conexión RPC a través de Vsock"
Note over V,S: Se comunica a través de un socket de Hyper-V sin utilizar TCP/IP
S->>F: "Lee archivos fuente / Ejecuta el linter"
F-->>S: "Devuelve datos y análisis"
S-->>V: "Transmite los resultados del servidor de idiomas a la interfaz de usuario"
V-->>U: "Muestra resaltado de sintaxis y errores"

El VS Code en el lado de Windows funciona simplemente como un “cliente ligero (thin client / UI)”, mientras que el procesamiento pesado, como el Language Server, el depurador (debugger) y la ejecución del terminal, son procesados íntegramente por el “Servidor de VS Code” en el lado de WSL. Esto te permite mantener tu entorno del lado de WSL limpio sin tener que instalar Node.js o Python en el lado de Windows.

Configuraciones obligatorias en VS Code

Instala “WSL” (ms-vscode-remote.remote-wsl) desde la sección “Extensiones” de VS Code. Luego, ve al directorio del proyecto en el terminal de WSL y simplemente ejecuta code ., el VS Code del lado de Windows se abrirá en ese directorio.

Nota importante (El problema del código de salto de línea): Los códigos de salto de línea difieren entre Windows y Linux (Windows es CRLF, Linux es LF). Si estás desarrollando en WSL, asegúrate siempre de unificar la configuración core.autocrlf de Git o la configuración de archivos por defecto de VS Code a LF. Si omites este paso, sufrirás errores misteriosos al ejecutar scripts de shell o contenedores de Docker.

1
2


# Configuración del código de salto de línea para Git en el lado de WSL
git config --global core.autocrlf input

Añade también lo siguiente en settings.json (configuración remota) de VS Code.

1
2
3
4


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

7. Optimización de Docker Desktop e Integración con WSL2

Hay dos enfoques principales para usar Docker en el entorno WSL2:

Instalar Docker Desktop for Windows y habilitar la función de integración con WSL2.
Instalar el Docker Engine nativo directamente dentro de WSL2 (Ubuntu, etc.).

Enfoque 1: Docker Desktop (Recomendado)

Se suele recomendar esto en muchos casos porque facilita la gestión mediante interfaz gráfica (GUI) y el acceso transparente de los contenedores entre Windows/WSL. Verifica lo siguiente en la configuración de Docker Desktop (Settings).

Marca la casilla de General -> Use the WSL 2 based engine.
Marca la casilla de Resources -> WSL Integration -> Enable integration with my default WSL distro y activa el interruptor (toggle button) de la distribución que vas a usar (Ubuntu).

Esto te permitirá ejecutar el comando docker directamente desde el terminal de WSL2 y la comunicación con el demonio de Docker (Docker daemon) se realizará a través de máquinas virtuales ligeras y exclusivas (docker-desktop y docker-desktop-data) gestionadas por Docker Desktop.

Enfoque 2: Instalación directa de Docker Engine nativo

Si tienes restricciones por parte de la red corporativa (como evadir los costos de licencia de Docker Desktop) o deseas reducir la sobrecarga de rendimiento al extremo, instala Docker puramente como un servidor Ubuntu con systemd habilitado en /etc/wsl.conf.

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


# Fragmento de los pasos oficiales de instalación de Docker en WSL2 Ubuntu con systemd habilitado
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

# Agregar el repositorio
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

# Agregar el usuario actual al grupo docker (para ejecutar sin sudo)
sudo usermod -aG docker $USER

Después de reiniciar, systemctl start docker funcionará exactamente igual que en un entorno Linux nativo, ofreciendo un alto rendimiento.

8. Integración de claves SSH: Autenticación perfecta entre Windows y WSL

Al hacer clones SSH de Git o conectarse por SSH a un servidor remoto, resulta muy molesto gestionar claves SSH separadas entre el lado de Windows y el lado de WSL. Para equilibrar seguridad y conveniencia, configuraremos un puente (bridge) para el agente SSH que se ejecuta en el lado de Windows (o un gestor de contraseñas como 1Password) hacia el lado de WSL.

Aquí explicaremos cómo reenviar al socket de dominio UNIX (UNIX domain socket) de WSL2 mediante npiperelay o socat, empleando la función del agente SSH de 1Password o el Agente de autenticación de OpenSSH de Windows, como los enfoques más modernos y seguros.

Reenvío de sockets de ssh-agent

Normalmente, el agente SSH proporcionado como una tubería con nombre (Named Pipe) en Windows debe convertirse en un archivo de socket (socket file) en el lado de WSL. Es fácil utilizando la función de wsl-ssh-agent o la proporcionada por 1Password.

En la pantalla de configuración de 1Password, ve a “Desarrollador (Developer)” -> habilita “Usar el agente SSH (Use SSH agent)”. Luego, añade la siguiente configuración a ~/.zshrc o ~/.bashrc en el lado de WSL, para enlazar el socket automáticamente al iniciar sesión.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Apunte en ~/.zshrc (Ejemplo usando 1Password SSH Agent)
export SSH_AUTH_SOCK=$HOME/.ssh/agent.sock
# Usar socat y npiperelay para reenviar si el socket no existe o el proceso no está enlazado al iniciar 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
 # Inicia socat en segundo plano (background) y conecta la tubería con nombre del lado de Windows al socket UNIX del lado de WSL
 (setsid socat UNIX-LISTEN:$SSH_AUTH_SOCK,fork EXEC:"npiperelay.exe -ei -s //./pipe/openssh-ssh-agent",nofork &) >/dev/null 2>&1
fi

Es necesario instalar de antemano npiperelay.exe en el lado de Windows y añadirlo a la variable PATH (ruta).

Una vez completada esta configuración, al ejecutar ssh-add -l desde el terminal de WSL, se mostrará una lista de claves públicas de las claves SSH registradas en 1Password o en el lado de Windows. Esto permite pasar la autenticación de forma segura sin copiar el archivo de la clave privada (private key) al interior de WSL.

9. Mantenimiento: Optimización (Compresión) de un VHDX inflado

Una de las mayores desventajas de WSL2 es la especificación en la que “el tamaño de archivo del disco virtual (.vhdx) del lado de Windows no se reduce automáticamente incluso al eliminar imágenes de Docker o borrar archivos”. Si el desarrollo continúa durante mucho tiempo, el archivo ext4.vhdx se hincha de decenas a cientos de GB.

Para liberar espacio en disco, es necesario optimizar (comprimir - Compact) el VHDX periódicamente desde el lado de Windows.

En primer lugar, apaga WSL por completo.
1

wsl --shutdown
Abre PowerShell con privilegios de administrador y ejecuta el siguiente comando diskpart, o el comando Optimize-VHD del módulo de Hyper-V (este último solo se puede utilizar si Hyper-V está activado).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Si el módulo Hyper-V está disponible
Optimize-VHD -Path "$env:LOCALAPPDATA\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx" -Mode Full

# Si usas diskpart
diskpart
# Escribe interactivamente en la siguiente línea de comandos
DISKPART> select vdisk file="C:\Users\<nombre_de_usuario>\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx"
DISKPART> attach vdisk readonly
DISKPART> compact vdisk
DISKPART> detach vdisk
DISKPART> exit

Realizar esta operación de forma regular te permitirá recuperar la capacidad desperdiciada del disco C.

10. Conclusión

WSL2 ha superado por completo los límites de ser solo un “extra de Linux ejecutándose en Windows” y ha evolucionado hacia una potente plataforma de desarrollo equivalente, o incluso superior, a un sistema MacOS o Linux nativo.

Al aplicar todas las configuraciones explicadas en este momento (optimización de recursos mediante .wslconfig, potenciación del terminal con Zsh + Powerlevel10k, acceso transparente con VS Code Remote y mantenimiento de VHDX e integración de SSH), se completará el “entorno de desarrollo definitivo”, sin estrés, rápido y seguro.

Lleva un poco de tiempo configurarlo, pero una vez que hayas solidificado la configuración, no hay duda de que la productividad de la ingeniería mejorará drásticamente en el futuro. Anímate y explora futuras personalizaciones basadas en esta guía, según tus preferencias y proyectos.