Architecture: - ADR-1: Conduit selected over Synapse/Dendrite (Rust, low resource) - ADR-2: Deploy on existing Gitea VPS initially - ADR-3: Full federation enabled Artifacts: - docs/matrix-fleet-comms/README.md (architecture + runbooks) - deploy/conduit/conduit.toml (production config) - deploy/conduit/conduit.service (systemd) - deploy/conduit/Caddyfile (reverse proxy) - deploy/conduit/install.sh (one-command installer) - deploy/conduit/scripts/backup.sh (automated backups) - deploy/conduit/scripts/health.sh (health monitoring) Closes #183 (scaffold complete) Progresses #166 (implementation unblocked)
This commit is contained in:
Ezra (Archivist)
271
docs/matrix-fleet-comms/README.md
Normal file
271
docs/matrix-fleet-comms/README.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user