ops-jrz1/specs/001-extract-matrix-platform/quickstart.md

# Quick Start: Extract Matrix Platform Modules

**Target Audience**: Maintainer extracting modules from ops-base
**Time Required**: 2-4 weeks (following RFC timeline)
**Prerequisites**: Access to ops-base repository, NixOS knowledge, GitHub account

---

## Overview

This guide walks through extracting Matrix platform modules from the private ops-base repository and publishing them as the public nixos-matrix-platform-template. Follow the RFC's 4-week implementation plan.

```
Week 1: Repository setup, sanitization, CI/CD
Week 2: Documentation extraction from worklogs
Week 3: Integration testing and security validation
Week 4: Sync workflow and publication
```

---

## Prerequisites Checklist

Before starting:

- [ ] Access to ops-base repository (`~/proj/ops-base`)
- [ ] Read the RFC (`~/proj/ops-base/docs/rfcs/repository-publication-strategy-rfc.md`)
- [ ] Nix 2.x installed and functional
- [ ] gitleaks 8.18.0+ installed (`nix-shell -p gitleaks`)
- [ ] GitHub account with ability to create public repositories
- [ ] ops-jrz1 repository cloned (this planning repo)
- [ ] Fresh VPS or VM for Phase 3 testing (Vultr/DigitalOcean recommended)

---

## Phase 1: Repository Setup & Sanitization (Week 1)

### Day 1-2: Create Repository and CI/CD

**1. Create GitHub repository:**
```bash
# On GitHub web interface:
# - Name: nixos-matrix-platform-template
# - Description: "Production-ready NixOS modules for Matrix homeserver with bridges"
# - Public repository
# - Initialize with README: No (we'll add it)
# - License: MIT

# Clone locally:
cd ~/proj
git clone git@github.com:YOUR_USERNAME/nixos-matrix-platform-template.git
cd nixos-matrix-platform-template
```

**2. Create initial repository structure:**
```bash
# Create directory structure
mkdir -p modules/{security,matrix-secrets}
mkdir -p configurations
mkdir -p docs/{bridges,patterns}
mkdir -p examples
mkdir -p scripts
mkdir -p .github/{workflows,ISSUE_TEMPLATE}

# Create .gitignore
cat > .gitignore <<'EOF'
# Nix build results
result
result-*

# Secrets (only encrypted versions committed)
secrets/secrets.yaml
!secrets/secrets.yaml.example

# IDE
.vscode/
.idea/

# Temporary files
*.swp
*.swo
*~
.DS_Store
EOF
```

**3. Set up GitHub Actions CI:**
```bash
# Copy CI workflow from contracts
cp ~/proj/ops-jrz1/specs/001-extract-matrix-platform/contracts/ci-validation.yaml \
   .github/workflows/ci.yml

# Edit ci.yml to convert from contract format to GitHub Actions YAML
# (See contracts/ci-validation.yaml for structure)
```

**4. Set up pre-commit hooks (optional):**
```bash
cat > .pre-commit-config.yaml <<'EOF'
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0
    hooks:
      - id: gitleaks

  - repo: local
    hooks:
      - id: nix-flake-check
        name: nix flake check
        entry: nix flake check
        language: system
        pass_filenames: false
EOF
```

**5. Create initial README:**
```bash
cat > README.md <<'EOF'
# NixOS Matrix Platform Template

Production-ready NixOS modules for deploying Matrix homeserver with bridges.

**Status**: 🚧 Under construction - not yet ready for use

## Features (planned)

- ✅ Matrix Homeserver (Continuwuity)
- ✅ Bridge Support (Slack, WhatsApp, Google Messages)
- ✅ Development Platform (Forgejo integration)
- ✅ Secrets Management (sops-nix)
- ✅ Security Hardening (fail2ban, SSH)
- ✅ Production Tested

## Coming Soon

Documentation and modules being extracted from production deployment.
Expected completion: [DATE]

## License

MIT License - see [LICENSE](LICENSE)
EOF
```

**6. Add LICENSE file:**
```bash
# Copy MIT license template
cat > LICENSE <<'EOF'
MIT License

Copyright (c) 2025 [Your Name]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

[... rest of MIT license ...]
EOF
```

**7. Initial commit:**
```bash
git add .
git commit -m "Initial repository structure

- Add directory layout for modules, docs, examples
- Add GitHub Actions CI with nix flake check + gitleaks
- Add MIT license
- Add initial README (work in progress)"
git push origin main
```

### Day 3-5: Copy and Sanitize Modules

**1. Create staging area:**
```bash
cd ~/proj/ops-jrz1
mkdir -p staging/{modules,configurations}
```

**2. Copy modules from ops-base:**
```bash
# Copy core modules
cp ~/proj/ops-base/modules/matrix-continuwuity.nix staging/modules/
cp ~/proj/ops-base/modules/mautrix-slack.nix staging/modules/
cp ~/proj/ops-base/modules/mautrix-whatsapp.nix staging/modules/
cp ~/proj/ops-base/modules/mautrix-gmessages.nix staging/modules/
cp ~/proj/ops-base/modules/dev-services.nix staging/modules/
cp -r ~/proj/ops-base/modules/security staging/modules/
cp -r ~/proj/ops-base/modules/matrix-secrets staging/modules/

# Copy example configurations (will be sanitized to examples)
cp ~/proj/ops-base/configurations/vultr-dev.nix staging/configurations/example-vps.nix
cp ~/proj/ops-base/configurations/dev-vps.nix staging/configurations/example-dev.nix
```

**3. Create sanitization script:**
```bash
cat > scripts/sanitize-files.sh <<'SCRIPT'
#!/usr/bin/env bash
# Automated sanitization based on contracts/sanitization-rules.yaml

set -euo pipefail

SRC_DIR="${1:?Usage: $0 <source-dir> <output-dir>}"
OUT_DIR="${2:?Usage: $0 <source-dir> <output-dir>}"

echo "=== Sanitizing files from $SRC_DIR to $OUT_DIR ==="

# Copy files to output
mkdir -p "$OUT_DIR"
cp -r "$SRC_DIR"/* "$OUT_DIR/"

# Apply critical sanitization rules (from contracts/sanitization-rules.yaml)
echo "Applying domain replacements..."
find "$OUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i \
  -e 's/clarun\.xyz/example.com/g' \
  -e 's/talu\.uno/matrix.example.org/g' \
  {} +

echo "Applying IP address replacements..."
find "$OUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i \
  -e 's/192\.168\.1\./10.0.0./g' \
  -e 's/45\.77\.205\.49/203.0.113.10/g' \
  {} +

echo "Applying path replacements..."
find "$OUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i \
  -e 's#/home/dan#/home/user#g' \
  -e 's#git+file:///home/dan/proj/continuwuity#github:girlbossceo/conduwuit#g' \
  {} +

echo "Applying hostname/username replacements..."
find "$OUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i \
  -e 's/\bjrz1\b/matrix/g' \
  -e 's/@admin:clarun/@admin:example/g' \
  -e 's/my-workspace/your-workspace/g' \
  -e 's/dlei@duck\.com/admin@example.com/g' \
  {} +

echo "Sanitization complete."
echo ""
echo "Next steps:"
echo "1. Run validation: ./scripts/validate-sanitization.sh $OUT_DIR"
echo "2. Manual review: Check comments, docs for personal context"
echo "3. Copy to template repo if validation passes"
SCRIPT

chmod +x scripts/sanitize-files.sh
```

**4. Create validation script:**
```bash
cat > scripts/validate-sanitization.sh <<'SCRIPT'
#!/usr/bin/env bash
# Validate sanitization based on contracts/sanitization-rules.yaml

set -euo pipefail

TARGET_DIR="${1:?Usage: $0 <directory>}"

echo "=== Validating sanitization in $TARGET_DIR ==="

FAILED=0

# Check for forbidden patterns
echo "Checking for personal domains..."
if rg 'clarun\.xyz|talu\.uno' "$TARGET_DIR" --type nix --type md; then
  echo "❌ FAILED: Personal domains found"
  FAILED=1
else
  echo "✅ PASSED: No personal domains"
fi

echo "Checking for personal IPs..."
if rg '192\.168\.1\.|45\.77\.205\.49' "$TARGET_DIR" --type nix --type md; then
  echo "❌ FAILED: Personal IPs found"
  FAILED=1
else
  echo "✅ PASSED: No personal IPs"
fi

echo "Checking for personal paths..."
if rg '/home/dan' "$TARGET_DIR"; then
  echo "❌ FAILED: Personal paths found"
  FAILED=1
else
  echo "✅ PASSED: No personal paths"
fi

echo "Running gitleaks..."
if gitleaks detect --no-git --source "$TARGET_DIR"; then
  echo "✅ PASSED: No secrets detected"
else
  echo "❌ FAILED: Secrets detected by gitleaks"
  FAILED=1
fi

if [ $FAILED -eq 0 ]; then
  echo ""
  echo "✅ All validations passed!"
  echo "Ready for manual review and copy to template repository."
  exit 0
else
  echo ""
  echo "❌ Some validations failed. Review output above."
  exit 1
fi
SCRIPT

chmod +x scripts/validate-sanitization.sh
```

**5. Run sanitization:**
```bash
# Sanitize modules
./scripts/sanitize-files.sh staging/modules ~/proj/nixos-matrix-platform-template/modules

# Sanitize configurations
./scripts/sanitize-files.sh staging/configurations ~/proj/nixos-matrix-platform-template/configurations
```

**6. Validate sanitization:**
```bash
./scripts/validate-sanitization.sh ~/proj/nixos-matrix-platform-template/modules
./scripts/validate-sanitization.sh ~/proj/nixos-matrix-platform-template/configurations
```

**7. Manual review (checklist from contracts/sanitization-rules.yaml):**
```bash
# Open each file and review:
# - [ ] Comments contain no personal references
# - [ ] Domain/IP placeholders are clear
# - [ ] REPLACE_ME comments added where needed
# - [ ] No hardcoded tokens or secrets
# - [ ] Module options have descriptions
```

### Day 6-7: Create Examples and Governance Docs

**1. Create example secrets template:**
```bash
cat > ~/proj/nixos-matrix-platform-template/examples/secrets.yaml.example <<'EOF'
# Example secrets file for sops-nix
# See docs/secrets-management.md for setup instructions

matrix:
  registration_token: "GENERATE_WITH_openssl_rand_hex_32"

acme:
  email: "your-email@example.com"

slack:
  oauth_token: "REPLACE_WITH_SLACK_BOT_TOKEN"
  app_token: "REPLACE_WITH_SLACK_APP_TOKEN"

# Add more secrets as needed
EOF
```

**2. Create sops config template:**
```bash
cat > ~/proj/nixos-matrix-platform-template/examples/.sops.yaml.example <<'EOF'
keys:
  # Replace with your host's age key
  # Get it with: ssh-to-age < /etc/ssh/ssh_host_ed25519_key.pub
  - &your_host age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

creation_rules:
  - path_regex: secrets/secrets\.yaml$
    key_groups:
      - age:
          - *your_host
EOF
```

**3. Create CONTRIBUTING.md:**
```bash
cat > ~/proj/nixos-matrix-platform-template/CONTRIBUTING.md <<'EOF'
# Contributing to nixos-matrix-platform-template

Thank you for contributing!

## How to Contribute

### Bug Reports
- Check existing issues first
- Provide minimal reproduction steps
- Include NixOS version and platform
- Sanitize logs (remove domains/IPs)

### Pull Requests
- Fork repository
- Create feature branch
- Test with `nix flake check`
- Update documentation
- Ensure CI passes (nix build + gitleaks)
- Submit PR with clear description

## Development Workflow

1. Make changes
2. Test locally: `nix flake check`
3. Scan for secrets: `gitleaks detect --no-git`
4. Build examples: `nix build .#nixosConfigurations.example-vps`
5. Submit PR

## Code Standards

- Follow existing Nix style
- Add comments for complex logic
- Use generic examples (example.com, 10.0.0.x)
- No secrets in commits

## Maintenance Policy

- Security fixes: Priority
- Bug fixes: Within 2 weeks
- Features: Best effort

## Questions?

- GitHub Discussions for design/questions
- Issues for bugs only
EOF
```

**4. Create SECURITY.md:**
```bash
cat > ~/proj/nixos-matrix-platform-template/SECURITY.md <<'EOF'
# Security Policy

## Reporting Vulnerabilities

**DO NOT** open public issues for security vulnerabilities.

Email: your-email@example.com

Include:
- Description
- Steps to reproduce
- Potential impact
- Suggested fix (if available)

Response time: 48 hours
Fix timeline: 7 days critical, 30 days moderate

## Supported Versions

| Version | Supported |
|---------|-----------|
| 1.x     | ✅ Yes    |
| < 1.0   | ❌ No     |
EOF
```

**5. Commit governance files:**
```bash
cd ~/proj/nixos-matrix-platform-template
git add examples/ CONTRIBUTING.md SECURITY.md
git commit -m "Add example templates and governance docs

- Add secrets.yaml.example and .sops.yaml.example
- Add CONTRIBUTING.md with contribution guidelines
- Add SECURITY.md with vulnerability disclosure process"
git push origin main
```

---

## Phase 2: Documentation Extraction (Week 2)

### Day 8-10: Extract Architecture Docs

**1. Extract gmessages config pattern:**
```bash
# Use LLM to extract from worklog:
# Input: ~/proj/ops-base/docs/worklogs/mautrix-slack-bridge-implementation-gmessages-pattern.org
# Output: ~/proj/nixos-matrix-platform-template/docs/patterns/config-generation.md
# Focus: Runtime config regeneration pattern, deep_update merge logic
```

**2. Extract admin room setup:**
```bash
# Input: ~/proj/ops-base/docs/worklogs/conduwuit-admin-room-discovery-password-reset.org
# Output: ~/proj/nixos-matrix-platform-template/docs/patterns/admin-room-setup.md
# Focus: Admin room discovery, appservice registration via admin room
```

**3. Extract secrets management:**
```bash
# Input: ~/proj/ops-base/docs/sops-nix-secrets-management-rfc.md
# Output: ~/proj/nixos-matrix-platform-template/docs/secrets-management.md
# Focus: sops-nix setup, age key generation, secret rotation
```

### Day 11-13: Write Bridge Guides

**4. Extract Slack bridge guide:**
```bash
# Input: ~/proj/ops-base/docs/worklogs/mautrix-slack-socket-mode-oauth-scopes-blocker.org
# Output: ~/proj/nixos-matrix-platform-template/docs/bridges/slack-setup.md
# Focus: Socket Mode vs webhooks, OAuth scopes, app configuration
```

**5. Create WhatsApp and gmessages guides:**
```bash
# Based on module configurations and common setup patterns
# Output: docs/bridges/whatsapp-setup.md
# Output: docs/bridges/gmessages-setup.md
```

### Day 14: Create Getting Started Guide

**6. Write comprehensive getting started:**
```bash
# Output: ~/proj/nixos-matrix-platform-template/docs/getting-started.md
# Structure:
# - 5-minute quick start
# - Prerequisites checklist
# - Step-by-step deployment
# - Common issues and solutions
```

---

## Phase 3: Testing and Validation (Week 3)

### Day 15-17: Integration Testing

**1. Deploy to fresh VPS:**
```bash
# Provision fresh NixOS VPS (Vultr/DigitalOcean)
# Time the deployment process (target: <30 minutes)

# Follow getting-started.md exactly as written
# Document any issues or unclear steps
```

**2. Test all user stories:**
```bash
# User Story 1: Developer deploys from template
# - Clone repo: ✅ / ❌
# - Customize config: ✅ / ❌
# - Deploy: ✅ / ❌
# - Matrix responds: ✅ / ❌

# User Story 3: Developer contributes
# - Fork repo: ✅ / ❌
# - Make change: ✅ / ❌
# - CI passes: ✅ / ❌
```

### Day 18-19: Security Review

**3. Final security audit:**
```bash
# Run gitleaks on full repo
cd ~/proj/nixos-matrix-platform-template
gitleaks detect --no-git --source .

# Manual review for personal info
rg 'clarun|talu|192\.168\.1\.|45\.77|/home/dan|jrz1|dlei@duck'

# Review git history (should be clean)
git log --all --oneline

# Test deployment guide on clean machine
```

### Day 20-21: Community Beta Testing

**4. Invite beta testers:**
```bash
# Share repo with 3-5 trusted community members
# Collect feedback on:
# - Documentation clarity
# - Deployment success
# - Missing information
# - Confusing steps
```

---

## Phase 4: Sync Workflow & Publication (Week 4)

### Day 22-23: Document Sync Workflow

**1. Create sync script:**
```bash
# Create scripts/sync-to-template.sh
# Based on research.md Decision 4
```

**2. Create sync-log.md:**
```bash
cat > ~/proj/nixos-matrix-platform-template/sync-log.md <<'EOF'
# Sync Log: ops-base → nixos-matrix-platform-template

This file tracks changes synced from the private ops-base repository.

## Initial Publication (2025-10-11)

**ops-base commit:** [hash]
**template tag:** v1.0.0

**Initial modules:**
- matrix-continuwuity.nix
- mautrix-slack.nix
- mautrix-whatsapp.nix
- mautrix-gmessages.nix
- dev-services.nix
- security/fail2ban.nix
- security/ssh-hardening.nix
- matrix-secrets/default.nix

**Documentation:**
- Extracted from 300KB+ worklogs
- Sanitized for public consumption
- Tested with beta users
EOF
```

### Day 24-25: Final Polish

**3. Update README:**
```bash
# Expand README with:
# - Feature list
# - Quick start link
# - Architecture overview
# - Community links
# - Badges (CI status, license)
```

**4. Create v1.0.0 release:**
```bash
git tag v1.0.0
git push --tags
```

### Day 26-28: Publication

**5. Final validation:**
```bash
# ✅ All CI checks pass
# ✅ gitleaks returns 0 findings
# ✅ All example configs build
# ✅ Documentation complete
# ✅ Beta testing feedback addressed
# ✅ LICENSE and governance files present
```

**6. Make repository public:**
```bash
# GitHub Settings → Change repository visibility → Make public
```

**7. Announce:**
```bash
# Post to:
# - Matrix.org community (#nix:nixos.org)
# - NixOS Discourse
# - Reddit r/NixOS
# - Hacker News (Show HN)
# - Personal blog/social
```

---

## Success Metrics

After publication, track:

- ✅ SC-001: Deployment time <30 minutes (tested in Phase 3)
- ✅ SC-002: All builds pass (CI badge green)
- ✅ SC-003: gitleaks 0 findings (CI validates)
- ✅ SC-004: All 8 modules present and building (checklist: matrix-continuwuity, mautrix-slack, mautrix-whatsapp, mautrix-gmessages, dev-services, fail2ban, ssh-hardening, matrix-secrets)
- ✅ SC-005: All 8 documentation sections complete (checklist: getting-started.md, architecture.md, secrets-management.md, 3 bridge guides, 2 pattern docs)
- 📊 SC-007: 10+ stars in 3 months (GitHub insights)
- 📊 SC-008: 3+ issues/PRs in 3 months (GitHub insights)
- 📊 SC-009: 0 security incidents in 6 months (monitor issues)
- 📊 SC-010: Quarterly syncs (check sync-log.md)

---

## Troubleshooting

### Common Issues

**Issue: gitleaks fails in CI**
```bash
# Check which file triggered
# Review contracts/sanitization-rules.yaml for pattern
# Add to sanitization script if valid pattern
# Or add to .gitleaksignore if false positive
```

**Issue: nix flake check fails**
```bash
# Run locally: nix flake check
# Check error message for file/line
# Common causes:
# - Missing import
# - Syntax error
# - Invalid option type
```

**Issue: Personal info found during review**
```bash
# Add to sanitization script
# Re-run sanitization on affected files
# Run validation again
# Force-push if already committed
```

---

## Next Steps

After v1.0.0 publication:

1. Monitor GitHub issues and discussions
2. Set quarterly calendar reminder for sync (January, April, July, October)
3. Respond to community feedback
4. Plan v1.1 improvements based on usage
5. Consider adding: Cachix, more bridges, monitoring stack

---

## Reference Documents

- **Feature Spec**: `specs/001-extract-matrix-platform/spec.md`
- **Implementation Plan**: `specs/001-extract-matrix-platform/plan.md`
- **Research**: `specs/001-extract-matrix-platform/research.md`
- **Data Model**: `specs/001-extract-matrix-platform/data-model.md`
- **Contracts**: `specs/001-extract-matrix-platform/contracts/`
- **RFC**: `~/proj/ops-base/docs/rfcs/repository-publication-strategy-rfc.md`

---

## Questions?

Refer to research.md for detailed technical decisions, or review the RFC for rationale behind the overall approach.