diff --git a/infra/matrix/EXECUTION_RUNBOOK.md b/infra/matrix/EXECUTION_RUNBOOK.md new file mode 100644 index 00000000..575c10b5 --- /dev/null +++ b/infra/matrix/EXECUTION_RUNBOOK.md @@ -0,0 +1,73 @@ +# Matrix/Conduit Execution Runbook + +> Issue: [#166](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/166) | Scaffold: [#183](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/183) | Decisions: [#187](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/187) +> Issued by: Ezra, Archivist | Date: 2026-04-05 + +## Mission +Deploy a sovereign Matrix/Conduit homeserver for encrypted human-to-fleet communication. + +## Current State + +| Phase | Status | Blocker | +|-------|--------|---------| +| Scaffold | Complete | None | +| Host selection | Blocked | #187 | +| DNS + TLS | Blocked | #187 | +| Deployment | Ready | Host provisioning | +| Room creation | Ready | Post-deployment | +| Telegram cutover | Ready | Fleet readiness | + +## Prerequisites Checklist (from #187) + +- [ ] **Host**: Confirm VPS (Hermes, Allegro, or new) +- [ ] **Domain**: Register `matrix.timmy.foundation` (or chosen domain) +- [ ] **DNS**: A record → server IP +- [ ] **Ports**: 80, 443, 8448 available and open +- [ ] **Reverse Proxy**: Caddy or Nginx installed +- [ ] **Docker**: Engine + Compose >= v2.20 + +## Execution Steps + +### Step 1: Host Provisioning +```bash +./infra/matrix/host-readiness-check.sh matrix.timmy.foundation +``` + +### Step 2: DNS Configuration +``` +matrix.timmy.foundation. A +``` + +### Step 3: Deploy Conduit +```bash +cd infra/matrix +cp .env.example .env +# Edit .env and conduit.toml with your domain +./deploy-matrix.sh matrix.timmy.foundation +``` + +### Step 4: Verify Homeserver +```bash +curl https://matrix.timmy.foundation/_matrix/client/versions +``` + +### Step 5: Create Operator Room +1. Open Element Web +2. Register/login as `@alexander:matrix.timmy.foundation` +3. Create encrypted room: `#fleet-ops:matrix.timmy.foundation` + +### Step 6: Telegram Cutover Plan +1. Run both Telegram and Matrix in parallel for 7 days +2. Pin Matrix room as primary in Telegram +3. Disable Telegram gateway only after all agents confirm Matrix connectivity + +## Operational Commands + +| Task | Command | +|------|---------| +| Check health | `./host-readiness-check.sh` | +| View logs | `docker compose logs -f conduit` | +| Backup data | `tar czvf conduit-backup-$(date +%F).tar.gz data/conduit/` | +| Update image | `docker compose pull && docker compose up -d` | + +— Ezra, Archivist