path: root/docs/PHASE_EXECUTION_PLAN.md

# Phase Execution Plan

## Overview

This document defines the three-phase modernization plan for the CrashOverBurn web server infrastructure.

**Current State:**
- Single Nix flake with multiple services (cgit, ejabberd, murmur, movim, mailserver, nginx)
- Nixinate-based deployment to host `193.16.42.36`
- Secrets encrypted via age/Secrix
- Minimal website (static HTML)

**Target State:**
- Enhanced nixinate deployment with validation
- Self-hosted Git hosting (cgit + gitolite)
- Full website deployment at nixtaml.tech
- Two documented Git repositories

---

## Phase 1: Deployment Modernisation

### Objectives

1. **ENHANCE nixinate deployment** (NOT replace!)
   - Retain nixinate - it is the bleeding edge of correct deployment
   - Add additional validation steps
   - Add deployment helper apps

2. **Validate flake builds before deployment** (per common-infra-strategies.md §6)
   - `nix flake check`
   - `nix build .#nixosConfigurations.crash-over-burn-1.config.system.build.toplevel`

3. **Add deployment documentation**

### Tasks

- [ ] **KEEP nixinate** - DO NOT REMOVE
- [ ] Verify nixinate configuration in flake.nix (_module.args)
- [ ] Verify Secrix hostPubKey is configured for crash-over-burn-1
- [ ] Test `nix flake check` passes
- [ ] Test build produces valid system derivation: `nix build .#nixosConfigurations.crash-over-burn-1.config.system.build.toplevel`
- [ ] Add validation app to flake/apps (pre-deploy check)
- [ ] Document deployment workflow in docs/deployment.md
- [ ] Document nixinate usage and configuration
- [ ] Validate Secrix recipients: `nix run .#secrix -- -l`

### Dependencies

- nixinate (existing - KEEP)
- nixpkgs (existing)
- secrix (existing)
- **common-infra-strategies.md** (core guideline reference)

### Success Criteria

- `nix flake check` passes without errors
- `nix build .#nixosConfigurations.crash-over-burn-1.config.system.build.toplevel` succeeds
- Deployment via nixinate works
- Secrix recipients validated

---

## Phase 2: cgit Verification and Repository Creation

### Objectives

1. **Verify cgit + gitolite deployment**
   - Test cgit web interface at code.crashoverburn.com
   - Test git push over SSH to git@code.crashoverburn.com
   - Verify gitolite serves repositories

2. **Create nixtaml repository**
   - Initialize bare git repository in gitolite
   - Mirror from upstream source (if applicable)
   - Configure proper access controls

3. **Create nixtaml-website repository**
   - Create new repository for website content
   - Configure CI/CD to deploy on push to main

### Tasks

#### cgit Verification

- [ ] Verify uwsgi service runs: `systemctl status uwsgi`
- [ ] Test HTTP access to code.crashoverburn.com
- [ ] Test git clone over HTTP: `git clone http://code.crashoverburn.com/git/nixtaml.git`
- [ ] Test git clone over SSH: `git clone git@code.crashoverburn.com:nixtaml.git`
- [ ] Verify gitolite admin access works

#### Repository: nixtaml

- [ ] Create repository via gitolite
- [ ] Push initial content (existing flake from filesystem)
- [ ] Configure access (public read, authenticated write)
- [ ] Add remote to local working copy

#### Repository: nixtaml-website

- [ ] Create new empty repository in gitolite
- [ ] Set up basic website source files
- [ ] Configure nginx to serve from repository checkout
- [ ] Test deployment webhook (if applicable)

### Dependencies

- cgit.nix service module (Phase 1)
- nginx service (Phase 1)
- gitolite (existing in cgit.nix)

### Success Criteria

- cgit web interface accessible at code.crashoverburn.com
- Repository clone works via both HTTP and SSH
- nixtaml repository exists and is pushable
- nixtaml-website repository exists with content

---

## Phase 3: Website Integration (nixtaml.tech)

### Objectives

1. **Deploy website as nginx webroot**
   - Configure nginx virtual host for nixtaml.tech
   - Serve static content from git checkout
   - Enable HTTPS via ACME

2. **Migrate from crashoverburn.com**
   - Maintain both domains or redirect
   - Update DNS records
   - Configure SSL certificates

3. **Set up automated deployment**
   - Git post-receive hook to update webroot
   - Or: CI/CD pipeline for static builds

### Tasks

- [ ] Update DNS A/AAAA records for nixtaml.tech
- [ ] Configure nginx virtual host for nixtaml.tech
- [ ] Set up ACME certificate for nixtaml.tech
- [ ] Configure webroot path (suggested: `/var/lib/nixtaml-website`)
- [ ] Create post-receive hook for automatic deployment
- [ ] Test HTTPS access
- [ ] Verify website content renders correctly
- [ ] Update CrashOverBurn main site redirect (optional)

### Dependencies

- nginx (Phase 1)
- acme_server.nix (existing)
- nixtaml-website repository (Phase 2)

### Success Criteria

- nixtaml.tech resolves and loads over HTTPS
- Website content is properly served
- Push to nixtaml-website main branch deploys automatically

---

## Execution Order

```
Phase 1 ──────────────► Phase 2 ──────────────► Phase 3
(Deploy Modernization)│ (Git Hosting)          │ (Website)
• Enhance nixinate   │• Verify cgit         │• DNS for nixtaml.tech
• Validate builds     │• Create nixtaml      │• Configure nginx
• Document deploy   │• Create nixtaml-site  │• ACME cert
                      │                       │• Deploy hook
```

---

## Notes

- Secrets are encrypted via age (files in `secrets/`)
- Deployment target: 193.16.42.36 (SSH on port 1108)
- Deployment user: commander
- State persisted in `/persist/` (per service configs)
- **nixinate is the correct deployment tool - never replace it**

---

## References

- **common-infra-strategies.md** - Core guideline for deployment patterns, Secrix integration, and host constructors
- nixinate - Deployment tool (github:DarthPJB/nixinate)
- Secrix - Secrets management (github:platonic-systems/secrix)