spb/ai-atlas

1# Deploying AI Atlas on MacLustr23Production runs on **M2M32c** (Mac Studio M2, 12 c / 32 GB, dedicated) behind the MacLustr Tunnel (BHS64 Caddy → wg1 10.67.0.20).4Everything goes through the gateway M1M32 and `mld` (`~/Desktop/cluster-skill/mld`).56## Topology78```9Internet → GoDaddy DNS (A www.ai-atlas.co + A ai-atlas.co → 51.161.112.61)10        → BHS64 Caddy (TLS Let's Encrypt, apex → www redirect)  →  WireGuard wg1  →  M2M32c:8320 (Next.js)11                                                                                      └─ rewrite /api/v1/* → 127.0.0.1:8321 (FastAPI, 2 uvicorn workers)12                                                                                      └─ ai-atlas-scheduler (aia schedule: connectors + jobs worker + backups)13                                                                                      └─ Postgres 17 + pgvector (db aiatlas) · Redis db 5 · ~/ai-atlas-data14        LLM factory: https://www.llm-api.io/v1 (MacLustr llm-api on M1M64, key "ai-atlas") — optional, extraction degrades gracefully15```1617Node prerequisites (done 2026-09-11 by `mld bootstrap` + `mld prepare M2M32c` + Homebrew): node 26, pnpm, pm2 (LaunchAgent), uv + Python 3.12,18`postgresql@17`, `pgvector`, `redis` as `brew services`, role/db `aiatlas` (password `aiatlas`, localhost only), extensions `vector`, `pg_trgm`, `uuid-ossp`.1920## Release procedure (from the laptop)2122```bash23cd ~/Desktop/Projets/apps-web/ai-atlas24.venv/bin/pytest -q && (cd apps/web && pnpm typecheck)              # 1. tests + typecheck25deploy/render-manifest.sh --push                                     # 2. manifest with AIA_ADMIN_TOKEN + AIA_LLM_API_KEY → M1M32:~/dispatch/apps/ai-atlas.json26~/Desktop/cluster-skill/mld stage ~/Desktop/Projets/apps-web/ai-atlas ai-atlas   # 3. laptop → gateway staging (sync_excludes)27~/Desktop/cluster-skill/mld deploy ai-atlas --node M2M32c            # 4. rsync → node, hooks (venv, migrate, seed, pnpm build), PM2, health, tunnel route, registry28ssh M2M32c 'cd ~/apps/ai-atlas && nohup bash deploy/first-run.sh > ~/ai-atlas-data/logs/first-run.log 2>&1 &'   # 5. first time: initial corpus29curl -sI https://www.ai-atlas.co | head -1                           # 6. public check30```3132### Canonical upgrade (2026-09-12) — first rollout of migration 00033334The `post_sync` hook runs `aia migrate` (0003 is additive) and `aia seed` (new benchmark variants, licences, org kinds). Right after the35deploy, canonicalize the production data once by hand (dry-run first, then apply; both are idempotent and never delete rows):3637```bash38ssh 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'39ssh M2M32c 'cd ~/apps/ai-atlas && … .venv/bin/aia canonicalize --apply | tail -40 && .venv/bin/aia canonicalize --apply | tail -3'   # second pass must report 0 changes40```4142The scheduler then keeps the data canonical (full pass nightly 03:30, light pass every 6 h — see docs/CANONICALIZATION.md).4344`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)45restarts anything missing after a power cut. Secrets: `deploy/.admin-token`, `deploy/.llm-key` (git-ignored); rendered manifest in `deploy/rendered/`.4647## Operations4849```bash50~/Desktop/cluster-skill/mld status | grep ai-atlas51~/Desktop/cluster-skill/mld logs ai-atlas52ssh M2M32c 'cd ~/apps/ai-atlas && AIA_LOG_JSON=0 .venv/bin/aia status'         # connector table + queue depth53ssh M2M32c 'cd ~/apps/ai-atlas && AIA_LOG_JSON=0 .venv/bin/aia run huggingface --force'54ssh M2M32c 'cd ~/apps/ai-atlas && .venv/bin/aia backup'                         # pg_dump → ~/ai-atlas-data/backups (nightly 04:40 too)55scripts/backup-offnode.sh                                                       # copies dumps + raw archive to M1M32:~/backups/ai-atlas56curl -s https://www.ai-atlas.co/api/v1/stats | python3 -m json.tool | head      # live counters57```5859Admin dashboard: `https://www.ai-atlas.co/admin` (token = `deploy/.admin-token`). Environment variables the processes read are listed in `.env.example`.6061## Scaling6263- More extraction throughput: run `aia worker` on other nodes with `DATABASE_URL` pointing at M2M32c (Postgres must then listen on the LAN —64  not enabled by default) or run additional `aia worker --kind llm_extract` processes on M2M32c.65- The LLM factory can point at any OpenAI-compatible server (`AIA_LLM_BASE_URL`), e.g. a second llm-api node.66- Raw archive grows with the number of changed snapshots (gzip, content-addressed). Disk: 423 GB free on M2M32c at launch.67