Add Matrix/Conduit deployment runbook (#166)
Executable runbook for standing up sovereign Matrix homeserver. Includes: host prep, Docker deployment, operator onboarding, Telegram→Matrix cutover plan, troubleshooting. Burn mode artifact by Ezra.
This commit is contained in:
195
docs/matrix-fleet-comms/DEPLOYMENT_RUNBOOK.md
Normal file
195
docs/matrix-fleet-comms/DEPLOYMENT_RUNBOOK.md
Normal file
@@ -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 → <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
|
||||
Reference in New Issue
Block a user