a00a5fe312
Changes: - Fix nginx proxy_pass directives to use 127.0.0.1 instead of localhost - Fix bridge homeserverUrl to use explicit IPv4 address - Enable debug logging on conduwuit - Add spec-kit framework files to .gitignore - Document deployment in comprehensive worklog Resolves connection refused errors from localhost resolving to IPv6 [::1] while services bind only to IPv4 127.0.0.1. Bridge now fully operational with bidirectional Slack-Matrix message flow working.
150 lines
5.3 KiB
Markdown
150 lines
5.3 KiB
Markdown
# ops-jrz1 Development Guidelines
|
|
|
|
Auto-generated from all feature plans. Last updated: 2025-10-22
|
|
|
|
## Active Technologies
|
|
- Nix 2.x, NixOS 24.05+, Bash 5.x (for scripts) (001-extract-matrix-platform)
|
|
- mautrix-slack (Python 3.11), PostgreSQL 15.10, sops-nix (002-slack-bridge-integration)
|
|
- Matrix homeserver: conduwuit (clarun.xyz)
|
|
- Secrets management: sops-nix with age encryption
|
|
|
|
## Project Structure
|
|
```
|
|
.
|
|
├── hosts/ # NixOS host configurations
|
|
│ └── ops-jrz1.nix # VPS configuration (45.77.205.49)
|
|
├── modules/ # NixOS modules
|
|
│ ├── dev-services.nix # PostgreSQL, Forgejo, bridge coordination
|
|
│ ├── mautrix-slack.nix # Slack bridge module
|
|
│ └── matrix-continuwuity.nix # Matrix homeserver
|
|
├── secrets/ # sops-encrypted secrets
|
|
│ └── secrets.yaml # Encrypted credentials (age)
|
|
├── specs/ # Feature specifications
|
|
│ ├── 001-extract-matrix-platform/
|
|
│ └── 002-slack-bridge-integration/
|
|
│ ├── spec.md # Feature specification
|
|
│ ├── plan.md # Implementation plan
|
|
│ ├── research.md # Technical research findings
|
|
│ ├── data-model.md # Data model & state machines
|
|
│ ├── quickstart.md # Deployment runbook
|
|
│ └── contracts/ # Configuration schemas
|
|
├── docs/ # Documentation
|
|
│ ├── platform-vision.md # North star document
|
|
│ └── worklogs/ # Deployment logs
|
|
└── .specify/ # Spec-kit framework files
|
|
```
|
|
|
|
## Commands
|
|
|
|
### Deployment
|
|
```bash
|
|
# Deploy configuration to VPS
|
|
nixos-rebuild switch --flake .#ops-jrz1 \
|
|
--target-host root@45.77.205.49 \
|
|
--build-host localhost
|
|
|
|
# Deploy to staging
|
|
nixos-rebuild switch --flake .#ops-jrz1-staging \
|
|
--target-host root@45.77.205.49 \
|
|
--build-host localhost
|
|
```
|
|
|
|
### Bridge Management
|
|
```bash
|
|
# Check bridge status
|
|
ssh root@45.77.205.49 'systemctl status mautrix-slack'
|
|
|
|
# View bridge logs
|
|
ssh root@45.77.205.49 'journalctl -u mautrix-slack -f'
|
|
|
|
# Check Socket Mode connection
|
|
ssh root@45.77.205.49 'journalctl -u mautrix-slack -n 20 | grep -i socket'
|
|
|
|
# Query bridge database
|
|
ssh root@45.77.205.49 'sudo -u mautrix_slack psql mautrix_slack -c "SELECT * FROM portal;"'
|
|
```
|
|
|
|
### Secrets Management
|
|
```bash
|
|
# Edit encrypted secrets
|
|
sops secrets/secrets.yaml
|
|
|
|
# View decrypted secrets (never commit output)
|
|
sops -d secrets/secrets.yaml
|
|
|
|
# Add new secret
|
|
sops secrets/secrets.yaml
|
|
# (Edit in your $EDITOR, auto-encrypts on save)
|
|
```
|
|
|
|
### Matrix Server
|
|
```bash
|
|
# Check Matrix homeserver
|
|
ssh root@45.77.205.49 'systemctl status matrix-continuwuity'
|
|
|
|
# Test federation
|
|
ssh root@45.77.205.49 'curl -s http://localhost:8008/_matrix/client/versions | jq .'
|
|
```
|
|
|
|
### Database
|
|
```bash
|
|
# List databases
|
|
ssh root@45.77.205.49 'sudo -u postgres psql -l'
|
|
|
|
# Check bridge database
|
|
ssh root@45.77.205.49 'sudo -u postgres psql mautrix_slack -c "\dt"'
|
|
|
|
# Backup bridge database
|
|
ssh root@45.77.205.49 'sudo -u postgres pg_dump mautrix_slack' > backup.sql
|
|
```
|
|
|
|
## Code Style
|
|
- Nix 2.x, NixOS 24.05+, Bash 5.x: Follow standard conventions
|
|
- NixOS modules: Use nixpkgs module pattern (options, config, mkIf)
|
|
- Configuration: Declarative over imperative
|
|
- Secrets: Never hardcode, use sops-nix or interactive login
|
|
- Logging: Use appropriate levels (debug for troubleshooting, info for production)
|
|
|
|
## Development Patterns
|
|
|
|
### Slack Bridge (002-slack-bridge-integration)
|
|
- **Authentication**: Interactive login via Matrix chat (`login app` command)
|
|
- **Socket Mode**: WebSocket connection, no public endpoint needed
|
|
- **Portal Creation**: Automatic based on activity (no manual channel mapping)
|
|
- **Secrets**: Stored in bridge database after authentication (not in NixOS config)
|
|
- **Token Requirements**: Bot token (xoxb-) + app-level token (xapp-)
|
|
|
|
### Secrets Management
|
|
- **Encryption**: Age encryption via SSH host key (/etc/ssh/ssh_host_ed25519_key)
|
|
- **Storage**: secrets/secrets.yaml (encrypted, safe to commit)
|
|
- **Runtime**: Decrypted to /run/secrets/ (tmpfs, cleared on reboot)
|
|
- **Permissions**: 0440 for service-specific secrets, owned by service user
|
|
|
|
### Deployment Workflow
|
|
1. Make configuration changes locally
|
|
2. Commit to git
|
|
3. Deploy via nixos-rebuild
|
|
4. Verify service status and logs
|
|
5. Document in worklogs/
|
|
6. Test functionality
|
|
7. Monitor for stability
|
|
|
|
## Recent Changes
|
|
- 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)
|
|
- Phase 0: Research complete (Socket Mode, API scopes, sops-nix, channel patterns)
|
|
- Phase 1: Design complete (data-model.md, contracts/, quickstart.md)
|
|
- Next: Phase 2 (/speckit.tasks for implementation breakdown)
|
|
|
|
## 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)
|
|
|
|
## Testing Guidelines
|
|
- Test message latency: Should be <5 seconds (FR-001, FR-002)
|
|
- Test reactions, edits, file attachments
|
|
- Monitor health indicators: connection_status, last_successful_message, error_count
|
|
- Stability target: 99% uptime over 7-day period
|
|
|
|
<!-- MANUAL ADDITIONS START -->
|
|
<!-- MANUAL ADDITIONS END --> |