Local development guide
pnpm, Docker, make doctor and the four local URLs.
Source: docs/development/DOC-011-local-development-guide.md
DOC-011: Local Development Guide
Estado
Approved para el scaffold (changes monorepo-scaffold y platform-surfaces-scaffold). Las páginas de producto siguen sin estar.
Entrada rápida
make help
make doctor
make install # pnpm en el host: typecheck, lint, test, prisma generate
make local-up-build # primera vez: imagen + perfil dev (postgres, mailpit, api, web, help, docs)
make local-up-d # día a día, en segundo plano
make infra-up # PostgreSQL :5434 + Mailpit SMTP :1025 / UI :8025
make observability-up # Loki, Prometheus, Grafana :3004 (opt-in, ADR-040)
make check # typecheck + lint + test, en el host
make ship ARGS='--title "chore: ..." '
make prod-compose-config # compose de producción A-lite (no arranca el VPS)
Interfaz DX: Makefile (ADR-016). Git: ADR-017. Local: ADR-027.
make local-up usa devops/docker/compose --profile dev. Copia devops/docker/.env.docker.example a .env.docker si falta (incluye HELP_PORT, SMTP_* y GRAFANA_*). Dentro de la red el hostname de la base es postgres y el SMTP es mailpit. En el host:
| Superficie | URL |
|---|---|
| API health | http://localhost:3000/api/v1/health |
| Web pública | http://localhost:3001/en · /es · portal /en/portal · admin /en/admin |
| Help Center | http://localhost:3002/en |
| Developer Docs | http://localhost:3003/en |
| Mailpit UI | http://localhost:8025 |
| Grafana | http://localhost:3004 (make observability-up; user/password de example) |
Mailpit solo captura correo local. Grafana no arranca con local-up. Redis no forma parte del stack. Las contraseñas de los example son solo de desarrollo. .env y .env.docker no se versionan. Cloudflare Turnstile (ADR-041) usa un widget real (NEXT_PUBLIC_TURNSTILE_SITE_KEY / TURNSTILE_SECRET_KEY en .env.docker). No uses las claves dummy 1x0000…: pintan la franja roja «For testing only».
Prerrequisitos
| Herramienta | Obligatorio | Notas |
|---|---|---|
make | Sí | Fachada DX |
git | Sí | Flujo de rama / ship |
rsync | Sí | make sync-agents |
OpenSpec CLI (openspec) | Sí | DOC-014 |
Spec Kit CLI (specify) | Sí | DOC-014 |
| Node ≥ 20 | Sí | ADR-020. make doctor lo exige |
| pnpm 9.15.0 | Sí | corepack enable && corepack prepare pnpm@9.15.0 --activate |
| Docker | Sí | Compose perfil dev (ADR-027). Primera vez: make local-up-build |
Calidad
make check ejecuta pnpm typecheck, pnpm lint, pnpm format:check, pnpm test, make security-deps y make security-sast. make security-secrets escanea el árbol con gitleaks. El detalle está en DOC-016 y en .specify/memory/security.md. El estilo de código está en .specify/memory/coding-style.md.