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

Matrix/Conduit Fleet Communications

Parent Issues: #166 | #183
Status: Architecture Complete → Implementation Ready
Owner: @ezra (architect) → TBD (implementer)
Created: 2026-04-05

---

Purpose

Fulfill Son of Timmy Commandment 6: establish Matrix/Conduit as the sovereign operator surface for human-to-fleet encrypted communication, moving beyond Telegram as the sole command channel.

---

Architecture Decision Records

ADR-1: Homeserver Selection — Conduit

Decision: Use Conduit (Rust-based Matrix homeserver)

Rationale:

Criteria	Conduit	Synapse	Dendrite
Resource Usage	Low (Rust)	High (Python)	Medium (Go)
Federation	Full	Full	Partial
Deployment Complexity	Simple binary	Complex stack	Medium
SQLite Support	Yes (simpler)	No (requires PG)	Yes
Federation Stability	Production	Production	Beta

Verdict: Conduit's low resource footprint and SQLite option make it ideal for fleet deployment.

ADR-2: Host Selection

Decision: Deploy on existing Gitea VPS (143.198.27.163:3000) initially

Rationale:

• Existing infrastructure, known operational state
• Sufficient resources (can upgrade if federation load grows)
• Consolidated with Gitea simplifies backup/restore

Future: Dedicated Matrix VPS if federation traffic justifies separation.

ADR-3: Federation Strategy

Decision: Full federation enabled from day one

Rationale:

• Alexander may need to message from any Matrix account
• Fleet bots can federate to other homeservers if needed
• Nostr bridge experiments (#830) may benefit from federation

Implication: Requires valid TLS certificate and public DNS.

---

Deployment Scaffold

Directory Structure

/opt/conduit/
├── conduit               # Binary
├── conduit.toml          # Configuration
├── data/                 # SQLite + media (backup target)
│   ├── conduit.db
│   └── media/
├── logs/                 # Rotated logs
└── scripts/              # Operational helpers
    ├── backup.sh
    └── rotate-logs.sh

Port Allocation

Service	Port	Protocol	Notes
Conduit HTTP	8448	TCP	Matrix client-server API
Conduit Federation	8448	TCP	Same port, different SRV
Element Web	8080	TCP	Optional web client

DNS Requirements:

• matrix.timmy.foundation → A record to VPS IP
• _matrix._tcp.timmy.foundation → SRV record for federation

Reverse Proxy (Caddy)

matrix.timmy.foundation {
    reverse_proxy localhost:8448
    
    header {
        X-Frame-Options DENY
        X-Content-Type-Options nosniff
    }
    
    tls {
        # Let's Encrypt automatic
    }
}

Conduit Configuration (conduit.toml)

[global]
server_name = "timmy.foundation"
database_path = "/opt/conduit/data/conduit.db"
port = 8448
max_request_size = 20000000  # 20MB for file uploads

[registration]
# Closed registration - admin creates accounts
enabled = false

[ federation]
enabled = true
disabled_servers = []

[ media ]
max_file_size = 50000000  # 50MB
max_media_size = 100000000  # 100MB total cache

[ retention ]
enabled = true
default_room_retention = "30d"

---

Prerequisites Checklist

Infrastructure

• DNS A record: matrix.timmy.foundation → 143.198.27.163
• DNS SRV record: _matrix._tcp.timmy.foundation → 0 0 8448 matrix.timmy.foundation
• Firewall: TCP 8448 open to world (federation)
• Firewall: TCP 8080 open to world (Element Web, optional)

Dependencies

• Conduit binary (latest release: check https://gitlab.com/famedly/conduit)
• Caddy installed (or nginx if preferred)
• SQLite (usually present, verify version ≥ 3.30)
• systemd (for service management)

Accounts (Bootstrap)

• @admin:timmy.foundation — Server admin
• @alexander:timmy.foundation — Operator primary
• @ezra:timmy.foundation — Archivist bot
• @timmy:timmy.foundation — Coordinator bot

Rooms (Bootstrap)

• #fleet-ops:timmy.foundation — Operator-to-fleet command channel
• #fleet-intel:timmy.foundation — Intelligence sharing
• #fleet-social:timmy.foundation — General chat

---

Implementation Phases

Phase 1: Infrastructure (Est: 2 hours)

1. Create DNS records
2. Open firewall ports
3. Download Conduit binary
4. Create directory structure

Phase 2: Deployment (Est: 2 hours)

1. Write conduit.toml
2. Create systemd service
3. Configure Caddy reverse proxy
4. Start Conduit, verify health

Phase 3: Bootstrap (Est: 1 hour)

1. Create admin account via CLI
2. Create user accounts
3. Create rooms, set permissions
4. Verify end-to-end encryption

Phase 4: Migration Planning (Est: 4 hours)

1. Map Telegram channels to Matrix rooms
2. Design bridge architecture (if needed)
3. Create cutover timeline
4. Document operator onboarding

---

Operational Runbooks

Backup

#!/bin/bash
# /opt/conduit/scripts/backup.sh
BACKUP_DIR="/backups/conduit/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"

# Stop Conduit briefly for consistent snapshot
systemctl stop conduit

cp /opt/conduit/data/conduit.db "$BACKUP_DIR/"
cp /opt/conduit/conduit.toml "$BACKUP_DIR/"
cp -r /opt/conduit/data/media "$BACKUP_DIR/"

systemctl start conduit

# Compress and upload to S3/backup target
tar czf "$BACKUP_DIR.tar.gz" -C "$BACKUP_DIR" .
# aws s3 cp "$BACKUP_DIR.tar.gz" s3://timmy-backups/conduit/

Account Creation

# As admin, create new user
curl -X POST \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"newuser","password":"secure_password_123"}' \
  https://matrix.timmy.foundation/_matrix/client/v3/register

Health Check

#!/bin/bash
# /opt/conduit/scripts/health.sh
curl -s https://matrix.timmy.foundation/_matrix/client/versions | jq .

---

Cross-Issue Linkages

Issue	Relationship	Action
#166	Parent epic	This scaffold enables #166 execution
#183	Scaffold child	This document fulfills #183 acceptance criteria
#830	Deep Dive	Matrix rooms can receive #830 intelligence briefings
#137	Related	Verify no conflict with existing comms work
#138	Related	Verify no conflict with Nostr bridge
#147	Related	Check if Matrix replaces or supplements existing plans

---

Artifacts Created

File	Purpose
docs/matrix-fleet-comms/README.md	This architecture document
deploy/conduit/conduit.toml	Production configuration
deploy/conduit/conduit.service	systemd service definition
deploy/conduit/Caddyfile	Reverse proxy configuration
deploy/conduit/scripts/backup.sh	Backup automation
deploy/conduit/scripts/health.sh	Health check script

---

Next Actions

1. DNS: Create matrix.timmy.foundation A and SRV records
2. Firewall: Open TCP 8448 on VPS
3. Install: Download and configure Conduit
4. Bootstrap: Create initial accounts and rooms
5. Onboard: Add Alexander, test end-to-end encryption
6. Migrate: Plan Telegram→Matrix transition

---

Ezra's Sign-off: This scaffold transforms #166 from fuzzy epic to executable implementation plan. All prerequisites are named, all acceptance criteria are mapped to artifacts, and the deployment path is phase-gated for incremental delivery.

— Ezra, Archivist
2026-04-05