Setup do ambiente local¶
A stack local é do Makefile da raiz (make help lista os alvos); a infra vive em infra/local/, e os apps rodam no host com hot reload. Fonte: CLAUDE.md da raiz, seções Comandos e Ambiente local.
Pré-requisitos¶
Python 3.12+, uv, Node 20+, pnpm, npm e Docker Desktop.
brew install --cask docker
make setup # dependências dos três apps (uv sync, pnpm install, npm install)
make local-up # sobe PostgreSQL + Redis + Mailpit + Caddy (containers)
make api-migrate # aplica as migrations
Detalhes da infra local (topologia, portas, troubleshooting) em infra/local/README.md.
O que precisa estar rodando¶
| Processo | Comando | Sem ele |
|---|---|---|
| PostgreSQL, Redis, Mailpit, Caddy | make local-up | nada sobe |
API (uvicorn :8000) | make api-dev | o front não tem a quem chamar |
Worker da fila (arq, spec 0050) | make worker-dev | a consulta ao bureau de crédito e os jobs agendados (6h e 7h) não acontecem — sem erro nenhum |
Frontend (Vite :5173) | make web-dev | sem tela |
Documentação técnica (Sphinx :8001) | make api-wiki | só /wiki fica fora — opcional |
O worker é um processo à parte da API, e existe nos três ambientes (local, dev-remote e produção). Subir só a API é o erro silencioso mais comum aqui.
Acesso¶
Origem única, roteada por path, em http://localhost:8080 — ver ../decisions/ADR-0003-ambiente-local-por-path-unico.md.
| URL | O quê |
|---|---|
http://localhost:8080/app | Frontend |
http://localhost:8080/api/docs | Swagger |
http://localhost:8080/api/v1/... | API |
http://localhost:8080/wiki | Documentação técnica (Sphinx AutoAPI) |
http://localhost:8080/mail | Mailpit |
make local-url imprime a lista. Não há domínio .test, certificado local nem entrada no /etc/hosts: localhost já é origem segura para o browser, então service worker, PWA e clipboard funcionam sem certificado. O que não existe mais (desde 2026-09-17, quando o tailscale serve saiu) é alcançar a stack local de outro aparelho.