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:

SuperficieURL
API healthhttp://localhost:3000/api/v1/health
Web públicahttp://localhost:3001/en · /es · portal /en/portal · admin /en/admin
Help Centerhttp://localhost:3002/en
Developer Docshttp://localhost:3003/en
Mailpit UIhttp://localhost:8025
Grafanahttp://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

HerramientaObligatorioNotas
makeSíFachada DX
gitSíFlujo de rama / ship
rsyncSímake sync-agents
OpenSpec CLI (openspec)SíDOC-014
Spec Kit CLI (specify)SíDOC-014
Node ≥ 20SíADR-020. make doctor lo exige
pnpm 9.15.0Sícorepack enable && corepack prepare pnpm@9.15.0 --activate
DockerSí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.

Referencias