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

- [x] **KEEP nixinate** - DO NOT REMOVE
- [x] Verify nixinate configuration in flake.nix (_module.args)
- [x] Verify Secrix hostPubKey is configured for crash-over-burn-1
- [x] Test `nix flake check` passes
- [x] Test build produces valid system derivation: `nix build .#nixosConfigurations.crash-over-burn-1.config.system.build.toplevel`
- [x] Add remote-command app to flake/apps
- [x] Document deployment workflow in docs/deployment.md
- [x] Validate Secrix recipients: `nix run .#secrix -- -l`
- [x] Fix deprecated: services.xserver.layout → services.xserver.xkb.layout
- [x] Fix deprecated: devShell → devShells.x86_64-linux.default

### 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

- [x] Verify uwsgi service runs: `systemctl status uwsgi`
- [x] Test HTTP access to code.crashoverburn.com (200 OK)
- [x] Verify gitolite serves repositories
- [ ] Test git clone over HTTP: `git clone http://code.crashoverburn.com/nixtaml.git`
- [ ] Test git clone over SSH: `git clone git@code.crashoverburn.com:nixtaml.git`
- [x] Configure public/private visibility via Nix (strict-export)

#### Repository: nixtaml

- [x] Create repository via gitolite (via gitolite-admin push)
- [x] Push initial content from /speed-storage/LLM-COMPLETE/nixtaml-prime
- [x] Configure as public repository
- [x] Add gitolite remote to local working copy

#### Repository: nixtaml-website

- [x] Create empty repository via gitolite
- [ ] Add initial website content
- [ ] Configure nginx to serve from repository checkout

### 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)

---

## Session Notes (2026-04-15)

### Completed Today
- Phase 1 fully complete (validation, deprecated fixes, documentation)
- Added `remote-command` app for SSH execution on remote
- Created gitolite-admin repos: nixtaml, nixtaml-website
- Pushed nixtaml from /speed-storage/LLM-COMPLETE/nixtaml-prime
- Configured cgit public/private visibility via Nix (strict-export)
- Updated AGENTS.md with comprehensive documentation

### Pending Next Session
1. **Deploy cgit changes**: `nix run .#crash-over-burn-1`
2. **Verify cgit shows all public repos** after deployment
3. **Test git clone** over HTTP and SSH
4. **Add content to nixtaml-website** repository
5. **Begin Phase 3**: nixtaml.tech website integration

### Key Learnings
- cgit visibility controlled by `git-daemon-export-ok` marker files
- Use `strict-export=git-daemon-export-ok` in cgitrc
- NEVER make imperative changes - always use Nix or gitolite-admin
- cgit accessible at root: https://code.crashoverburn.com/ (not /git/)