Setup e Ambiente

Setup e Ambiente

Como deixar a máquina pronta pro curso. As versões exatas de cada módulo ficam no VERSIONS.md do módulo — esta página cobre o tooling base.

Esta página é operacional e muda com o tempo (versões de SO, de ferramentas). Se algo aqui estiver desatualizado, corrija direto na wiki.

---

O que você precisa

Ferramenta	Versão	Para quê
asdf	recente	Travar versões de Go e Node por projeto
Go	1.26+	Implementação Go do ledger
Node	24+	Implementação Node do ledger
pnpm	11+	Gerenciador de pacotes do Node
Docker	v2	Subir a infra compartilhada
Docker Compose	v2 (plugin)	docker compose, não docker-compose
Make	qualquer	Atalhos de build/test
Git	2.40+	Gitflow do curso

Hardware: mínimo 8GB de RAM. A stack de infra sobe ~10 containers nos módulos finais (Postgres, RabbitMQ, OTel Collector, Prometheus, Grafana, Tempo, Loki).

---

macOS (Apple Silicon e Intel)

# Homebrew, se ainda não tiver
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install asdf git make
# Docker Desktop: baixe em docker.com (inclui Compose v2)

# asdf no shell (zsh — padrão no macOS)
echo -e '\n. "$(brew --prefix asdf)/libexec/asdf.sh"' >> ~/.zshrc
source ~/.zshrc

# Plugins de linguagem
asdf plugin add golang
asdf plugin add nodejs

Apple Silicon: o Docker Desktop usa virtualização. Em imagens sem build arm64, ative "Use Rosetta for x86/amd64 emulation" em Settings → General. A stack do curso é toda multi-arch, então normalmente não precisa.

---

Linux

# asdf
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
source ~/.bashrc

asdf plugin add golang
asdf plugin add nodejs

# Docker Engine + Compose v2 (Ubuntu/Debian) — siga o guia oficial:
# https://docs.docker.com/engine/install/
# Depois, rodar docker sem sudo:
sudo usermod -aG docker $USER   # requer logout/login

---

Windows (via WSL2)

Não rode o curso no Windows nativo. Use WSL2 — o ambiente é Linux, e Docker, asdf e o tooling se comportam como na seção Linux.

# No PowerShell como administrador
wsl --install
# Reinicie. Instale a distro (Ubuntu) na Microsoft Store se necessário.

Depois, dentro do Ubuntu/WSL2:

1. Instale o Docker Desktop no Windows e ative Settings → Resources → WSL Integration para a sua distro.
2. Siga a seção Linux acima para asdf, Go, Node.
3. Mantenha o repositório dentro do filesystem do WSL2 (~/cloudnative-course), nunca em /mnt/c/.... I/O cruzando a fronteira Windows↔Linux é lento e quebra file-watching.

---

Instalar e travar as versões

Dentro do repositório clonado:

# asdf lê o .tool-versions do módulo e instala o que falta
asdf install

# Conferir
go version      # go1.26.x
node --version  # v24.x
pnpm --version  # 11.x
docker compose version

Cada módulo tem seu VERSIONS.md com a versão exata e a justificativa. Travar versão é o conteúdo do Módulo 1 — não é burocracia, é o primeiro exercício de arquitetura do curso.

---

Subir a infra compartilhada

cd app/infra
docker compose up -d
docker compose ps   # todos os serviços "running"/"healthy"

Para derrubar ao fim da sessão:

docker compose down          # mantém os volumes (dados persistem)
docker compose down -v       # apaga os volumes (reset total)

Se algum container não sobe, vá para Troubleshooting.

---

Verificação final

# App Go
cd app/go && make test-race

# App Node
cd app/node && pnpm install && pnpm test

Testes verdes nas duas linguagens = ambiente pronto. Pode entrar no Módulo 1.