Migration: consolidate Echo6 docs to cortex with full infrastructure cleanup sync
- Documents recent infrastructure cleanup (8 CTs destroyed, 35 DNS records removed, Headscale cleanup) - Adds 24 new runbooks covering Authentik, PeerTube, Meshtastic, RECON, Proxmox, Mailcow, Internet Archive, GPU routing - Adds project documentation for headscale, vaultwarden, peertube, matrix, mmud, advbbs, arr stack - Updates services.md, environment.md, caddy.md, authentik.md to match live infrastructure - Removes 4 deprecated runbook duplicates (canonical versions live in projects/) - Adds .gitignore for binary archives and editor temp files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
89834796ff
commit
e9231ac24a
93 changed files with 51223 additions and 254 deletions
122
PHASE6_DECISION.md
Normal file
122
PHASE6_DECISION.md
Normal file
|
|
@ -0,0 +1,122 @@
|
|||
# Phase 6 Decision Summary
|
||||
# Generated: 2026-04-09
|
||||
|
||||
## 1. Is Hookshot the Right Choice?
|
||||
|
||||
**NO.** Hookshot cannot be used for this use case.
|
||||
|
||||
**Reason:** Hookshot's E2EE implementation is incompatible with MAS (Matrix
|
||||
Authentication Service). Echo6's Synapse uses MAS. All mautrix-signal portal
|
||||
rooms use E2BE encryption. Hookshot cannot establish crypto sessions when MAS
|
||||
is active (GitHub issues #1084, #980 — both OPEN as of March 2026). The webhook
|
||||
payloads would contain useless ciphertext, not plaintext.
|
||||
|
||||
This is a hard blocker with no workaround short of disabling MAS (breaks all
|
||||
user auth) or disabling E2BE on the bridge (exposes Signal messages in transit).
|
||||
|
||||
## 2. Recommended Alternative: Synapse Retention + Export Script
|
||||
|
||||
Instead of hookshot, a much simpler approach achieves the same goal:
|
||||
|
||||
### Step 1: Synapse Config (2 lines)
|
||||
```yaml
|
||||
redaction_retention_period: null # Never censor redacted content
|
||||
experimental_features:
|
||||
msc2815_enabled: true # Allow moderator access to redacted content
|
||||
```
|
||||
|
||||
This preserves ALL event content in Synapse's Postgres forever, including
|
||||
redacted messages. MSC2815 provides API access to the original content.
|
||||
|
||||
### Step 2: Export Script (cron job, no bot)
|
||||
A Python script that:
|
||||
- Runs nightly via cron on Contabo
|
||||
- Queries Synapse admin API for events in bridged rooms
|
||||
- Writes JSONL + markdown exports to /mnt/library/Archives/Signal/
|
||||
- No E2EE handling needed — admin API returns server-side decrypted content
|
||||
- No bot account, no device verification, no crypto key management
|
||||
|
||||
### Why This Is Better Than Hookshot
|
||||
|
||||
| Concern | Hookshot | Synapse Retention + Export |
|
||||
|---------|----------|---------------------------|
|
||||
| E2EE + MAS | BROKEN | Not applicable (admin API) |
|
||||
| Per-room config | Manual per room | Automatic (all rooms) |
|
||||
| New portal auto-join | Requires automation | Not needed (queries DB) |
|
||||
| Backfill historical | No backfill | Full history available |
|
||||
| Infrastructure | New container + Redis | 2-line config + cron script |
|
||||
| Maintenance | Hookshot upgrades, Redis, crypto store | Script only |
|
||||
| Failure mode | Missed events if down | DB has everything, export retries |
|
||||
| Edit/redaction capture | Real-time only | Retained in DB forever |
|
||||
|
||||
### Why This Is Better Than the Custom Bot (Original Phase 6)
|
||||
|
||||
The original Phase 6 plan proposed a full matrix-nio bot with E2EE, asyncpg,
|
||||
systemd service, healthchecks, and monitoring. That's ~500-1000 lines of Python
|
||||
for a problem that Synapse already solves with 2 config lines.
|
||||
|
||||
The custom bot approach is only justified if:
|
||||
- Real-time alerting on specific messages is needed (not requested)
|
||||
- Independent archive separate from Synapse DB is required (not requested)
|
||||
- Synapse admin API is insufficient for export needs (it's not)
|
||||
|
||||
## 3. Questions Requiring Live Test
|
||||
|
||||
None. All claims are verified from Synapse source code:
|
||||
- `redaction_retention_period: null` — confirmed in synapse/config/server.py
|
||||
- `msc2815_enabled` — confirmed in synapse/config/experimental.py line 372
|
||||
- Admin API event access — confirmed working (used throughout Phase 3-5)
|
||||
- Hookshot E2EE+MAS blocker — confirmed from GitHub issues with reproduction steps
|
||||
|
||||
## 4. Estimated Effort
|
||||
|
||||
### Synapse Config Change
|
||||
- Edit homeserver.yaml: 5 minutes
|
||||
- Restart Synapse: 1 minute
|
||||
- Verify via admin API: 5 minutes
|
||||
- **Total: ~15 minutes**
|
||||
|
||||
### Export Script
|
||||
- Python script to query admin API and write JSONL/markdown: 1-2 hours
|
||||
- Cron setup: 5 minutes
|
||||
- Test with existing rooms: 15 minutes
|
||||
- **Total: ~2 hours**
|
||||
|
||||
### Compare to Full Hookshot Deployment
|
||||
- Deploy hookshot container: 30 min
|
||||
- Debug E2EE+MAS incompatibility: hours of dead end
|
||||
- Fall back to alternative: start over
|
||||
- **Total: wasted time**
|
||||
|
||||
### Compare to Custom Bot (Original Phase 6)
|
||||
- Bot code + E2EE + DB schema + systemd + monitoring: 4-6 hours
|
||||
- Device verification walkthrough: 30 min
|
||||
- Export pipeline: 1-2 hours
|
||||
- **Total: 6-8 hours**
|
||||
|
||||
## 5. Blockers
|
||||
|
||||
None for the recommended approach. The only blocker was hookshot's E2EE+MAS
|
||||
incompatibility, which the recommended approach avoids entirely.
|
||||
|
||||
## 6. Decision Matrix
|
||||
|
||||
| Approach | Viable | Effort | Completeness | Ops Burden |
|
||||
|----------|--------|--------|--------------|------------|
|
||||
| Hookshot | NO (E2EE+MAS blocked) | N/A | N/A | N/A |
|
||||
| Custom matrix-nio bot | Yes | High (6-8h) | Full (real-time + export) | Medium |
|
||||
| Synapse retention + export | Yes | Low (~2h) | Full (DB + batch export) | Minimal |
|
||||
|
||||
**Recommendation: Synapse retention + export script.**
|
||||
|
||||
---
|
||||
|
||||
## Ref Files Produced
|
||||
|
||||
1. `.ref/synapse_retention_discovery.ref` — Current retention config, MSC2815 support, DB sizes, growth rate, rollback
|
||||
2. `.ref/hookshot_deployment_discovery.ref` — Contabo resources, port conflicts, compose snippet
|
||||
3. `.ref/hookshot_e2ee_discovery.ref` — **BLOCKER documented** — E2EE+MAS incompatibility
|
||||
4. `.ref/hookshot_payload_discovery.ref` — Webhook payload shape (for future reference)
|
||||
5. `.ref/hookshot_room_targeting_discovery.ref` — Per-room model, no wildcard, current portals
|
||||
6. `.ref/archive_receiver_discovery.ref` — Storage options, alternative approaches, CT recommendations
|
||||
7. `.ref/PHASE6_DECISION.md` — This file
|
||||
Loading…
Add table
Add a link
Reference in a new issue