Document current architecture, manual fixes, and QA checklist
Added comprehensive documentation: - Manual workaround for sender_localpart registration bug - QA testing checklist for untested features - Future monitoring/alerting requirements - Current architecture diagram and data flow - Security model and operational notes
This commit is contained in:
Dan
parent
0b1751766b
commit
2dfe4ea829
266
CLAUDE.md
266
CLAUDE.md
|
|
@ -131,14 +131,16 @@ ssh root@45.77.205.49 'sudo -u postgres pg_dump mautrix_slack' > backup.sql
|
||||||
|
|
||||||
## Recent Changes
|
## Recent Changes
|
||||||
- 001-extract-matrix-platform: Added Nix 2.x, NixOS 24.05+, Bash 5.x (for scripts)
|
- 001-extract-matrix-platform: Added Nix 2.x, NixOS 24.05+, Bash 5.x (for scripts)
|
||||||
- 002-slack-bridge-integration: Added mautrix-slack bridge with Socket Mode (2025-10-22)
|
- 002-slack-bridge-integration: Deployed mautrix-slack bridge with Socket Mode (2025-10-26)
|
||||||
- Phase 0: Research complete (Socket Mode, API scopes, sops-nix, channel patterns)
|
- Phase 0-1: Research and design complete
|
||||||
- Phase 1: Design complete (data-model.md, contracts/, quickstart.md)
|
- Phase 2: Infrastructure deployed and operational
|
||||||
- Next: Phase 2 (/speckit.tasks for implementation breakdown)
|
- Status: Bidirectional message flow working (Slack ↔ Matrix)
|
||||||
|
- ~50 Slack channels synced to Matrix rooms
|
||||||
|
|
||||||
## Known Issues
|
## Known Issues
|
||||||
- mautrix-slack exits with code 11 without credentials (expected, requires `login app`)
|
|
||||||
- olm-3.2.16 marked insecure (permitted via nixpkgs.config.permittedInsecurePackages)
|
- olm-3.2.16 marked insecure (permitted via nixpkgs.config.permittedInsecurePackages)
|
||||||
|
- conduwuit log level set to "debug" (intended for troubleshooting, consider reverting to "info")
|
||||||
|
- Fresh database required after conduwuit version upgrades (wipe /var/lib/matrix-continuwuity/db/)
|
||||||
|
|
||||||
## Testing Guidelines
|
## Testing Guidelines
|
||||||
- Test message latency: Should be <5 seconds (FR-001, FR-002)
|
- Test message latency: Should be <5 seconds (FR-001, FR-002)
|
||||||
|
|
@ -147,4 +149,258 @@ ssh root@45.77.205.49 'sudo -u postgres pg_dump mautrix_slack' > backup.sql
|
||||||
- Stability target: 99% uptime over 7-day period
|
- Stability target: 99% uptime over 7-day period
|
||||||
|
|
||||||
<!-- MANUAL ADDITIONS START -->
|
<!-- MANUAL ADDITIONS START -->
|
||||||
|
|
||||||
|
## Manual Configuration Workarounds
|
||||||
|
|
||||||
|
### mautrix-slack Registration File Fix (KNOWN ISSUE)
|
||||||
|
|
||||||
|
**Problem:** The bridge's registration generator creates a random `sender_localpart` instead of using the configured `bot.username` value.
|
||||||
|
|
||||||
|
**Current Manual Fix (Required on Fresh Deploy):**
|
||||||
|
```bash
|
||||||
|
# After bridge service starts and generates registration
|
||||||
|
ssh root@45.77.205.49 'systemctl stop mautrix-slack'
|
||||||
|
|
||||||
|
# Edit registration file to fix sender_localpart
|
||||||
|
ssh root@45.77.205.49 "sed -i 's/^sender_localpart: .*/sender_localpart: slackbot/' /var/lib/matrix-appservices/mautrix_slack_registration.yaml"
|
||||||
|
|
||||||
|
# Re-register appservice in Matrix admin room
|
||||||
|
# In Element, send to admin room:
|
||||||
|
# !admin appservices unregister slack
|
||||||
|
# !admin appservices register
|
||||||
|
# <paste corrected YAML>
|
||||||
|
|
||||||
|
# Restart homeserver to load new registration
|
||||||
|
ssh root@45.77.205.49 'systemctl restart matrix-continuwuity'
|
||||||
|
|
||||||
|
# Start bridge
|
||||||
|
ssh root@45.77.205.49 'systemctl start mautrix-slack'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Root Cause:** mautrix-slack's `-g` flag generates registration independently of `config.yaml` settings.
|
||||||
|
|
||||||
|
**Potential Permanent Fix:** Patch `modules/mautrix-slack.nix` to post-process registration file after generation:
|
||||||
|
```nix
|
||||||
|
# In ExecStartPre, after registration generation:
|
||||||
|
${pkgs.gnused}/bin/sed -i 's/^sender_localpart: .*/sender_localpart: ${cfg.appservice.senderLocalpart}/' "$REG_PATH"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Impact:** Without this fix, registration sender_localpart won't match bridge config, causing authentication failures.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## QA Testing Checklist
|
||||||
|
|
||||||
|
### Core Features (✅ Tested & Working)
|
||||||
|
- [x] Bidirectional text messaging (Slack ↔ Matrix)
|
||||||
|
- [x] Channel discovery and room creation (~50 channels synced)
|
||||||
|
- [x] Socket Mode WebSocket connection
|
||||||
|
- [x] Bot authentication with Matrix homeserver
|
||||||
|
- [x] Bridge startup and recovery after restart
|
||||||
|
|
||||||
|
### Features Requiring QA Testing (⚠️ Untested)
|
||||||
|
- [ ] **File Attachments**
|
||||||
|
- Upload file in Slack → verify appears in Matrix
|
||||||
|
- Upload file in Matrix → verify appears in Slack
|
||||||
|
- Test various file types (images, PDFs, archives)
|
||||||
|
- Test large files (>10MB)
|
||||||
|
|
||||||
|
- [ ] **Emoji Reactions**
|
||||||
|
- Add reaction in Slack → verify appears in Matrix
|
||||||
|
- Add reaction in Matrix → verify appears in Slack
|
||||||
|
- Remove reaction → verify syncs
|
||||||
|
|
||||||
|
- [ ] **Message Edits**
|
||||||
|
- Edit message in Slack → verify updates in Matrix
|
||||||
|
- Edit message in Matrix → verify updates in Slack
|
||||||
|
|
||||||
|
- [ ] **Message Deletion**
|
||||||
|
- Delete message in Slack → verify removes from Matrix
|
||||||
|
- Delete message in Matrix → verify removes from Slack
|
||||||
|
|
||||||
|
- [ ] **Thread Replies**
|
||||||
|
- Reply in Slack thread → verify threading in Matrix
|
||||||
|
- Reply in Matrix thread → verify threading in Slack
|
||||||
|
|
||||||
|
- [ ] **User Profile Sync**
|
||||||
|
- Change Slack display name → verify updates Matrix puppet
|
||||||
|
- Change Slack avatar → verify updates Matrix puppet
|
||||||
|
|
||||||
|
- [ ] **Error Handling**
|
||||||
|
- Network interruption recovery
|
||||||
|
- Matrix homeserver restart handling
|
||||||
|
- Slack WebSocket reconnection
|
||||||
|
- Invalid token handling
|
||||||
|
|
||||||
|
- [ ] **Performance**
|
||||||
|
- High-volume channel (>100 messages/hour)
|
||||||
|
- Large file transfer times
|
||||||
|
- Message latency under load
|
||||||
|
|
||||||
|
### Test Commands
|
||||||
|
```bash
|
||||||
|
# Monitor bridge during testing
|
||||||
|
ssh root@45.77.205.49 'journalctl -u mautrix-slack -f'
|
||||||
|
|
||||||
|
# Check for errors
|
||||||
|
ssh root@45.77.205.49 'journalctl -u mautrix-slack --since "1 hour ago" | grep -E "ERR|WRN|FTL"'
|
||||||
|
|
||||||
|
# Verify message flow
|
||||||
|
# Test in #vlads-pad or similar channel
|
||||||
|
# Send from Slack, verify in Matrix room
|
||||||
|
# Send from Matrix room, verify in Slack
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Future Infrastructure Needs
|
||||||
|
|
||||||
|
### Monitoring & Alerting (Not Implemented)
|
||||||
|
|
||||||
|
**Health Checks Needed:**
|
||||||
|
- Bridge WebSocket connection status
|
||||||
|
- Matrix homeserver availability
|
||||||
|
- Message processing latency
|
||||||
|
- Database connection health
|
||||||
|
- Error rate thresholds
|
||||||
|
|
||||||
|
**Potential Solutions:**
|
||||||
|
```bash
|
||||||
|
# Option 1: Simple systemd monitoring
|
||||||
|
systemctl status mautrix-slack | grep -q "active (running)" || alert
|
||||||
|
|
||||||
|
# Option 2: Prometheus + Alertmanager
|
||||||
|
# - Export bridge metrics (if available)
|
||||||
|
# - Alert on service down, high error rate, message lag
|
||||||
|
|
||||||
|
# Option 3: Uptime monitoring
|
||||||
|
# - External ping to Matrix homeserver
|
||||||
|
# - Check /_matrix/client/versions endpoint
|
||||||
|
# - Alert on HTTP errors or timeout
|
||||||
|
```
|
||||||
|
|
||||||
|
**Metrics to Track:**
|
||||||
|
- Bridge uptime percentage
|
||||||
|
- Messages processed (Slack → Matrix, Matrix → Slack)
|
||||||
|
- WebSocket reconnection events
|
||||||
|
- Database query performance
|
||||||
|
- Error counts by type
|
||||||
|
|
||||||
|
**Alert Conditions:**
|
||||||
|
- Bridge down for >5 minutes
|
||||||
|
- No messages processed in >15 minutes (if active channels exist)
|
||||||
|
- Error rate >5% of total messages
|
||||||
|
- Database connection failures
|
||||||
|
- Disk space <10% free
|
||||||
|
|
||||||
|
### Backup Strategy (Not Implemented)
|
||||||
|
|
||||||
|
**Critical Data:**
|
||||||
|
- Matrix RocksDB: `/var/lib/matrix-continuwuity/db/` (66M)
|
||||||
|
- Bridge PostgreSQL: `mautrix_slack` database (172K)
|
||||||
|
- Registration files: `/var/lib/matrix-appservices/*.yaml`
|
||||||
|
- Secrets: sops-encrypted `secrets/secrets.yaml` (in git)
|
||||||
|
|
||||||
|
**Backup Approach:**
|
||||||
|
```bash
|
||||||
|
# Daily database backups
|
||||||
|
ssh root@45.77.205.49 'tar czf /root/backups/matrix-$(date +%Y%m%d).tar.gz /var/lib/matrix-continuwuity/db/'
|
||||||
|
ssh root@45.77.205.49 'sudo -u postgres pg_dump mautrix_slack > /root/backups/bridge-$(date +%Y%m%d).sql'
|
||||||
|
|
||||||
|
# Retention: 7 daily, 4 weekly, 12 monthly
|
||||||
|
# Store off-VPS (rsync to backup server or cloud storage)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Recovery Procedure:**
|
||||||
|
1. Deploy NixOS configuration
|
||||||
|
2. Restore database backups
|
||||||
|
3. Restore registration files
|
||||||
|
4. Re-authenticate with Slack (new tokens via `login app`)
|
||||||
|
5. Verify message flow
|
||||||
|
|
||||||
|
**Note:** Matrix database can be wiped and rebuilt from Slack if needed (current architecture treats Matrix as ephemeral view layer).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Current Architecture State (2025-10-26)
|
||||||
|
|
||||||
|
### Deployed Services
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────┐
|
||||||
|
│ clarun.xyz (45.77.205.49) │
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────────────────────────────────┐ │
|
||||||
|
│ │ nginx :443 (HTTPS) │ │
|
||||||
|
│ │ - Matrix Client-Server API │ │
|
||||||
|
│ │ - Forgejo (git.clarun.xyz) │ │
|
||||||
|
│ └────────────┬────────────────────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ ├─→ conduwuit :8008 (127.0.0.1) │
|
||||||
|
│ │ - Matrix homeserver │
|
||||||
|
│ │ - RocksDB schema v18 │
|
||||||
|
│ │ - 66M database │
|
||||||
|
│ │ │
|
||||||
|
│ └─→ Forgejo :3000 (127.0.0.1) │
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────────────────────────────────┐ │
|
||||||
|
│ │ mautrix-slack :29319 (127.0.0.1) │ │
|
||||||
|
│ │ - Socket Mode WebSocket to Slack │ │
|
||||||
|
│ │ - PostgreSQL backend (172K) │ │
|
||||||
|
│ │ - ~50 portal rooms │ │
|
||||||
|
│ └────────────┬────────────────────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ └─→ PostgreSQL :5432 (unix socket) │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
└─→ Slack API (Socket Mode WebSocket)
|
||||||
|
- Workspace: chochacho
|
||||||
|
- Bot token: xoxb-...
|
||||||
|
- App token: xapp-...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Critical Networking Details
|
||||||
|
- **All internal services use IPv4 (127.0.0.1)** - NOT "localhost"
|
||||||
|
- Reason: `localhost` resolves to IPv6 `[::1]` but services bind IPv4-only
|
||||||
|
- Fixed in: nginx proxy_pass, bridge homeserverUrl configuration
|
||||||
|
|
||||||
|
### Service Dependencies
|
||||||
|
```
|
||||||
|
postgresql.service
|
||||||
|
└─→ mautrix-slack.service
|
||||||
|
└─→ matrix-continuwuity.service
|
||||||
|
└─→ nginx.service
|
||||||
|
```
|
||||||
|
|
||||||
|
### Data Flow
|
||||||
|
1. **Slack → Matrix:**
|
||||||
|
- Slack pushes event via Socket Mode WebSocket
|
||||||
|
- Bridge receives, transforms to Matrix event
|
||||||
|
- Bridge POSTs to conduwuit appservice endpoint
|
||||||
|
- conduwuit distributes to Matrix rooms
|
||||||
|
- Element clients receive via /sync
|
||||||
|
|
||||||
|
2. **Matrix → Slack:**
|
||||||
|
- Element client sends message via conduwuit
|
||||||
|
- conduwuit forwards to bridge appservice endpoint
|
||||||
|
- Bridge transforms to Slack API call
|
||||||
|
- Bridge POSTs to Slack API (bot token)
|
||||||
|
- Appears in Slack channel
|
||||||
|
|
||||||
|
### Security Model
|
||||||
|
- **Secrets:** Managed via sops-nix, deployed to `/run/secrets/`
|
||||||
|
- **Bridge tokens:**
|
||||||
|
- `as_token`: Bridge authenticates to Matrix
|
||||||
|
- `hs_token`: Matrix authenticates to bridge
|
||||||
|
- **Slack tokens:**
|
||||||
|
- `xoxb-`: Bot API calls
|
||||||
|
- `xapp-`: Socket Mode connection
|
||||||
|
- **No public bridge endpoint:** Socket Mode eliminates webhook requirement
|
||||||
|
|
||||||
|
### Operational Notes
|
||||||
|
- Matrix database disposable (can rebuild from Slack)
|
||||||
|
- Bridge config fully declarative except sender_localpart fix
|
||||||
|
- Fresh database recommended after conduwuit version upgrades
|
||||||
|
- Debug logging currently enabled on conduwuit
|
||||||
|
|
||||||
<!-- MANUAL ADDITIONS END -->
|
<!-- MANUAL ADDITIONS END -->
|
||||||
Loading…
Reference in a new issue