# Deploying AI Atlas on MacLustr

Production runs on **M2M32c** (Mac Studio M2, 12 c / 32 GB, dedicated) behind the MacLustr Tunnel (BHS64 Caddy → wg1 10.67.0.20).
Everything goes through the gateway M1M32 and `mld` (`~/Desktop/cluster-skill/mld`).

## Topology

```
Internet → GoDaddy DNS (A www.ai-atlas.co + A ai-atlas.co → 51.161.112.61)
        → BHS64 Caddy (TLS Let's Encrypt, apex → www redirect)  →  WireGuard wg1  →  M2M32c:8320 (Next.js)
                                                                                      └─ rewrite /api/v1/* → 127.0.0.1:8321 (FastAPI, 2 uvicorn workers)
                                                                                      └─ ai-atlas-scheduler (aia schedule: connectors + jobs worker + backups)
                                                                                      └─ Postgres 17 + pgvector (db aiatlas) · Redis db 5 · ~/ai-atlas-data
        LLM factory: https://www.llm-api.io/v1 (MacLustr llm-api on M1M64, key "ai-atlas") — optional, extraction degrades gracefully
```

Node prerequisites (done 2026-09-11 by `mld bootstrap` + `mld prepare M2M32c` + Homebrew): node 26, pnpm, pm2 (LaunchAgent), uv + Python 3.12,
`postgresql@17`, `pgvector`, `redis` as `brew services`, role/db `aiatlas` (password `aiatlas`, localhost only), extensions `vector`, `pg_trgm`, `uuid-ossp`.

## Release procedure (from the laptop)

```bash
cd ~/Desktop/Projets/apps-web/ai-atlas
.venv/bin/pytest -q && (cd apps/web && pnpm typecheck)              # 1. tests + typecheck
deploy/render-manifest.sh --push                                     # 2. manifest with AIA_ADMIN_TOKEN + AIA_LLM_API_KEY → M1M32:~/dispatch/apps/ai-atlas.json
~/Desktop/cluster-skill/mld stage ~/Desktop/Projets/apps-web/ai-atlas ai-atlas   # 3. laptop → gateway staging (sync_excludes)
~/Desktop/cluster-skill/mld deploy ai-atlas --node M2M32c            # 4. rsync → node, hooks (venv, migrate, seed, pnpm build), PM2, health, tunnel route, registry
ssh M2M32c 'cd ~/apps/ai-atlas && nohup bash deploy/first-run.sh > ~/ai-atlas-data/logs/first-run.log 2>&1 &'   # 5. first time: initial corpus
curl -sI https://www.ai-atlas.co | head -1                           # 6. public check
```

### Canonical upgrade (2026-09-12) — first rollout of migration 0003

The `post_sync` hook runs `aia migrate` (0003 is additive) and `aia seed` (new benchmark variants, licences, org kinds). Right after the
deploy, canonicalize the production data once by hand (dry-run first, then apply; both are idempotent and never delete rows):

```bash
ssh M2M32c 'cd ~/apps/ai-atlas && export PATH=/opt/homebrew/opt/postgresql@17/bin:$PATH AIA_LOG_JSON=0 DATABASE_URL=postgresql+asyncpg://aiatlas:aiatlas@127.0.0.1:5432/aiatlas AIA_DATA_DIR=$HOME/ai-atlas-data && .venv/bin/aia backup && .venv/bin/aia canonicalize | tail -40'
ssh M2M32c 'cd ~/apps/ai-atlas && … .venv/bin/aia canonicalize --apply | tail -40 && .venv/bin/aia canonicalize --apply | tail -3'   # second pass must report 0 changes
```

The scheduler then keeps the data canonical (full pass nightly 03:30, light pass every 6 h — see docs/CANONICALIZATION.md).

`mld deploy` re-points `https://www.ai-atlas.co → M2M32c:8320` on BHS64 and runs the public health check. `mld heal` (every 5 min on M1M32)
restarts anything missing after a power cut. Secrets: `deploy/.admin-token`, `deploy/.llm-key` (git-ignored); rendered manifest in `deploy/rendered/`.

## Operations

```bash
~/Desktop/cluster-skill/mld status | grep ai-atlas
~/Desktop/cluster-skill/mld logs ai-atlas
ssh M2M32c 'cd ~/apps/ai-atlas && AIA_LOG_JSON=0 .venv/bin/aia status'         # connector table + queue depth
ssh M2M32c 'cd ~/apps/ai-atlas && AIA_LOG_JSON=0 .venv/bin/aia run huggingface --force'
ssh M2M32c 'cd ~/apps/ai-atlas && .venv/bin/aia backup'                         # pg_dump → ~/ai-atlas-data/backups (nightly 04:40 too)
scripts/backup-offnode.sh                                                       # copies dumps + raw archive to M1M32:~/backups/ai-atlas
curl -s https://www.ai-atlas.co/api/v1/stats | python3 -m json.tool | head      # live counters
```

Admin dashboard: `https://www.ai-atlas.co/admin` (token = `deploy/.admin-token`). Environment variables the processes read are listed in `.env.example`.

## Scaling

- More extraction throughput: run `aia worker` on other nodes with `DATABASE_URL` pointing at M2M32c (Postgres must then listen on the LAN —
  not enabled by default) or run additional `aia worker --kind llm_extract` processes on M2M32c.
- The LLM factory can point at any OpenAI-compatible server (`AIA_LLM_BASE_URL`), e.g. a second llm-api node.
- Raw archive grows with the number of changed snapshots (gzip, content-addressed). Disk: 423 GB free on M2M32c at launch.