NixOS/specs/003-vps-image-migration/tasks.md

description

description
Task list for VPS Image Migration

Tasks: VPS Image Migration

Input: Design documents from /specs/003-vps-image-migration/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/

Tests: Not requested.

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Format: [ID] [P?] [Story] Description

• [P]: Can run in parallel (different files, no dependencies)
• [Story]: Which user story this task belongs to (e.g., US1, US2, US3)
• Include exact file paths in descriptions

Phase 1: Setup (Shared Infrastructure)

Purpose: Project initialization and validation setup

• T001 Review current image generation usage in flake.nix and parts/packages.nix and note all nixos-generators references
• T002 [P] Review host structure in hosts/ to mirror patterns for the new hosts/vps/configuration.nix

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Remove deprecated generator and ensure existing outputs are preserved

• T003 Update parts/packages.nix to build emacs-vm from nixpkgs/NixOS outputs (remove nixos-generators usage)
• T004 Remove nixos-generators input from flake.nix
• T005 Update flake.lock to drop nixos-generators entries
• T006 STOP: Ask user to validate emacs-vm build works without nixos-generators (confirm before proceeding) (reference parts/packages.nix)

Checkpoint: Foundation ready after user confirmation

---

Phase 3: User Story 1 - Provision a VPS Image (Priority: P1) 🎯 MVP

Goal: Define a new vps host and produce a Linode-compatible image artifact

Independent Test: Build the vps image, launch a Linode instance from it, verify network connectivity and remote access

Implementation for User Story 1

• T007 [US1] Create hosts/vps/configuration.nix with base imports and minimal networking/remote access enablement
• T008 [US1] Register vps host in parts/hosts.nix using existing createConfig pattern
• T009 [US1] Add a Linode image build output for vps in parts/packages.nix using the upstream NixOS image workflow
• T010 [US1] Document the vps host entry and image artifact location in docs/reference/index.md
• T011 [US1] Add a manual validation checklist entry for vps boot connectivity and remote access in specs/003-vps-image-migration/quickstart.md

Checkpoint: vps image builds and can boot with connectivity

---

Phase 4: User Story 2 - Secrets Available After Enrollment (Priority: P2)

Goal: Secure two-phase secrets bootstrap and enrollment workflow

Independent Test: Boot vps, generate host key, enroll key, re-encrypt secrets, redeploy, verify secrets available

Implementation for User Story 2

• T012 [US2] Set secure host posture for vps in hosts/vps/configuration.nix (secureHost enabled, secrets gated)
• T013 [US2] Add vps-specific sops-nix bootstrap settings in hosts/vps/configuration.nix (generate key on first boot; no baked key)
• T014 [US2] Document the enrollment and re-encryption steps in docs/playbooks/enroll-vps.md
• T015 [US2] Update secrets guidance to reference the vps enrollment flow in docs/constitution.md

Checkpoint: vps can boot without secrets, then unlocks secrets after enrollment and redeploy

---

Phase 5: User Story 3 - Remote Rebuild Workflow (Priority: P3)

Goal: Provide a documented, repeatable remote rebuild process

Independent Test: Trigger a rebuild from an explicitly authorized operator machine and verify applied config changes

Implementation for User Story 3

• T016 [US3] Add a rebuild helper script in scripts/rebuild-vps.sh with clear inputs and safety checks
• T017 [US3] Document remote rebuild usage and prerequisites (explicitly authorized operator machines only) in docs/playbooks/vps-rebuild.md

Checkpoint: remote rebuild flow is repeatable and documented

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Final consistency checks and documentation polish

• T018 [P] Ensure vps host is referenced in any host inventories or indexes in docs/reference/index.md
• T019 Validate quickstart steps still match implementation in specs/003-vps-image-migration/quickstart.md
• T020 Validate existing host/image builds after migration (document results in specs/003-vps-image-migration/quickstart.md)

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies - can start immediately
• Foundational (Phase 2): Depends on Setup completion - BLOCKS all user stories
• User Stories (Phase 3+): Depend on Foundational completion and user validation at T006
• Polish (Final Phase): Depends on desired user stories being complete

User Story Dependencies

• User Story 1 (P1): Starts after Phase 2 and user validation at T006
• User Story 2 (P2): Starts after Phase 2 and user validation at T006; depends on vps host existing (T007/T008)
• User Story 3 (P3): Starts after Phase 2 and user validation at T006; can be done in parallel with US2

Parallel Opportunities

• T002 can run in parallel with T001
• T018 and T019 can run in parallel in the Polish phase
• After T006, US2 and US3 can proceed in parallel once US1 host scaffolding exists

---

Parallel Example: User Story 2

Task: "Set secure host posture for vps in hosts/vps/configuration.nix"
Task: "Document the enrollment and re-encryption steps in docs/playbooks/enroll-vps.md"

---

Implementation Strategy

MVP First (User Story 1 Only)

1. Complete Phase 1: Setup
2. Complete Phase 2: Foundational
3. Pause at T006 for user validation of emacs-vm
4. Complete Phase 3: User Story 1
5. Stop and validate the image boot and connectivity

Incremental Delivery

1. Complete Setup + Foundational → user validates emacs-vm
2. Add User Story 1 → validate image build/boot
3. Add User Story 2 → validate secrets enrollment flow
4. Add User Story 3 → validate remote rebuild workflow
5. Polish and doc consistency checks