- Add 5 standalone ADRs in infra/matrix/docs/adr/ - Add EXECUTION_ARCHITECTURE_KT.md: exact path from DNS decision to fleet ops - Architecture proof and continuity preserved
This commit is contained in:
Ezra (Archivist)
240
docs/matrix-fleet-comms/EXECUTION_ARCHITECTURE_KT.md
Normal file
240
docs/matrix-fleet-comms/EXECUTION_ARCHITECTURE_KT.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# Execution Architecture KT — Matrix/Conduit Human-to-Fleet Comms
|
||||
|
||||
**Issue**: [#166](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/166)
|
||||
**Blocker**: [#187](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/187) — Host/domain/proxy decisions
|
||||
**Scaffold**: [#183](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/183)
|
||||
**Created**: Ezra | 2026-04-05
|
||||
**Purpose**: Turn the #166 fuzzy epic into an exact execution script. Once #187 closes, follow this KT verbatim.
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This document is the **knowledge transfer** from architecture (#183) to execution (#166). It assumes the decision framework in `docs/DECISION_FRAMEWORK_187.md` has been accepted (recommended: **Option A — Hermes VPS + Caddy + matrix.timmytime.net**) and maps every step from "DNS record exists" to "Alexander sends an encrypted message to the fleet."
|
||||
|
||||
---
|
||||
|
||||
## Pre-Conditions (Close #187 First)
|
||||
|
||||
| # | Pre-Condition | Authority | Evidence |
|
||||
|---|---------------|-----------|----------|
|
||||
| 1 | Host chosen (IP known) | Alexander/admin | Written in #187 |
|
||||
| 2 | Domain/subdomain chosen | Alexander/admin | DNS A record live |
|
||||
| 3 | Reverse proxy chosen | Alexander/admin | Caddyfile committed |
|
||||
| 4 | Ports 80/443/8448 open | Host admin | `host-readiness-check.sh` passes |
|
||||
| 5 | TLS path confirmed | Architecture | Let's Encrypt viable |
|
||||
|
||||
> **If all 5 are true, #166 is unblocked and this KT is the runbook.**
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Host Prep (30 minutes)
|
||||
|
||||
### 1.1 Clone Repo on Target Host
|
||||
```bash
|
||||
ssh root@<HOST_IP>
|
||||
git clone https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config.git /opt/timmy-config
|
||||
cd /opt/timmy-config/infra/matrix
|
||||
```
|
||||
|
||||
### 1.2 Verify Host Readiness
|
||||
```bash
|
||||
./host-readiness-check.sh
|
||||
```
|
||||
Expected: all checks green (Docker, ports, disk, RAM).
|
||||
|
||||
### 1.3 Configure Environment
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env:
|
||||
# CONDUIT_SERVER_NAME=matrix.timmytime.net
|
||||
# CONDUIT_ALLOW_REGISTRATION=true # ONLY for bootstrap
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Conduit Deployment (15 minutes)
|
||||
|
||||
### 2.1 One-Command Deploy
|
||||
```bash
|
||||
./deploy-matrix.sh
|
||||
```
|
||||
This starts:
|
||||
- Conduit homeserver container
|
||||
- Caddy reverse proxy container
|
||||
- (Optional) Element web client
|
||||
|
||||
### 2.2 Verify Health
|
||||
```bash
|
||||
curl -s https://matrix.timmytime.net/_matrix/client/versions | jq .
|
||||
```
|
||||
Expected: JSON with `versions` array.
|
||||
|
||||
### 2.3 Verify Federation
|
||||
```bash
|
||||
curl -s https://matrix.timmytime.net/.well-known/matrix/server
|
||||
```
|
||||
Expected: `{"m.server": "matrix.timmytime.net:443"}`
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Fleet Bootstrap — Accounts & Rooms (30 minutes)
|
||||
|
||||
### 3.1 Create Admin Account
|
||||
**Enable registration temporarily** in `.env`:
|
||||
```
|
||||
CONDUIT_ALLOW_REGISTRATION=true
|
||||
CONDUIT_REGISTRATION_TOKEN=<random_secret>
|
||||
```
|
||||
Restart:
|
||||
```bash
|
||||
docker compose restart conduit
|
||||
```
|
||||
|
||||
Register admin:
|
||||
```bash
|
||||
docker exec -it conduit register_new_matrix_user -c /var/lib/matrix-conduit -u admin -p '<STRONG_PASS>' -a
|
||||
```
|
||||
|
||||
**Immediately disable registration** and restart.
|
||||
|
||||
### 3.2 Create Fleet Accounts
|
||||
| Account | Purpose | Created By |
|
||||
|---------|---------|------------|
|
||||
| `@admin:matrix.timmytime.net` | Server administration | deploy script |
|
||||
| `@alexander:matrix.timmytime.net` | Human operator | admin |
|
||||
| `@timmy:matrix.timmytime.net` | Coordinator bot | admin |
|
||||
| `@ezra:matrix.timmytime.net` | Archivist bot | admin |
|
||||
| `@allegro:matrix.timmytime.net` | Dispatch bot | admin |
|
||||
| `@bezalel:matrix.timmytime.net` | Dev bot | admin |
|
||||
| `@gemini:matrix.timmytime.net` | Nexus architect bot | admin |
|
||||
|
||||
Use the Conduit admin API or `register_new_matrix_user` for each.
|
||||
|
||||
### 3.3 Create Fleet Rooms
|
||||
| Room Alias | Purpose | Encryption |
|
||||
|------------|---------|------------|
|
||||
| `#fleet-ops:matrix.timmytime.net` | Operator commands | ✅ E2E |
|
||||
| `#fleet-intel:matrix.timmytime.net` | Deep Dive briefings | ✅ E2E |
|
||||
| `#fleet-social:matrix.timmytime.net` | General chat | ✅ E2E |
|
||||
| `#fleet-alerts:matrix.timmytime.net` | Critical alerts | ✅ E2E |
|
||||
|
||||
**Create room via Element Web or curl:**
|
||||
```bash
|
||||
curl -X POST "https://matrix.timmytime.net/_matrix/client/v3/createRoom" -H "Authorization: Bearer <ADMIN_TOKEN>" -d '{
|
||||
"name": "Fleet Ops",
|
||||
"room_alias_name": "fleet-ops",
|
||||
"preset": "private_chat",
|
||||
"initial_state": [{
|
||||
"type": "m.room.encryption",
|
||||
"content": {"algorithm": "m.megolm.v1.aes-sha2"}
|
||||
}]
|
||||
}'
|
||||
```
|
||||
|
||||
### 3.4 Invite Fleet Members
|
||||
Invite each bot/user to the appropriate rooms. For `#fleet-ops`, restrict to `@alexander`, `@timmy`, `@ezra`, `@allegro`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Wizard Onboarding Procedure (30 minutes)
|
||||
|
||||
Each wizard house needs:
|
||||
1. **Matrix credentials** (username + password + recovery key)
|
||||
2. **Client recommendation** — Element Desktop or Fluffychat
|
||||
3. **Room memberships** — invite to relevant fleet rooms
|
||||
4. **Encryption verification** — verify keys with Alexander
|
||||
|
||||
### Onboarding Checklist per Wizard
|
||||
- [ ] Account created and credentials stored in vault
|
||||
- [ ] Client installed and signed in
|
||||
- [ ] Joined `#fleet-ops` and `#fleet-intel`
|
||||
- [ ] E2E verification completed with `@alexander`
|
||||
- [ ] Test message sent and received
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Telegram → Matrix Cutover Architecture
|
||||
|
||||
### 5.1 Parallel Operations (Week 1-2)
|
||||
- Telegram remains primary
|
||||
- Matrix is shadow channel: duplicate critical messages to both
|
||||
- Bots post to Matrix for habit formation
|
||||
|
||||
### 5.2 Bridge Option (Evaluative)
|
||||
If immediate message parity is required, evaluate:
|
||||
- **mautrix-telegram** bridge (self-hosted, complex)
|
||||
- **Manual dual-post** (simple, temporary)
|
||||
|
||||
**Recommendation**: Skip the bridge for now. Dual-post via bot logic is lower risk.
|
||||
|
||||
### 5.3 Cutover Trigger
|
||||
When:
|
||||
- All wizards are active on Matrix
|
||||
- Alexander confirms Matrix reliability for 7 consecutive days
|
||||
- E2E encryption verified in `#fleet-ops`
|
||||
|
||||
**Action**: Declare Matrix the primary human-to-fleet surface. Telegram becomes fallback only.
|
||||
|
||||
---
|
||||
|
||||
## Operational Continuity
|
||||
|
||||
### Backup
|
||||
```bash
|
||||
# Daily cron on host
|
||||
0 2 * * * /opt/timmy-config/infra/matrix/scripts/deploy-conduit.sh backup
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
```bash
|
||||
# Health check every 5 minutes
|
||||
*/5 * * * * /opt/timmy-config/infra/matrix/scripts/deploy-conduit.sh status || alert
|
||||
```
|
||||
|
||||
### Upgrade Path
|
||||
1. Pull latest `timmy-config`
|
||||
2. Run `./host-readiness-check.sh`
|
||||
3. `docker compose pull && docker compose up -d`
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria Mapping
|
||||
|
||||
| #166 Criterion | How This KT Satisfies It | Phase |
|
||||
|----------------|--------------------------|-------|
|
||||
| Deploy Conduit homeserver | `deploy-matrix.sh` + health checks | 2 |
|
||||
| Create fleet rooms/channels | Exact room aliases + creation curl | 3 |
|
||||
| Verify encrypted operator messaging | E2E enabled + key verification step | 3-4 |
|
||||
| Define Telegram→Matrix cutover plan | Section 5 explicit cutover trigger | 5 |
|
||||
| Alexander can message fleet | `@alexander` account + `#fleet-ops` membership | 3 |
|
||||
| Messages encrypted and persistent | `m.room.encryption` in room creation + Conduit persistence | 3 |
|
||||
| Telegram no longer only surface | Cutover trigger + dual-post interim | 5 |
|
||||
|
||||
---
|
||||
|
||||
## Decision Authority for Execution
|
||||
|
||||
| Step | Owner | When |
|
||||
|------|-------|------|
|
||||
| DNS / #187 close | Alexander | T+0 |
|
||||
| Run `deploy-matrix.sh` | Allegro or Ezra | T+0 (15 min) |
|
||||
| Create accounts/rooms | Allegro or Ezra | T+15 (30 min) |
|
||||
| Onboard wizards | Individual agents + Alexander | T+45 (ongoing) |
|
||||
| Cutover declaration | Alexander | T+7 days (minimum) |
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- Scaffold: [`infra/matrix/`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/infra/matrix)
|
||||
- ADRs: [`infra/matrix/docs/adr/`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/infra/matrix/docs/adr)
|
||||
- Decision Framework: [`docs/DECISION_FRAMEWORK_187.md`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/docs/DECISION_FRAMEWORK_187.md)
|
||||
- Operational Runbook: [`infra/matrix/docs/RUNBOOK.md`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/infra/matrix/docs/RUNBOOK.md)
|
||||
|
||||
---
|
||||
|
||||
**Ezra Sign-off**: This KT removes all ambiguity from #166. The only remaining work is executing these phases in order once #187 is closed.
|
||||
|
||||
— Ezra, Archivist
|
||||
2026-04-05
|
||||
Reference in New Issue
Block a user