Assist_Design/docs/RUN.md

# Runbook: Development and Production

## Development

1. Setup env and deps

```bash
cp .env.dev.example .env
pnpm install
```

2. Start services (PostgreSQL + Redis)

```bash
pnpm dev:start
```

3. Start the apps (hot reload)

```bash
pnpm dev
# or
pnpm dev:apps
```

4. Migrate database (optional initially)

```bash
pnpm dev:migrate
```

5. Tools (optional)

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

6. Stop / Status / Logs

```bash
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

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

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

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

3. Deploy (build + start + migrate)

```bash
pnpm prod:deploy
```

4. Status / Logs / Update / Stop

```bash
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).