diff --git a/docs/matrix-fleet-comms/DEPLOYMENT_RUNBOOK.md b/docs/matrix-fleet-comms/DEPLOYMENT_RUNBOOK.md new file mode 100644 index 00000000..bddeab17 --- /dev/null +++ b/docs/matrix-fleet-comms/DEPLOYMENT_RUNBOOK.md @@ -0,0 +1,195 @@ +# Matrix/Conduit Deployment Runbook +# Issue #166 — Human-to-Fleet Encrypted Communication +# Created: Ezra, Burn Mode | 2026-04-05 + +## Pre-Flight Checklist + +Before running this playbook, ensure: +- [ ] Host provisioned with ports 80/443/8448 open +- [ ] Domain `matrix.timmytime.net` delegated to host IP +- [ ] Docker + Docker Compose installed +- [ ] `infra/matrix/` scaffold cloned to host + +## Quick Start (One Command) + +```bash +cd infra/matrix && ./deploy.sh --host $(curl -s ifconfig.me) --domain matrix.timmytime.net +``` + +## Manual Deployment Steps + +### 1. Host Preparation + +```bash +# Update system +sudo apt update && sudo apt upgrade -y + +# Install Docker +curl -fsSL https://get.docker.com | sh +sudo usermod -aG docker $USER +newgrp docker + +# Install Docker Compose +sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose +sudo chmod +x /usr/local/bin/docker-compose +``` + +### 2. Domain Configuration + +Ensure DNS A record: +``` +matrix.timmytime.net → +``` + +### 3. Scaffold Deployment + +```bash +git clone http://143.198.27.163:3000/Timmy_Foundation/timmy-config.git +cd timmy-config/infra/matrix +``` + +### 4. Environment Configuration + +```bash +# Copy and edit environment +cp .env.template .env +nano .env + +# Required values: +# DOMAIN=matrix.timmytime.net +# POSTGRES_PASSWORD= +# CONDUIT_MAX_REQUEST_SIZE=20000000 +``` + +### 5. Launch Services + +```bash +# Start Conduit + Element Web +docker-compose up -d + +# Verify health +docker-compose ps +docker-compose logs -f conduit +``` + +### 6. Federation Test + +```bash +# Test .well-known delegation +curl https://matrix.timmytime.net/.well-known/matrix/server +curl https://matrix.timmytime.net/.well-known/matrix/client + +# Test federation API +curl https://matrix.timmytime.net:8448/_matrix/key/v2/server +``` + +## Post-Deployment: Operator Onboarding + +### Create Admin Account + +```bash +# Via Conduit admin API (first user = admin automatically) +curl -X POST "https://matrix.timmytime.net/_matrix/client/r0/register" \ + -H "Content-Type: application/json" \ + -d '{ + "username": "alexander", + "password": "", + "auth": {"type": "m.login.dummy"} + }' +``` + +### Fleet Room Bootstrap + +```bash +# Create rooms via API (using admin token) +export TOKEN=$(cat ~/.matrix_admin_token) + +# Operators room +curl -X POST "https://matrix.timmytime.net/_matrix/client/r0/createRoom" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Operators", + "topic": "Human-to-fleet command surface", + "preset": "private_chat", + "encryption": true + }' + +# Fleet General room +curl -X POST "https://matrix.timmytime.net/_matrix/client/r0/createRoom" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Fleet General", + "topic": "All wizard houses — general coordination", + "preset": "public_chat", + "encryption": true + }' +``` + +## Troubleshooting + +### Port 8448 Blocked + +```bash +# Verify federation port +nc -zv matrix.timmytime.net 8448 + +# Check firewall +sudo ufw status +sudo ufw allow 8448/tcp +``` + +### SSL Certificate Issues + +```bash +# Force Caddy certificate refresh +docker-compose exec caddy rm -rf /data/caddy/certificates +docker-compose restart caddy +``` + +### Conduit Database Migration + +```bash +# Backup before migration +docker-compose exec conduit sqlite3 /var/lib/matrix-conduit/conduit.db ".backup /backup/conduit-$(date +%Y%m%d).db" +``` + +## Telegram → Matrix Cutover Plan + +### Phase 0: Parallel (Week 1-2) +- Matrix rooms operational +- Telegram still primary +- Fleet agents join both + +### Phase 1: Operator Verification (Week 3) +- Alexander confirms Matrix reliability +- Critical alerts dual-posted + +### Phase 2: Fleet Gateway Migration (Week 4) +- Hermes gateway adds Matrix platform +- Telegram becomes fallback + +### Phase 3: Telegram Deprecation (Week 6-8) +- 30-day overlap period +- Final cutover announced +- Telegram bots archived + +## Verification Commands + +```bash +# Health check +curl -s https://matrix.timmytime.net/_matrix/client/versions | jq . + +# Federation check +curl -s https://federationtester.matrix.org/api/report?server_name=matrix.timmytime.net | jq '.FederationOK' + +# Element Web check +curl -s -o /dev/null -w "%{http_code}" https://element.timmytime.net +``` + +--- + +**Artifact**: `docs/matrix-fleet-comms/DEPLOYMENT_RUNBOOK.md` +**Issue**: #166 +**Author**: Ezra | Burn Mode | 2026-04-05