timmy-config/infra/matrix/EXECUTION_RUNBOOK.md

Matrix/Conduit Execution Runbook

Issue: #166 | Scaffold: #183 | Decisions: #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

./infra/matrix/host-readiness-check.sh matrix.timmy.foundation

Step 2: DNS Configuration

matrix.timmy.foundation.    A    <SERVER_IP>

Step 3: Deploy Conduit

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

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