# Feature Specification: Extract Matrix Platform Modules for ops-jrz1 Server **Feature Branch**: `001-extract-matrix-platform` **Created**: 2025-10-11 **Status**: Draft **Input**: User description: "Extract Matrix platform modules from ops-base to configure ops-jrz1 dev/test server in this repository" ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Deploy Matrix Platform to ops-jrz1 Server (Priority: P1) Deploy Matrix homeserver with bridges to the ops-jrz1 dev/test server using extracted and sanitized modules from this repository. **Why this priority**: This is the primary deliverable - a working Matrix platform on ops-jrz1 using production-tested patterns from ops-base. **Independent Test**: Can be fully tested by: (1) customizing configuration for ops-jrz1, (2) following deployment guide, (3) deploying to server, (4) verifying Matrix responds and user registration works. Delivers a working Matrix homeserver. **Acceptance Scenarios**: 1. **Given** a developer with a VPS and domain name, **When** they follow the quick start guide (5 minutes), **Then** they have a clear understanding of next steps and requirements 2. **Given** the developer has customized the example configuration, **When** they run the deployment command, **Then** the Matrix homeserver starts successfully and responds to API requests 3. **Given** the Matrix homeserver is running, **When** the developer follows the bridge setup guide, **Then** they can add Slack/WhatsApp/Google Messages bridges to their deployment --- ### User Story 2 - Extract and Sanitize Modules from ops-base (Priority: P1) Extract Matrix modules from ops-base, sanitize personal information (domains, IPs, secrets), and place them in this repository for ops-jrz1 server configuration. **Why this priority**: This is foundational - must extract and sanitize modules before we can configure and deploy the server. **Independent Test**: Can be tested by: (1) running sanitization scripts on ops-base modules, (2) verifying gitleaks finds no secrets, (3) verifying no personal domains/IPs remain, (4) building configurations successfully. Delivers sanitized modules ready for deployment. **Acceptance Scenarios**: 1. **Given** ops-base contains production modules with personal config, **When** sanitization process runs, **Then** all personal domains (clarun.xyz, talu.uno) are replaced with example.com variants 2. **Given** modules contain personal IP addresses, **When** sanitization completes, **Then** all IPs are replaced with RFC 1918 private ranges or TEST-NET-3 public examples 3. **Given** the sanitized repository, **When** gitleaks secret scanning runs, **Then** no secrets, tokens, or sensitive data are detected 4. **Given** sanitized files, **When** nix flake check runs, **Then** all configurations build successfully with no syntax errors --- ### User Story 3 - Enable Community Contributions (Priority: P3 - Deferred) **Status**: Deferred until public publication. Add governance files (CONTRIBUTING.md, SECURITY.md) and community features when ready to share publicly. **Why deferred**: Not needed for internal dev/test server. Will implement before public sharing. **Acceptance Scenarios**: 1. **Given** a developer wants to contribute, **When** they read CONTRIBUTING.md, **Then** they understand the process, testing requirements, and code standards 2. **Given** a developer submits a pull request, **When** they push their branch, **Then** pre-push hooks validate (nix flake check, gitleaks, build tests) before changes reach remote 3. **Given** a valid pull request passes CI, **When** maintainers review it, **Then** they can merge or request changes based on clear contribution guidelines --- ### User Story 4 - Sync Improvements from ops-base (Priority: P2) Create workflow for syncing future improvements from ops-base back to this repository as modules evolve. **Why this priority**: Useful for ongoing maintenance as production environment improves, but not critical for initial deployment. **Acceptance Scenarios**: 1. **Given** improvements exist in ops-base modules, **When** maintainer runs sync workflow script, **Then** the script identifies changes and generates sanitized diff for review 2. **Given** sanitized changes ready to apply, **When** maintainer applies them to template, **Then** automated tests (nix flake check, gitleaks) verify no secrets leaked and builds pass 3. **Given** synced changes are validated, **When** maintainer commits and pushes, **Then** git hooks validate successfully and template remains secure --- ### User Story 5 - Developer Learns Matrix Bridge Patterns from Documentation (Priority: P3) A developer wants to understand how to implement specific patterns (like Socket Mode authentication, gmessages-style config generation, or admin room setup) that are documented in the template's pattern guides. **Why this priority**: Educational value adds community benefit but is not essential for basic deployment. Nice-to-have for initial launch, can be improved iteratively. **Independent Test**: Can be tested by: (1) reading pattern documentation (e.g., Socket Mode setup), (2) following the steps in the guide, (3) verifying the pattern works as documented. Delivers knowledge transfer value. **Acceptance Scenarios**: 1. **Given** a developer implementing Slack bridge, **When** they read docs/bridges/slack-setup.md, **Then** they understand Socket Mode vs webhooks and have a checklist of OAuth scopes needed 2. **Given** a developer encounters gmessages config generation pattern, **When** they read docs/patterns/config-generation.md, **Then** they understand why runtime regeneration is used and can apply the pattern to other bridges 3. **Given** a developer using Conduwuit, **When** they read docs/patterns/admin-room-setup.md, **Then** they can successfully register appservices via admin room commands --- ### Edge Cases - What happens when a user tries to deploy without setting up sops-nix secrets management first? - How does the template handle users on different NixOS versions (stable vs unstable)? - What if a user deploys to ARM architecture instead of x86_64? - How does sanitization handle new personal references added after initial publication? - What happens if upstream bridge packages introduce breaking changes? - How does the sync workflow prevent accidental secret leakage during updates? ## Requirements *(mandatory)* ### Functional Requirements **Repository Structure & Sanitization:** - **FR-001**: Repository MUST contain sanitized NixOS modules for Matrix homeserver (Continuwuity), mautrix bridges (Slack, WhatsApp, Google Messages), and security hardening - **FR-002**: All personal domains MUST be replaced with generic examples or ops-jrz1-specific values (clarun.xyz → example.com, talu.uno → ops-jrz1 domain) - **FR-003**: All personal IP addresses MUST be replaced with RFC 1918 private ranges (10.0.0.x) or ops-jrz1-specific addresses - **FR-004**: All secrets MUST be removed from extracted code and managed via sops-nix - **FR-005**: All personal paths MUST be sanitized (/home/dan → appropriate paths) - **FR-006**: Extracted modules MUST NOT contain encrypted secrets or personal debugging logs from ops-base - **FR-007**: Repository MUST include ops-jrz1 server configuration that builds successfully **Documentation:** - **FR-008**: Repository MUST include README with architecture overview and deployment guide - **FR-009**: Repository SHOULD include deployment documentation for ops-jrz1 server - **FR-010**: Repository SHOULD include bridge setup notes extracted from worklogs (for reference) - **FR-011**: Repository SHOULD include pattern documentation extracted from worklogs (for reference) - **FR-012**: Repository MUST include secrets-management documentation for sops-nix - **FR-013**: Documentation MUST NOT contain personal infrastructure details from ops-base **Security & Validation:** - **FR-014**: Repository MUST pass gitleaks secret scanning with zero findings - **FR-015**: Configuration MUST pass `nix flake check` validation - **FR-016**: Repository SHOULD include git pre-commit and pre-push hooks for validation - **FR-017**: Deferred - CI workflow not needed for internal dev server - **FR-018**: Deferred - SECURITY.md for future public sharing **Community & Governance:** - **FR-019**: Deferred - CONTRIBUTING.md for future public sharing - **FR-020**: Deferred - Issue templates for future public sharing - **FR-021**: Repository SHOULD include LICENSE file for future sharing - **FR-022**: Deferred - Community features for future public sharing **Sync Workflow:** - **FR-023**: Repository SHOULD document workflow for future syncs from ops-base - **FR-024**: Repository SHOULD include helper scripts for identifying and sanitizing changes - **FR-025**: Sync workflow SHOULD include validation steps (build check, gitleaks scan) - **FR-026**: Deferred - Quarterly reminders for ongoing maintenance **Testing & Deployment:** - **FR-027**: Configuration MUST be tested by deploying to ops-jrz1 server - **FR-028**: Configuration targets x86_64-linux architecture - **FR-029**: All modules MUST build against pinned nixpkgs version for reproducibility ### Key Entities *(include if feature involves data)* - **Module**: A reusable NixOS module file (e.g., matrix-continuwuity.nix, mautrix-slack.nix) containing service configuration and systemd units - **Configuration**: An example deployment configuration file (e.g., example-vps.nix) that imports modules and sets options - **Secret**: Sensitive data (tokens, passwords, keys) managed via sops-nix encryption, stored in secrets/secrets.yaml - **Pattern Document**: Extracted architectural knowledge from worklogs explaining proven implementation approaches - **Bridge Setup Guide**: Step-by-step documentation for configuring specific Matrix bridges with authentication and registration - **Sanitization Rule**: A find/replace or validation rule that ensures personal information is removed (domain, IP, path, secret patterns) - **Sync Checkpoint**: A record of what changes have been synced from ops-base to template at a specific point in time ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: Configuration can be deployed to ops-jrz1 server and Matrix homeserver responds within 30 minutes - **SC-002**: Configuration builds successfully with `nix flake check` (zero errors) - **SC-003**: gitleaks secret scanning returns zero findings across entire repository - **SC-004**: All target modules extracted and building: matrix-continuwuity, mautrix-slack, mautrix-whatsapp, mautrix-gmessages, security/fail2ban, security/ssh-hardening (6+ modules total) - **SC-005**: Core documentation complete: README, deployment guide, secrets-management docs - **SC-006**: Deferred - Git hooks for future enforcement - **SC-007**: Deferred - Community metrics for future public sharing - **SC-008**: Deferred - Community engagement for future public sharing - **SC-009**: Zero security incidents (no secret leakage from ops-base extraction) - **SC-010**: Deferred - Sync workflow for ongoing maintenance ## Assumptions *(mandatory)* - ops-jrz1 is a dev/test server (not production - no 99.9999% uptime requirement) - Maintainer has basic familiarity with NixOS and Nix flakes - ops-jrz1 server exists or will be provisioned for deployment - Domain name and DNS available for ops-jrz1 server - SSH access to ops-jrz1 server available - ops-base repository contains working Matrix modules to extract - ops-base repository may contain worklogs with useful pattern documentation - Maintainer has access to ops-base (private) repository - gitleaks tool available for secret scanning - NixOS provides necessary packages (matrix-continuwuity, mautrix bridges) ## Out of Scope *(include if needed to clarify boundaries)* - Public template repository (deferred for future) - Community contribution features (deferred for future) - Rewriting git history in ops-base - Automated sync from ops-base (manual extraction for now) - Support for platforms other than NixOS - Graphical configuration UI - Hosting services or managed deployments - Non-Matrix services beyond extracted modules - Matrix clients or frontend components - Custom bridge development - Multi-host deployments (single-host for ops-jrz1) - Windows or macOS deployment targets - Production monitoring/observability (can be added later) ## Dependencies *(include if feature relies on external factors)* - **NixOS/nixpkgs**: Requires packages for matrix-continuwuity, mautrix-slack, mautrix-whatsapp, mautrix-gmessages, forgejo - **sops-nix**: Required for secrets management, must be compatible with current NixOS version - **Git hosting platform**: Required for hosting repository (Forgejo for development, GitHub/tangl.sh for public publication) - **gitleaks**: Required for automated secret scanning in CI and locally - **age encryption tool**: Required for sops-nix secret encryption - **ops-base repository**: Source of modules and documentation to be extracted - **Nix flake system**: Template uses flakes for dependency management and configuration - **Let's Encrypt / ACME**: Assumed for TLS certificate generation (users must configure) ## Open Questions *(include if there are unresolved decisions)* None - all critical decisions were resolved in the RFC consensus validation process.