the-other-dude/docs/superpowers/specs/2026-03-14-setup-script-design.md

# TOD Production Setup Script — Design Spec

## Overview

An interactive Python setup wizard (`setup.py`) that walks a sysadmin through configuring and deploying TOD (The Other Dude) for production. The script minimizes manual configuration by auto-generating secrets, capturing OpenBao credentials automatically, building images sequentially, and verifying service health.

**Target audience:** Technical sysadmins unfamiliar with this specific project.

## Design Decisions

- **Python 3.10+** — already required by the stack, enables rich input handling and colored output.
- **Linear wizard with opinionated defaults** — grouped sections, auto-generate everything possible, only prompt for genuine human decisions.
- **Integrated OpenBao bootstrap** — script starts the OpenBao container, captures unseal key and root token, updates `.env.prod` automatically (no manual copy-paste).
- **Sequential image builds** — builds api, poller, frontend, winbox-worker one at a time to avoid OOM on low-RAM machines.
- **Re-runnable** — safe to run again; detects existing `.env.prod` and offers to overwrite, back up (`.env.prod.backup.<ISO timestamp>`), or abort.

## Prerequisite: Database Rename

The codebase currently uses `mikrotik` as the database name. Before the setup script can use `tod`, these files must be updated:

- `docker-compose.yml` — default `POSTGRES_DB` and healthcheck (`pg_isready -d`)
- `docker-compose.prod.yml` — hardcoded poller `DATABASE_URL` (change to `${POLLER_DATABASE_URL}`)
- `docker-compose.staging.yml` — if applicable
- `scripts/init-postgres.sql` — `GRANT CONNECT ON DATABASE` statements
- `.env.example` — all URL references

The setup script will use `POSTGRES_DB=tod`. These file changes are part of the implementation, not runtime.

Additionally, `docker-compose.prod.yml` hardcodes the poller's `DATABASE_URL`. This must be changed to `DATABASE_URL: ${POLLER_DATABASE_URL}` so the setup script's generated value is used.

## Script Flow

### Phase 1: Pre-flight Checks

- Verify Python 3.10+
- Verify Docker Engine and Docker Compose v2 are installed and the daemon is running
- Check for existing `.env.prod` — if found, offer: overwrite / back up and create new / abort
- Warn if less than 4GB RAM available
- Check if key ports are in use (5432, 6379, 4222, 8001, 3000, 51820) and warn

### Phase 2: Interactive Configuration (Linear Wizard)

Six sections, presented in order:

#### 2.1 Database

| Prompt | Default | Notes |
|--------|---------|-------|
| PostgreSQL superuser password | (required, no default) | Validated non-empty, min 12 chars |

Auto-generated:
- `POSTGRES_DB=tod`
- `app_user` password via `secrets.token_urlsafe(24)` (yields ~32 base64 chars)
- `poller_user` password via `secrets.token_urlsafe(24)` (yields ~32 base64 chars)
- `DATABASE_URL=postgresql+asyncpg://postgres:<pw>@postgres:5432/tod`
- `SYNC_DATABASE_URL=postgresql+psycopg2://postgres:<pw>@postgres:5432/tod`
- `APP_USER_DATABASE_URL=postgresql+asyncpg://app_user:<app_pw>@postgres:5432/tod`
- `POLLER_DATABASE_URL=postgres://poller_user:<poller_pw>@postgres:5432/tod`

#### 2.2 Security

No prompts. Auto-generated:
- `JWT_SECRET_KEY` via `secrets.token_urlsafe(64)` (yields ~86 base64 chars)
- `CREDENTIAL_ENCRYPTION_KEY` via `base64(secrets.token_bytes(32))` (yields 44 base64 chars)
- Display both values to the user with a "save these somewhere safe" note

#### 2.3 Admin Account

| Prompt | Default | Notes |
|--------|---------|-------|
| Admin email | `admin@the-other-dude.dev` | Validated as email-like |
| Admin password | (enter or press Enter to generate) | Min 12 chars if manual; generated passwords are 24 chars |

#### 2.4 Email (Optional)

| Prompt | Default | Notes |
|--------|---------|-------|
| Configure SMTP now? | No | If no, skip with reminder |
| SMTP host | (required if yes) | |
| SMTP port | 587 | |
| SMTP username | (optional) | |
| SMTP password | (optional) | |
| From address | (required if yes) | |
| Use TLS? | Yes | |

#### 2.5 Web / Domain

| Prompt | Default | Notes |
|--------|---------|-------|
| Production domain | (required) | e.g. `tod.staack.com` |

Auto-derived:
- `APP_BASE_URL=https://<domain>`
- `CORS_ORIGINS=https://<domain>`

#### 2.6 Summary & Confirmation

Display all settings grouped by section. Secrets are partially masked (first 8 chars + `...`). Ask for confirmation before writing.

### Phase 3: Write `.env.prod`

Write the file with section comments and timestamp header. Also generate `scripts/init-postgres-prod.sql` with the generated `app_user` and `poller_user` passwords baked in (PostgreSQL init scripts don't support env var substitution).

Format:

```bash
# ============================================================
# TOD Production Environment — generated by setup.py
# Generated: <ISO timestamp>
# ============================================================

# --- Database ---
POSTGRES_DB=tod
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<input>
DATABASE_URL=postgresql+asyncpg://postgres:<pw>@postgres:5432/tod
SYNC_DATABASE_URL=postgresql+psycopg2://postgres:<pw>@postgres:5432/tod
APP_USER_DATABASE_URL=postgresql+asyncpg://app_user:<app_pw>@postgres:5432/tod
POLLER_DATABASE_URL=postgres://poller_user:<poller_pw>@postgres:5432/tod

# --- Security ---
JWT_SECRET_KEY=<generated>
CREDENTIAL_ENCRYPTION_KEY=<generated>

# --- OpenBao (KMS) ---
OPENBAO_ADDR=http://openbao:8200
OPENBAO_TOKEN=PLACEHOLDER_RUN_SETUP
BAO_UNSEAL_KEY=PLACEHOLDER_RUN_SETUP

# --- Admin Bootstrap ---
FIRST_ADMIN_EMAIL=<input>
FIRST_ADMIN_PASSWORD=<input-or-generated>

# --- Email ---
# <configured block or "unconfigured" note>
SMTP_HOST=
SMTP_PORT=587
SMTP_USER=
SMTP_PASSWORD=
SMTP_USE_TLS=true
SMTP_FROM_ADDRESS=noreply@example.com

# --- Web ---
APP_BASE_URL=https://<domain>
CORS_ORIGINS=https://<domain>

# --- Application ---
ENVIRONMENT=production
LOG_LEVEL=info
DEBUG=false
APP_NAME=TOD - The Other Dude

# --- Storage ---
GIT_STORE_PATH=/data/git-store
FIRMWARE_CACHE_DIR=/data/firmware-cache
WIREGUARD_CONFIG_PATH=/data/wireguard
WIREGUARD_GATEWAY=wireguard
CONFIG_RETENTION_DAYS=90

# --- Redis & NATS ---
REDIS_URL=redis://redis:6379/0
NATS_URL=nats://nats:4222

# --- Poller ---
POLL_INTERVAL_SECONDS=60
CONNECTION_TIMEOUT_SECONDS=10
COMMAND_TIMEOUT_SECONDS=30

# --- Remote Access ---
TUNNEL_PORT_MIN=49000
TUNNEL_PORT_MAX=49100
TUNNEL_IDLE_TIMEOUT=300
SSH_RELAY_PORT=8080
SSH_IDLE_TIMEOUT=900

# --- Config Backup ---
CONFIG_BACKUP_INTERVAL=21600
CONFIG_BACKUP_MAX_CONCURRENT=10
```

### Phase 4: OpenBao Bootstrap

1. Start postgres and openbao containers only: `docker compose -f docker-compose.yml -f docker-compose.prod.yml --env-file .env.prod up -d postgres openbao`
2. Wait for openbao container to be healthy (timeout 60s)
3. Run `docker compose logs openbao 2>&1` and parse the `OPENBAO_TOKEN=` and `BAO_UNSEAL_KEY=` lines using regex (init.sh prints these to stdout during container startup, which is captured in Docker logs)
4. Update `.env.prod` by replacing the `PLACEHOLDER_RUN_SETUP` values with the captured credentials
5. On failure: `.env.prod` retains placeholders, print instructions for manual capture via `docker compose logs openbao`

### Phase 5: Build Images

Build sequentially to avoid OOM:

```
docker compose -f docker-compose.yml -f docker-compose.prod.yml build api
docker compose -f docker-compose.yml -f docker-compose.prod.yml build poller
docker compose -f docker-compose.yml -f docker-compose.prod.yml build frontend
docker compose -f docker-compose.yml -f docker-compose.prod.yml build winbox-worker
```

Show progress for each. On failure: stop, report which image failed, suggest rerunning.

### Phase 6: Start Stack

```
docker compose -f docker-compose.yml -f docker-compose.prod.yml --env-file .env.prod up -d
```

### Phase 7: Health Check

- Poll service health for up to 60 seconds
- Report status of: postgres, redis, nats, openbao, api, poller, frontend, winbox-worker
- On success: print access URL (`https://<domain>`) and admin credentials
- On timeout: report which services are unhealthy, suggest `docker compose logs <service>`

## Database Init Script

`scripts/init-postgres.sql` hardcodes `app_password` and `poller_password`. Since PostgreSQL's `docker-entrypoint-initdb.d` scripts don't support environment variable substitution, the setup script generates `scripts/init-postgres-prod.sql` with the actual generated passwords baked in. The docker-compose.prod.yml volume mount will be updated to use this file instead.

## Login Page Fix

`frontend/src/routes/login.tsx` lines 235-241 contain a "First time?" hint showing `.env` credential names. This will be wrapped in `{import.meta.env.DEV && (...)}` so it only appears in development builds. Vite's production build strips DEV-gated code entirely.

## Error Handling

| Scenario | Behavior |
|----------|----------|
| Docker not installed/running | Fail early with clear message |
| Existing `.env.prod` | Offer: overwrite / back up / abort |
| Port already in use | Warn (non-blocking) with which port and likely culprit |
| OpenBao init fails | `.env.prod` retains placeholders, print manual capture steps |
| Image build fails | Stop, show failed image, suggest retry command |
| Health check timeout (60s) | Report unhealthy services, suggest log commands |
| Ctrl+C before Phase 3 | Graceful exit, no files written |
| Ctrl+C during/after Phase 3 | `.env.prod` exists (possibly with placeholders), noted on exit |

## Re-runnability

- Detects existing `.env.prod` and offers choices
- Won't regenerate secrets if valid ones exist (offers to keep or regenerate)
- OpenBao re-init is idempotent (init.sh handles already-initialized state)
- Image rebuilds are safe (Docker layer caching)
- Backup naming: `.env.prod.backup.<ISO timestamp>`

## Dependencies

- Python 3.10+ (stdlib only — no pip packages required)
- Docker Engine 24+
- Docker Compose v2
- Stdlib modules: `secrets`, `subprocess`, `shutil`, `json`, `re`, `datetime`, `pathlib`, `getpass`, `socket` (for port checks)