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)

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

### 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=<generate_strong_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": "<secure_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