Docker via WSL2

Nesta máquina o Docker não está disponível diretamente no Windows. O Docker Engine roda nativamente dentro da distro WSL2 Ubuntu, e todo comando docker / docker compose DEVE ser executado através do wsl.

Ambiente

Mapeamento de caminhos

O filesystem do Linux diferencia maiúsculas e minúsculas: o caminho e os nomes de arquivos referenciados em Dockerfile / docker-compose*.yml DEVEM bater exatamente com o casing no disco.

Como executar comandos

Sempre use wsl.exe --cd <diretório> -e <comando>. O diretório deve ser o que contém o docker-compose*.yml (ou o contexto de build).

Pela ferramenta PowerShell (preferida)

wsl --cd /mnt/c/repos/ambrosia -e docker compose up -d --build
wsl --cd /mnt/c/repos/ambrosia -e docker compose ps
wsl -e docker ps -a

O --cd também aceita caminho Windows: wsl --cd 'C:\repos\ambrosia' -e docker compose ps.

Pela ferramenta Bash (Git Bash / MSYS)

O Git Bash converte automaticamente argumentos que parecem caminhos POSIX (/mnt/c/... vira C:/Program Files/Git/mnt/c/...) e o comando falha com Wsl/ERROR_PATH_NOT_FOUND. Para evitar:

# Opção 1: desabilitar a conversão de caminhos
MSYS_NO_PATHCONV=1 wsl.exe --cd /mnt/c/repos/ambrosia -e docker compose up -d

# Opção 2: passar o caminho no formato Windows
wsl.exe --cd 'C:\repos\ambrosia' -e docker compose up -d

Pipes, variáveis e múltiplos comandos

Quando o comando precisar de pipe, &&, redirecionamento ou expansão de variável dentro do Linux, envolva em sh -c '...' (aspas simples para o shell do Windows não interpretar):

wsl --cd /mnt/c/repos/ambrosia -e sh -c 'docker compose logs --tail=100 api | grep -i error'
wsl -e sh -c 'docker ps --format "{{.Names}} {{.Status}}"'

Comandos comuns

Regras

1. Nunca chame docker diretamente no PowerShell/Bash do Windows — o binário não existe. Sempre prefixe com wsl / wsl.exe.
2. Não use sudo — o usuário padrão já pertence ao grupo docker.
3. Não use -f / --follow nem -it em logs, exec ou run: as ferramentas não são interativas e o comando ficaria preso. Use --tail=N. Para processos longos (ex.: build demorado), use run_in_background da ferramenta.
4. Não instale Docker Desktop nem altere o engine do WSL sem pedido explícito do usuário.
5. Ações destrutivas exigem confirmação: docker compose down -v, docker volume rm, docker system prune, docker rm -f em containers que não foram criados na tarefa atual. Esta máquina hospeda containers de outros projetos (ex.: anjoo_*, avabot-*) — nunca os pare ou remova.
6. Portas: containers publicados no WSL2 ficam acessíveis no Windows via localhost:<porta> (localhost forwarding padrão). Antes de publicar uma porta, verifique conflitos com wsl -e docker ps --format "{{.Names}} {{.Ports}}".
7. Line endings: scripts shell copiados para a imagem (entrypoint.sh etc.) DEVEM usar LF. Arquivos com CRLF falham no container com /bin/sh^M: not found.

Troubleshooting

Skills relacionadas

• docker-compose-config — padrão de .env e variáveis no docker-compose.yml.
• dotnet-env — ambientes Development / Docker / Production.
• deploy-prod — pipeline de deploy em produção (fora desta máquina).