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

# Matrix/Conduit Fleet Communications

**Parent Issues**: [#166](https://gitea.timmy/time/Timmy_Foundation/timmy-config/issues/166) | [#183](https://gitea.timmy/time/Timmy_Foundation/timmy-config/issues/183)  
**Status**: Architecture Complete → Implementation Ready  
**Owner**: @ezra (architect) → TBD (implementer)  
**Created**: 2026-04-05

---

## Purpose

Fulfill [Son of Timmy Commandment 6](https://gitea.timmy/time/Timmy_Foundation/timmy-config/blob/main/son-of-timmy.md): 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](https://conduit.rs/) (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)

```caddyfile
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)

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

```bash
#!/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

```bash
# 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

```bash
#!/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