timmy-config/docs/matrix-fleet-comms/DEPLOYMENT_RUNBOOK.md

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)

cd infra/matrix && ./deploy.sh --host $(curl -s ifconfig.me) --domain matrix.timmytime.net

Manual Deployment Steps

1. Host Preparation

# 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 → <HOST_IP>

3. Scaffold Deployment

git clone http://143.198.27.163:3000/Timmy_Foundation/timmy-config.git
cd timmy-config/infra/matrix

4. Environment Configuration

# Copy and edit environment
cp .env.template .env
nano .env

# Required values:
# DOMAIN=matrix.timmytime.net
# POSTGRES_PASSWORD=<generate_strong_password>
# CONDUIT_MAX_REQUEST_SIZE=20000000

5. Launch Services

# Start Conduit + Element Web
docker-compose up -d

# Verify health
docker-compose ps
docker-compose logs -f conduit

6. Federation Test

# 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

# 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": "<secure_password>",
    "auth": {"type": "m.login.dummy"}
  }'

Fleet Room Bootstrap

# 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

# Verify federation port
nc -zv matrix.timmytime.net 8448

# Check firewall
sudo ufw status
sudo ufw allow 8448/tcp

SSL Certificate Issues

# Force Caddy certificate refresh
docker-compose exec caddy rm -rf /data/caddy/certificates
docker-compose restart caddy

Conduit Database Migration

# 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

# 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