Operations
Last Updated: 2026-06-11
Runbooks for production deployment, self-hosted installer (alpha), and AT Protocol OAuth / PDS origin behavior. Local onboarding stays in Getting started.
Pages
| Document | Summary |
|---|---|
| Production deployment | HTTPS single-origin topology, gateway + static UI, env checklist, release image |
| App edge deployment | infra/app Pulumi stack — Caddy on app.*, file-explorer rsync, gateway proxy |
| Data (managed Postgres) | infra/data Pulumi stack — DO Postgres, firewall, bootstrap + DATABASE_URL wiring |
| Self-hosted troubleshooting | ~/.substratum logs, gateway manifest, OAuth 400 on Express install, alpha support checklist |
| OAuth and PDS origins | Same-origin rules, discoverable vs loopback OAuth metadata, loopback PDS Sec-Fetch-Site concerns |
| Catalog vs blockstore storage | Postgres catalog vs file bytes ratio, capacity planning, how to measure on self-hosted |
| Marketing landing and macOS releases | Pulumi marketing stack, ~/.ssh/substratum-do rsync, Caddy/TLS on substratum.cloud, Spaces .dmg releases |
| Garage v1 rollout | Phased PDS hosting, entitlement enforcement, manual billing, admin.* operator UI + Discourse — launch checklist for 0–500 users |
| PDS deployment | pds.substratum.cloud — Tranquil PDS upstream, authz proxy, Caddy TLS (Garage Phase 3) |
| Entitlement admin procedures | Grant/lapse via admin.* UI + admin API; staff DID provisioning (Garage) |
| Admin edge deployment | infra/admin Pulumi stack — Caddy on admin.*, SPA rsync, ops-api proxy |
| PDS account migration | Leave Substratum PDS for Bluesky or self-hosting — PDS MOOver recommended |
Dev vs production at a glance
| Topic | Local dev (Compose edge) | Production |
|---|---|---|
| App URL | http://127.0.0.1:8080 | https://your-domain (must match PUBLIC_BASE_URL) |
| UI delivery | Vite :14200 behind nginx (not forwarded on host) | Built file-explorer static assets behind CDN / reverse proxy |
| OAuth client | Loopback metadata (atproto_localhost_client_metadata) | Discoverable metadata at /.well-known/oauth-client-metadata.json |
| User PDS | Local Tranquil PDS at http://localhost:3000 (authz proxy; optional) | User’s home PDS (e.g. Bluesky, Tangled, self-hosted) |
| Session cookie | substratum_session on edge origin | Same — must be set on the same origin as the SPA |
| Self-hosted edge | Installer troubleshooting (:35480, ~/.substratum/logs) | N/A (managed hosting) |