ops-jrz1/CLAUDE.md

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

# 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

# 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

# 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

# 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

# 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