Assist_Design/docs/RUN.md

Runbook: Development and Production

Development

1. Setup env and deps

cp .env.dev.example .env
pnpm install

2. Start services (PostgreSQL + Redis)

pnpm dev:start

3. Start the apps (hot reload)

pnpm dev
# or
pnpm dev:apps

4. Migrate database (optional initially)

pnpm dev:migrate

5. Tools (optional)

pnpm dev:tools   # Adminer (http://localhost:8080) + Redis Commander (http://localhost:8081)

6. Stop / Status / Logs

pnpm dev:status
pnpm dev:logs
pnpm dev:stop

Notes

• Both apps read env from the root .env (centralized).
• Ports are controlled via env:
  • BFF_PORT (fallback to PORT) defaults to 4000
  • NEXT_PORT defaults to 3000
• Backend API runs on http://localhost:${BFF_PORT} (default 4000; paths start with /api).
• Portal runs on http://localhost:${NEXT_PORT} (default 3000).

Production

1. Setup env

cp .env.production.example .env
# Edit .env with production values

2. (Optional) First-time TLS certificate via HTTP challenge

# Replace with your domain and email
./scripts/prod/manage.sh issue-cert yourdomain.com you@example.com

3. Deploy (build + start + migrate)

pnpm prod:deploy

4. Status / Logs / Update / Stop

pnpm prod:status
pnpm prod:logs
pnpm prod:update
pnpm prod:stop

Endpoints (behind reverse proxy)

• Portal: https://yourdomain.com
• API: https://yourdomain.com/api
• Health: https://yourdomain.com/healthz (proxy) and https://yourdomain.com/api/health (backend)

Security

• Nginx enforces HTTPS, HSTS, CSP and rate limiting for /api/.
• Backend disables x-powered-by, supports trust proxy, and uses centralized env validation.
• Do not commit the .env file; keep secrets safe (e.g., secrets/ volume for keys).