Docker on kenji.blog

Passos para Construir um Ambiente de Desenvolvimento Local Reprodutível usando Docker

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

1. Introdução: Rompendo com o “Na minha máquina funciona”

No ambiente de desenvolvimento de software, o problema de “Na minha máquina funciona” (It works on my machine), causado por diferenças de ambiente entre os desenvolvedores, tem sido um fator de desperdício de tempo em muitos projetos por um longo período. Diferenças de sistema operacional, versões de linguagens instaladas, dependências de bibliotecas e conflitos de ferramentas instaladas globalmente fazem com que o ambiente local esteja sempre exposto à “incerteza de estado”.

O que resolve fundamentalmente esses desafios são as tecnologias de contêineres, como o Docker, e o paradigma de Infrastructure as Code (IaC). Ao conteinerizar o ambiente de desenvolvimento local, é possível alcançar isolamento em nível de SO e gerenciar a versão do ambiente em si junto com a base de código.

Neste artigo, utilizando Docker, Docker Compose e VSCode DevContainers, explicaremos de forma minuciosa os passos para construir um “ambiente de desenvolvimento local reprodutível em que o estado será exatamente o mesmo, não importando quem, quando ou em qual máquina ele for iniciado”, juntamente com os profundos mecanismos técnicos por trás disso, incluindo perspectivas matemáticas.

2. A Afinidade entre Infrastructure as Code (IaC) e a Tecnologia de Contêineres

Princípios do IaC e sua Aplicação ao Ambiente Local

Infrastructure as Code (IaC) é a abordagem de gerenciar a configuração e o provisionamento da infraestrutura através de arquivos de definição legíveis por máquina, em vez de processos manuais. Os princípios centrais do IaC incluem os seguintes elementos:

Abordagem Declarativa (Declarative Approach): Define “como o estado final deve ser” em vez de “como alterar o estado”.
Idempotência (Idempotency): Não importa quantas vezes o script seja executado, o mesmo resultado (estado) é sempre garantido.
Controle de Versão (Version Control): O estado da infraestrutura é salvo como código em um VCS, como o Git, permitindo o rastreamento do histórico de alterações e a revisão por pares.

Praticar IaC no ambiente de desenvolvimento local significa codificar o “estado ideal” do ambiente de desenvolvimento usando Dockerfile, docker-compose.yml e devcontainer.json. Isso proporciona uma experiência de integração (onboarding) na qual os novos membros da equipe podem clonar o repositório e executar apenas um comando para começar a desenvolver imediatamente.

Recursos do Kernel que Suportam a Tecnologia de Contêineres

A tecnologia de contêineres, diferente da virtualização baseada em hypervisor como as máquinas virtuais (VMs), é uma tecnologia de virtualização leve que isola os processos enquanto compartilha o kernel do SO hospedeiro. Para realizar isso, os seguintes recursos do kernel do Linux são usados principalmente:

Namespaces: Fornece visualizações independentes dos recursos do sistema (PID, rede, pontos de montagem, usuários, etc.) para cada processo.
Cgroups (Control Groups): Limita e aloca os recursos físicos (CPU, memória, E/S de disco, etc.) que um processo pode usar.
UnionFS (Union File System): Uma tecnologia que sobrepõe transparentemente várias árvores de diretórios (camadas) e as apresenta como um único sistema de arquivos. As camadas de imagem do Docker dependem dessa tecnologia.

Vamos considerar um modelo matemático para a restrição de recursos. Seja $M_{\text{total}}$ a capacidade total de memória da máquina host e $m_i$ o limite de memória para $n$ contêineres rodando no host. A condição necessária para que o sistema opere de forma estável, considerando a memória base $M_{\text{os}}$ consumida pelo SO host e outros processos, pode ser expressa pela seguinte inequação:

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

Ao definir estritamente $m_i$ para cada contêiner usando Cgroups, mesmo que um contêiner específico cause um vazamento de memória, podemos evitar que o OOM (Out Of Memory) Killer derrube outros contêineres ou o sistema host inteiro.

3. Design Eficiente do Dockerfile: Dominando os Multi-stage Builds

O primeiro passo para um ambiente reprodutivo é o design do Dockerfile que define o ambiente de execução da aplicação. Aqui, usando Python (FastAPI) como exemplo, explicaremos as melhores práticas para um Dockerfile seguro e leve utilizando multi-stage builds (builds de múltiplos estágios).

O multi-stage build é uma técnica que usa várias instruções FROM em um único Dockerfile para separar o ambiente de build (um ambiente pesado contendo compiladores e ferramentas de desenvolvimento) do ambiente de execução (um ambiente leve contendo apenas os artefatos necessários).

Exemplo Prático de Dockerfile para Python FastAPI

O código a seguir é um exemplo de um Dockerfile avançado que combina o gerenciamento de dependências com o Poetry e 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 (Ambiente de build)
# ---------------------------------------------------------
FROM python:3.11-slim AS builder

# Configuração de variáveis de ambiente necessárias
ENV PYTHONUNBUFFERED=1 \
 PYTHONDONTWRITEBYTECODE=1 \
 POETRY_VERSION=1.6.1 \
 POETRY_HOME="/opt/poetry" \
 POETRY_VIRTUALENVS_IN_PROJECT=true \
 POETRY_NO_INTERACTION=1

# Instalação de pacotes dependentes
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

# Cópia dos arquivos de dependência e instalação
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-root --only main

# ---------------------------------------------------------
# Stage 2: Runtime (Ambiente de execução)
# ---------------------------------------------------------
FROM python:3.11-slim AS runtime

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

# Criação de um usuário sem privilégios mínimos
RUN groupadd -r appuser && useradd -r -g appuser appuser

WORKDIR /app

# Copia apenas o ambiente virtual (dependências) do builder
COPY --from=builder --chown=appuser:appuser /app/.venv /app/.venv

# Cópia do código da aplicação
COPY --chown=appuser:appuser ./src /app/src

# Mudança para o usuário sem privilégios
USER appuser

# Comando padrão ao iniciar o contêiner
ENTRYPOINT ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

Avaliação Matemática do Tamanho da Imagem por Multi-stage Build

Seja $S_{\text{single}}$ o tamanho da imagem quando construída em um único estágio, e $S_{\text{multi}}$ o tamanho da imagem quando o multi-stage build é aplicado. A taxa de redução de tamanho $R$ é calculada da seguinte forma:

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

Por exemplo, suponha que $S_{\text{single}}$ inclua a imagem base do SO (cerca de 110 MB), pacotes de desenvolvimento (como gcc, cerca de 150 MB), o próprio Poetry (cerca de 40 MB), as bibliotecas dependentes do projeto (cerca de 80 MB) e o código fonte (cerca de 5 MB), totalizando 385 MB. Por outro lado, em $S_{\text{multi}}$, apenas as bibliotecas dependentes (80 MB) e o código fonte (5 MB) são copiados para a imagem base (110 MB), resultando em um total de 195 MB.

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

Dessa forma, introduzir o multi-stage build pode reduzir o tamanho da imagem pela metade. A redução do tamanho da imagem traduz-se diretamente em tempos de pull mais curtos do registro, economia de espaço em disco e melhor segurança devido à redução da superfície de ataque (Attack Surface).

4. Orquestração de Múltiplos Contêineres com Docker Compose

No desenvolvimento moderno de aplicações web, arquiteturas de microsserviços em que vários componentes colaboram, como servidores web, bancos de dados e servidores de cache, são comuns. Para gerenciá-los centralmente no ambiente local, usamos o docker-compose.yml.

Desta vez, construiremos localmente um sistema de 3 camadas com “Web (FastAPI)”, “Database (PostgreSQL)” e “Cache (Redis)”.

Diagrama de Arquitetura (Mermaid)

O diagrama abaixo é um diagrama de blocos que representa o relacionamento entre cada contêiner, a rede e os volumes na máquina local.

graph TD
User["Máquina Host (Navegador/curl)"] -->|Localhost:8000| Web["Contêiner Web FastAPI"]
subgraph "Rede Bridge do Docker (app-network)"
Web -->|Porta 5432| DB["Contêiner PostgreSQL"]
Web -->|Porta 6379| Redis["Contêiner Redis"]
end
DB --> Volume1["Volume Nomeado (postgres_data)"]
Redis --> Volume2["Volume Nomeado (redis_data)"]
HostDir["Código Fonte do Host (./src)"] -.->|Bind Mount| Web

Implementação e Explicação Detalhada do docker-compose.yml

Abaixo, é mostrado um exemplo de um docker-compose.yml robusto que pode suportar a construção de um ambiente prático.

 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  # Monta o código do host como somente leitura (para hot reload)
 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 (Volumes) e Persistência de Dados

Por princípio, os contêineres são “sem estado” (stateless) e “efêmeros” (ephemeral). Quando um contêiner é destruído, os dados internos também são perdidos. Para reter dados do banco de dados ou caches, é necessário montar uma área do sistema de arquivos da máquina host no contêiner.

Bind Mount (Montagem de Ligação): O ./src:/app/src:ro no serviço web acima se enquadra nisso. Ele mapeia um diretório específico do host diretamente para dentro do contêiner. Usado para refletir as edições de código local imediatamente no contêiner (hot reload). Do ponto de vista de segurança, a melhor prática é adicionar a opção :ro (Read-Only) para evitar que o código fonte do host seja modificado a partir do contêiner.
Named Volume (Volume Nomeado): postgres_data e redis_data se enquadram nisso. É uma área gerenciada internamente pelo Docker (por exemplo, /var/lib/docker/volumes/), com desempenho de E/S superior aos bind mounts e absorve as diferenças de sistema de arquivos entre os SOs. Sempre use este método para a persistência de bancos de dados.

Rede (Networking) e Descoberta de Serviços

O Docker Compose cria, por padrão, uma rede de ponte (bridge network) exclusiva para cada projeto. É a app-network mencionada acima. Contêineres pertencentes à mesma rede podem resolver nomes (resolução DNS) usando o “nome do serviço” (ex: db, redis) como hostname, em vez do endereço IP. Por exemplo, do contêiner Web, é possível acessar o banco de dados pela URL postgresql://postgres:password@db:5432/mydb. Isso torna possível alternar os destinos de conexão de forma transparente por meio de variáveis de ambiente, tanto no ambiente local quanto em produção.

Verificação de Integridade (Healthcheck) e Controle da Ordem de Inicialização

A diretiva depends_on controla a ordem de inicialização dos contêineres, mas apenas especificar depends_on fará com que o contêiner Web seja iniciado assim que o “contêiner do DB for iniciado”. Na realidade, o processo de inicialização do DB (início do processo do PostgreSQL e preparação das tabelas) leva vários segundos, o que pode causar erros de conexão do DB a partir do contêiner Web. Para evitar isso, é possível definir um healthcheck e especificar condition: service_healthy para iniciar o contêiner Web apenas após confirmar que “o DB está em um estado em que pode aceitar requisições de conexão”.

5. Gerenciamento de Variáveis de Ambiente e Segurança (.env)

O hardcoding de informações sensíveis, como senhas de banco de dados e chaves de API, no docker-compose.yml é um antipadrão que deve ser evitado a todo custo. Em vez disso, usamos um arquivo de variáveis de ambiente .env para injetar esses valores.

Crie um arquivo .env na raiz do projeto.

1
2
3
4


# Arquivo .env (Lembre-se de adicioná-lo ao .gitignore para não ser gerenciado pelo Git)
POSTGRES_PASSWORD=supersecretpassword
POSTGRES_DB=devdb
API_SECRET_KEY=dev_secret_key_12345

O Docker Compose lê, por padrão, o arquivo .env localizado no diretório de execução e expande os espaços reservados ${VAR_NAME} dentro do arquivo YAML. Com este método, é possível gerenciar com segurança valores de configuração diferentes para cada ambiente (como local, staging e produção) sem alterar o código da infraestrutura.

6. A Melhor Experiência de Desenvolvimento com VSCode DevContainers

Até aqui, construímos um ambiente de backend robusto usando Docker. No entanto, podemos ir um passo além. Utilizando o recurso VSCode DevContainers (Remote - Containers), torna-se possível executar o próprio backend do editor (VSCode) dentro do contêiner.

Isso elimina a necessidade de instalar sequer o Python ou Node.js na máquina local e permite que tudo, desde linters (flake8/eslint) e formatadores (black/prettier) até extensões da IDE, seja definido dentro da base de código e compartilhado com toda a equipe.

Configuração do devcontainer.json

Crie um diretório .devcontainer na raiz do projeto e coloque o arquivo de configuração dentro dele.

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

Ao incluir este arquivo no repositório, no momento em que você abre o projeto no VSCode, um prompt “Reopen in Container” será exibido. Com apenas um clique, todos os contêineres necessários são iniciados, as extensões são instaladas e você estará imediatamente pronto para começar a codificar. É uma experiência verdadeiramente mágica.

7. Sequência de Processamento de Requisições e Modelagem de Desempenho

Vamos verificar o ciclo de vida do processamento de requisições da aplicação web no ambiente de desenvolvimento local construído com um diagrama de sequência e considerar o modelo matemático de seu desempenho.

Diagrama de Sequência (Fluxo de Requisições)

sequenceDiagram
participant Client as "Navegador / 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: "Verificar Cache para user:123"
activate Redis
alt "Cache Hit (Dados encontrados)"
Redis-->>Web: "Retornar Dados de Usuário em Cache"
Web-->>Client: "200 OK (Resposta Rápida)"
else "Cache Miss (Dados não encontrados)"
Redis-->>Web: "Nulo (Não Encontrado)"
deactivate Redis
Web->>DB: "SELECT * FROM users WHERE id = 123"
activate DB
DB-->>Web: "Retornar Linha do Banco de Dados"
deactivate DB
Web->>Redis: "SET user:123 Data (TTL: 60s)"
activate Redis
Redis-->>Web: "OK"
deactivate Redis
Web-->>Client: "200 OK (Resposta Padrão)"
end
deactivate Web

Modelo Matemático de Atraso de Processamento (Latência)

Modelaremos matematicamente o tempo médio de processamento de requisições $T_{\text{total}}$ no sistema acima. A latência de cada processamento é definida a seguir:

$T_{\text{net}}$: Latência de rede entre o cliente e o contêiner Web
$T_{\text{app}}$: Tempo de processamento puro no lado da aplicação (como serialização)
$T_{\text{cache}}$: Tempo gasto lendo e escrevendo no Redis
$T_{\text{db}}$: Tempo gasto na execução de consultas ao PostgreSQL
$p_{\text{miss}}$: Taxa de cache miss ($0 \le p_{\text{miss}} \le 1$)

O tempo médio de resposta é expresso pela seguinte 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}}) $$

No ambiente de desenvolvimento local (dentro do Docker), $T_{\text{net}}$ fica quase próximo a 0, mas o que deve ser notado é a performance de E/S durante o bind mount. Especialmente ao usar o Docker Desktop no Windows/macOS, devido ao overhead de compartilhamento de arquivos entre o SO host e a VM (contêiner), $T_{\text{app}}$ (tempo de carregamento do código, etc.) tende a se tornar inflado. Para eliminar esse gargalo de desempenho, é altamente recomendada uma arquitetura que utilize DevContainers, conforme mencionado anteriormente, colocando todo o código fonte dentro de um volume nomeado ou executando a engine do Docker nativamente em um ambiente WSL2 (Windows Subsystem for Linux 2).

8. Otimização do Desempenho do Build do Docker: Estratégia de Cache de Camadas

Ao escrever um Dockerfile, entender o mecanismo de “cache de camadas” muda drasticamente o tempo de build. O Docker cria um diferencial de sistema de arquivos (camada) para cada instrução no Dockerfile (FROM, RUN, COPY, etc.) e a retém como cache. Nas reconstruções, o cache das camadas inalteradas é reutilizado.

O princípio importante é “escrever as instruções em ordem crescente da frequência de alterações”.

Vamos considerar a modelagem do impacto das alterações do código fonte no tempo de build. Seja o tempo total de build $T_{\text{build}}$, o tempo de execução de cada etapa $T_{\text{layer}_i}$ e a presença ou ausência do cache hit o valor booleano $c_i \in \{0, 1\}$ (1 quando houver cache hit).

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

Uma vez que ocorre um cache miss ($c_k = 0$) na camada $k$, o cache é invalidado ($c_j = 0$) para todas as camadas subsequentes $j > k$.

1
2
3
4


# Exemplo ruim (Copiando o código fonte primeiro)
COPY ./src /app/src
COPY pyproject.toml poetry.lock ./
RUN poetry install

Neste caso, mudar apenas uma linha de código causará um cache miss na primeira instrução COPY, resultando na demorada instrução RUN poetry install sendo executada a cada vez.

1
2
3
4


# Bom exemplo (Resolvendo as dependências primeiro)
COPY pyproject.toml poetry.lock ./
RUN poetry install
COPY ./src /app/src

Se for escrito dessa forma, mesmo que o código fonte seja alterado, o cache da camada para o poetry install ($c_i = 1$) será efetivo, e o tempo de build será reduzido drasticamente de minutos para segundos.

9. Solução de Problemas e Dicas (Troubleshooting)

Aqui estão problemas comuns e soluções ao operar em um ambiente local.

Erro de Conflito de Portas Se ocorrer um erro como Bind for 0.0.0.0:8000 failed: port is already allocated, outro processo na máquina local está usando essa porta. Você pode evitar isso alterando o número da porta do lado do host para algo como ports: - "8080:8000".
Esgotamento do Espaço em Disco Ao usar o Docker por um longo tempo, imagens ou volumes não utilizados (Dangling Images / Volumes) podem se acumular, consumindo dezenas de GB do espaço em disco. Recomenda-se limpar regularmente o sistema com o seguinte comando:
1

docker system prune -a --volumes
Problema de Permissões de Arquivos Ao usar bind mounts no ambiente Linux, o proprietário dos arquivos criados no contêiner será root, e não será possível editá-los no lado do host. Você pode resolver isso criando um usuário sem privilégios no Dockerfile que coincida com o seu próprio UID/GID do SO host (ex: 1000:1000).

10. Conclusão: A Melhoria na Velocidade de Desenvolvimento Trazida pela Reprodutibilidade

Ao combinar o Docker, Docker Compose e VSCode DevContainers, um ambiente de desenvolvimento local robusto é alcançado, onde “não importa quem inicie o ambiente, o estado será perfeitamente o mesmo”.

Trazer o paradigma IaC para o ambiente local não reduz apenas o tempo de configuração inicial. Ele melhora drasticamente a velocidade e a qualidade de todo o ciclo de desenvolvimento, removendo a ansiedade em relação às mudanças de configuração da infraestrutura, facilitando a experimentação de novas pilhas de tecnologias e possibilitando uma transição suave para as pipelines de CI/CD.

Utilize as melhores práticas explicadas neste artigo, como a otimização do tamanho da imagem por meio de multi-stage builds, controle de dependências usando healthchecks e a escrita do Dockerfile focada no cache de camadas, e, com certeza, implemente a melhor experiência de desenvolvimento (DX: Developer Experience) em seu próprio projeto.

Guia de Configuração Definitivo do Ambiente de Desenvolvimento para WSL2 (Windows Subsystem for Linux)

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

O “WSL2 (Windows Subsystem for Linux 2)”, que fornece um ambiente de desenvolvimento nativo do Linux no Windows, tornou-se uma ferramenta indispensável no desenvolvimento de software moderno. No entanto, há uma diferença imensa em desempenho e experiência de desenvolvimento entre usá-lo em seu estado padrão e ajustá-lo adequadamente após entender sua arquitetura.

Neste artigo, explicaremos detalhadamente todo o processo para construir o “ambiente de desenvolvimento definitivo” exigido por engenheiros profissionais. Começando com uma explicação da arquitetura fundamental do WSL2, abordaremos configurações para maximizar o desempenho, a construção de um ambiente de terminal confortável, a integração perfeita com Docker e VS Code, e configurações avançadas de rede.

1. A Arquitetura do WSL2 e a Evolução a partir do WSL1

Para extrair totalmente o potencial do WSL2, é importante primeiro entender sua estrutura interna. O WSL original (WSL1) e o WSL2 têm abordagens fundamentalmente diferentes para executar binários do Linux no Windows.

WSL1: Camada de Tradução de Chamadas de Sistema

O WSL1 adotava um mecanismo que traduzia chamadas de sistema do Linux para a API NT do Windows em tempo real. Isso tinha a vantagem de uma sobrecarga de recursos muito baixa, já que não usava uma máquina virtual (VM). No entanto, era difícil emular perfeitamente chamadas de sistema complexas, como operações de E/S do sistema de arquivos, resultando em uma degradação de desempenho terrível ao lidar com um grande número de arquivos pequenos, como npm install do Node.js ou operações de repositório do Git.

WSL2: VM Utilitária Leve e Kernel Linux Completo

No WSL2, a arquitetura foi renovada, e um kernel Linux real construído pela Microsoft agora roda diretamente em uma “VM utilitária leve” que utiliza um subconjunto da arquitetura Hyper-V. Isso garante 100% de compatibilidade de chamadas de sistema, e o uso de um disco virtual (VHDX) com o sistema de arquivos ext4 nativo do Linux melhorou drasticamente o desempenho de E/S de arquivos em comparação com o WSL1.

O diagrama Mermaid a seguir mostra as diferenças estruturais entre o WSL1 e o WSL2.

flowchart TD
subgraph "Ambiente do SO Windows"
A["Kernel Windows NT"]
A --> F["Sistema de Arquivos NTFS (Unidade C:)"]
end
subgraph "Arquitetura do WSL2"
B["Hypervisor Hyper-V"]
B --> C["VM Utilitária Leve"]
C --> D["Kernel Linux (Microsoft)"]
D --> E["Espaço de Usuário Ubuntu (glibc, bash, etc.)"]
D --> G["Disco Virtual ext4 (.vhdx)"]
end
A -.->|"Compartilhamento de Arquivos de Rede via Protocolo Plan 9 (9P)"| D
style B fill:#f9f,stroke:#333,stroke-width:2px
style D fill:#bbf,stroke:#333,stroke-width:2px

A lição importante a ser tirada dessa estrutura é que “o acesso aos arquivos no lado do Linux (dentro do VHDX) é extremamente rápido, mas o acesso aos arquivos no lado do Windows (/mnt/c/) é muito lento porque passa pelo protocolo 9P”. O código-fonte do projeto deve ser sempre colocado no diretório inicial (~) do lado do WSL.

2. Análise Matemática do Desempenho: Por que o WSL2 é rápido?

Vamos avaliar quantitativamente a melhoria de desempenho do WSL2 usando um modelo matemático. Uma das operações mais demoradas no desenvolvimento de software é o processamento que envolve E/S de um grande número de arquivos (por exemplo, instalação de bibliotecas e compilação).

O tempo total de execução $T_{total}$ de um determinado processo é expresso como a soma do tempo de computação pela CPU $T_{compute}$ e o tempo de E/S de disco $T_{io}$.

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

No caso do WSL1, ocorre uma sobrecarga ao converter as operações do lado do Linux em operações NTFS, então o tempo de E/S é modelado da seguinte forma. Aqui, $n$ é o número de operações de arquivo, $t_{ntfs\_syscall}$ é o tempo de execução da chamada de sistema do lado do Windows, e $t_{trans}$ é a sobrecarga da camada de tradução.

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

Por outro lado, no caso do WSL2, o kernel emite E/S diretamente para o sistema de arquivos ext4, então a sobrecarga é apenas um pequeno atraso $t_{virt}$ devido à virtualização.

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

Em sistemas de arquivos comuns, como $t_{ext4} \ll t_{ntfs\_syscall} + t_{trans}$, quando $n$ é muito grande (dezenas a centenas de milhares de operações de arquivo), a diferença no tempo de E/S entre o WSL1 e o WSL2 aumenta exponencialmente.

Além disso, assumindo que a taxa de sobrecarga do cálculo da CPU em um ambiente virtualizado seja $\rho$, na virtualização mais recente assistida por hardware (Intel VT-x / AMD-V), ela fica em torno de $\rho \approx 0.01 \sim 0.03$ (1 a 3%). Portanto, mesmo em tarefas puramente computacionais, ele oferece $97\% \sim 99\%$ de desempenho comparável ao de um ambiente Linux nativo.

3. Instalação e Construção da Base

No Windows 10/11, a instalação do WSL2 tornou-se muito simples. Basta abrir o PowerShell com privilégios de administrador e executar o seguinte comando:

1
2
3
4
5
6


# WSL2 e Ubuntu são instalados por padrão
wsl --install

# Ao especificar uma distribuição específica
# Pode ser verificado com wsl --list --online
wsl --install -d Ubuntu-24.04

Após a instalação e reinicialização, você será solicitado a configurar um nome de usuário UNIX e senha na primeira inicialização. Esse usuário é independente do usuário do Windows e é válido apenas dentro do WSL.

Se você já estiver usando o WSL1, poderá convertê-lo para o WSL2 com os seguintes comandos:

1
2
3
4
5


# Converter uma distribuição existente para WSL2
wsl --set-version Ubuntu 2

# Definir o WSL2 como padrão para distribuições adicionadas no futuro
wsl --set-default-version 2

4. Os Segredos do Controle de Recursos: .wslconfig e wsl.conf

Uma das maiores armadilhas do WSL2 é o “consumo ilimitado de memória (inchaço do processo Vmmem)”. Como o WSL2 usa o cache de página do kernel Linux, ele consome infinitamente a memória do host (Windows) a cada E/S. Para evitar isso, é essencial limitar os recursos por meio de arquivos de configuração.

Os arquivos de configuração do WSL2 são divididos em dois: .wslconfig que afeta todo o Windows e wsl.conf que afeta o interior de cada distribuição.

4.1. .wslconfig (Lado do Windows)

Crie um arquivo no diretório de perfil de usuário do Windows (C:\Users\<NomeDoUsuario>\.wslconfig) para controlar a alocação de recursos para a 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\<NomeDoUsuario>\.wslconfig
[wsl2]
# Quantidade máxima de memória alocada à VM. Recomenda-se cerca de 50% a 75% da memória total do host
memory=16GB

# Número de núcleos de CPU a serem usados (usa todos os núcleos se omitido)
processors=8

# Tamanho do arquivo de swap
swap=8GB

# Destino de salvamento do arquivo de swap (se desejar economizar espaço na unidade C)
# swapfile=D:\\wsl\\swap.vhdx

# Habilitar o encaminhamento do localhost (para acessar o WSL do lado do Windows através do localhost)
localhostForwarding=true

# Liberar memória automaticamente (Apenas Windows 11)
# Libera dinamicamente o cache de página para evitar o inchaço do Vmmem
autoMemoryReclaim=dropcache

[experimental]
# Recursos avançados de rede disponíveis no Windows 11 22H2 e posteriores
# Isso permite suporte a IPv6 e compartilhamento do mesmo endereço IP entre o WSL e o Windows
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

4.2. wsl.conf (Lado do Linux)

Edite /etc/wsl.conf dentro do WSL para controlar o comportamento específico da distribuição.

 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 (Editado dentro do WSL)
[network]
# Desativa a geração automática de /etc/resolv.conf na inicialização do WSL
# Útil se você deseja definir um DNS personalizado (por exemplo, 8.8.8.8)
generateResolvConf=false

# Define um nome de host personalizado
hostname=WSL-DevNode

[automount]
# Configurações de montagem para unidades do Windows
enabled=true
options="metadata,uid=1000,gid=1000,umask=022"
# Muda o ponto de montagem da unidade C de /mnt/c para /c (encurta o caminho)
root=/

[boot]
# Ativa o systemd (WSL 0.67.6 e posteriores)
# Isso permite que snap e vários daemons (como o Docker) sejam executados nativamente
systemd=true

[user]
# Usuário de login padrão
default=kenji

Para aplicar essas configurações, você deve executar wsl --shutdown no PowerShell para parar completamente a VM do WSL antes de reiniciar.

5. O Ambiente de Terminal Definitivo: Zsh + Powerlevel10k

A produtividade não aumentará se você mantiver o bash padrão. Combinaremos o Zsh, que se orgulha de funções poderosas de autocompletar e visibilidade, com o tema ultrarrápido “Powerlevel10k” para construir o prompt mais forte.

5.1. Introdução e Configuração do Windows Terminal

Instale o “Windows Terminal” a partir da Microsoft Store. Abra as configurações JSON (settings.json), defina o perfil padrão para o WSL (Ubuntu) e altere a fonte para uma Nerd Font focada em desenvolvimento (por exemplo, HackGen Console NF ou MesloLGS NF).

5.2. Instalação do Zsh e Oh My Zsh

Execute os seguintes comandos no terminal do WSL:

1
2
3
4
5
6


# Atualização de pacotes e instalação do Zsh
sudo apt update && sudo apt upgrade -y
sudo apt install -y zsh git curl

# Executa o script de instalação do Oh My Zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

5.3. Introdução ao Powerlevel10k e Plugins

Introduziremos plugins (realce de sintaxe e autocompletar) e o tema Powerlevel10k que aprimoram ainda mais o 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

Edite ~/.zshrc para ativar o tema e os plugins.

1
2
3
4
5


# Alterações em ~/.zshrc
ZSH_THEME="powerlevel10k/powerlevel10k"

# Adicionar ao array de plugins
plugins=(git zsh-autosuggestions zsh-syntax-highlighting)

Ao salvar e executar source ~/.zshrc, o assistente de configuração do Powerlevel10k (p10k configure) será iniciado. Siga as instruções na tela para personalizar o prompt ao seu gosto (estilo do prompt, presença de ícones, informações a serem exibidas, etc.). O nome e o status do branch do Git, a versão do Node.js, o tempo de execução do comando, entre outros, serão exibidos em tempo real, melhorando drasticamente a eficiência do desenvolvimento.

6. VS Code Remote - Integração Perfeita com o WSL

No desenvolvimento com o WSL2, a extensão “Remote - WSL” é o mecanismo que permite o acesso perfeito aos arquivos dentro do WSL a partir do IDE (Visual Studio Code) instalado no lado do Windows.

Explicação da Arquitetura

O diagrama de sequência a seguir mostra como o VS Code se comunica com o WSL2.

sequenceDiagram
autonumber
participant U as "Desenvolvedor"
participant V as "IU do VS Code (Windows)"
participant S as "Servidor VS Code (WSL2)"
participant F as "Sistema de Arquivos ext4 (WSL2)"
U->>V: "Digitar `code .` no Terminal WSL"
V->>S: "Estabelecer Conexão RPC via Vsock"
Note over V,S: Comunica-se por soquetes Hyper-V sem usar TCP/IP
S->>F: "Ler Arquivos de Origem / Executar Linter"
F-->>S: "Retornar Dados e Análise"
S-->>V: "Transmitir resultados do Servidor de Idioma para a IU"
V-->>U: "Exibir realce de sintaxe e erros"

O VS Code no lado do Windows funciona como um mero “cliente fino (IU)”, e todos os processos pesados como Servidor de Linguagem (Language Server), depurador e execução no terminal são tratados pelo “VS Code Server” no lado do WSL. Isso permite que você mantenha seu ambiente limpo usando apenas o lado do WSL, sem ter que instalar o Node.js ou Python no lado do Windows.

Configurações Essenciais do VS Code

Instale a extensão “WSL” (ms-vscode-remote.remote-wsl) a partir de “Extensões” no VS Code. Em seguida, navegue até o diretório do seu projeto no terminal do WSL e simplesmente execute code . para iniciar o VS Code no lado do Windows com esse diretório aberto.

Nota importante (Problema com o código de quebra de linha): Windows e Linux usam códigos de quebra de linha diferentes (Windows usa CRLF, Linux usa LF). Ao desenvolver no WSL, certifique-se de unificar a configuração core.autocrlf do Git e as configurações padrão de arquivos do VS Code para LF. Se não fizer isso, você poderá sofrer com erros misteriosos ao executar scripts de shell ou contêineres Docker.

1
2


# Configuração do código de quebra de linha do Git no lado do WSL
git config --global core.autocrlf input

Adicione também o seguinte ao settings.json (configurações remotas) do VS Code:

1
2
3
4


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

7. Otimização do Docker Desktop e Integração WSL2

Para usar o Docker no ambiente WSL2, existem principalmente duas abordagens:

Instalar o Docker Desktop for Windows e ativar o recurso de integração com o WSL2
Instalar o Docker Engine nativo diretamente dentro do WSL2 (Ubuntu, etc.)

Abordagem 1: Docker Desktop (Recomendado)

Esta abordagem é recomendada na maioria dos casos porque facilita o gerenciamento via GUI e o acesso transparente a contêineres entre Windows/WSL. Verifique o seguinte nas Configurações (Settings) do Docker Desktop:

Em General, marque a opção Use the WSL 2 based engine.
Em Resources -> WSL Integration, marque a opção Enable integration with my default WSL distro e ligue a chave seletora para a distribuição (Ubuntu) a ser usada.

Isso permite que o comando docker seja executado diretamente do terminal do WSL2, e a comunicação com o daemon do Docker ocorra por meio de uma VM leve dedicada (docker-desktop e docker-desktop-data) gerenciada pelo Docker Desktop.

Abordagem 2: Instalação Direta do Docker Engine Nativo

Se houver restrições de rede corporativa (como evitar taxas de licenciamento do Docker Desktop) ou se você quiser reduzir ao máximo a sobrecarga de desempenho, ative o systemd em /etc/wsl.conf e instale o Docker como um servidor Ubuntu puro.

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


# Trecho do procedimento oficial de instalação do Docker no Ubuntu WSL2 com systemd ativado
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

# Adição do repositório
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

# Adicionar o usuário atual ao grupo docker (para executar sem sudo)
sudo usermod -aG docker $USER

Após a reinicialização, o systemctl start docker funcionará exatamente como em um ambiente Linux nativo, oferecendo alto desempenho.

8. Integração da Chave SSH: Autenticação Perfeita entre Windows e WSL

Ao clonar repositórios Git via SSH ou conectar-se a servidores remotos via SSH, é muito trabalhoso gerenciar chaves SSH separadamente nos lados do Windows e do WSL. Para equilibrar segurança e conveniência, configuraremos uma ponte entre o agente SSH em execução no lado do Windows (ou um gerenciador de senhas como o 1Password) e o lado do WSL.

Aqui, explicaremos o método de usar a funcionalidade de agente SSH do 1Password ou o OpenSSH Authentication Agent do Windows como a abordagem mais segura e moderna, encaminhando-o para o soquete de domínio UNIX do WSL2 usando npiperelay e socat.

Encaminhamento de Soquete do ssh-agent

O agente SSH, que normalmente é fornecido como um Named Pipe (pipe nomeado) no Windows, deve ser convertido em um arquivo de soquete no lado do WSL. É fácil fazer isso usando recursos fornecidos pelo wsl-ssh-agent ou pelo 1Password.

Na tela de configurações do 1Password, ative “Developer” -> “Usar Agente SSH”. Em seguida, adicione as seguintes configurações ao ~/.zshrc ou ~/.bashrc do lado do WSL para vincular automaticamente o soquete ao fazer login.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Adição ao ~/.zshrc (Exemplo ao usar o 1Password SSH Agent)
export SSH_AUTH_SOCK=$HOME/.ssh/agent.sock
# Encaminhar usando socat e npiperelay se o soquete não existir ou o processo não estiver vinculado quando o WSL iniciar
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 o socat em segundo plano e conecta o Named Pipe do lado do Windows ao soquete UNIX do lado do WSL
 (setsid socat UNIX-LISTEN:$SSH_AUTH_SOCK,fork EXEC:"npiperelay.exe -ei -s //./pipe/openssh-ssh-agent",nofork &) >/dev/null 2>&1
fi

É necessário instalar o npiperelay.exe no lado do Windows e adicionar seu caminho ao PATH antecipadamente.

Quando essa configuração estiver concluída, a execução de ssh-add -l a partir do terminal do WSL exibirá uma lista de chaves públicas das chaves SSH registradas no 1Password ou no lado do Windows. Isso permite que você passe pela autenticação com segurança, sem copiar arquivos de chave privada para dentro do WSL.

9. Manutenção: Otimização (Compactação) de VHDX Inchado

Uma das maiores falhas do WSL2 é a especificação de que “mesmo se você excluir imagens do Docker ou arquivos, o tamanho do arquivo do disco virtual do lado do Windows (.vhdx) não será reduzido automaticamente”. Após um longo período de desenvolvimento, o arquivo ext4.vhdx pode inchar para dezenas a centenas de gigabytes.

Para liberar espaço em disco, você deve otimizar (Compactar) periodicamente o VHDX no lado do Windows.

Primeiro, desligue completamente o WSL.
1

wsl --shutdown
Abra o PowerShell com privilégios de administrador e execute o comando diskpart a seguir ou o comando Optimize-VHD do módulo Hyper-V (o último só pode ser usado se o Hyper-V estiver ativado).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Quando o módulo Hyper-V está disponível
Optimize-VHD -Path "$env:LOCALAPPDATA\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx" -Mode Full

# Quando usar o diskpart
diskpart
# Digite interativamente no prompt abaixo
DISKPART> select vdisk file="C:\Users\<NomeDoUsuario>\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx"
DISKPART> attach vdisk readonly
DISKPART> compact vdisk
DISKPART> detach vdisk
DISKPART> exit

Ao executar essa operação regularmente, você pode recuperar o espaço consumido desnecessariamente na unidade C.

10. Conclusão

O WSL2 transcendeu completamente o quadro de ser apenas um “Linux de bônus rodando no Windows” e evoluiu para uma plataforma de desenvolvimento poderosa que rivaliza ou até supera o MacOS ou máquinas Linux nativas.

Ao aplicar todas as configurações explicadas desta vez (otimização de recursos com .wslconfig, aprimoramento de terminal com Zsh + Powerlevel10k, acesso transparente com VS Code Remote e integração SSH e manutenção de VHDX), o “ambiente de desenvolvimento definitivo” livre de estresse, rápido e seguro estará completo.

Demora um pouco para configurar o ambiente, mas uma vez que você consolide suas configurações, não há dúvida de que sua produtividade em engenharia melhorará drasticamente de agora em diante. Sinta-se à vontade para explorar mais personalizações com base neste guia para atender aos seus próprios projetos e preferências.