From a74adc7f95d0b99b4b55fc6f6210d118b05208b1 Mon Sep 17 00:00:00 2001 From: Danilo Reyes Date: Tue, 3 Feb 2026 20:35:44 -0600 Subject: [PATCH] init --- AGENTS.md | 4 +- secrets/ssh/ed25519_deploy.pub | 1 + secrets/ssh/ed25519_lidarr-reports.pub | 1 + .../checklists/requirements.md | 34 ++++ .../004-vps-migration/contracts/openapi.yaml | 38 ++++ specs/004-vps-migration/data-model.md | 41 ++++ specs/004-vps-migration/plan.md | 52 ++++++ specs/004-vps-migration/quickstart.md | 36 ++++ specs/004-vps-migration/research.md | 31 +++ specs/004-vps-migration/spec.md | 176 ++++++++++++++++++ specs/004-vps-migration/tasks.md | 83 +++++++++ 11 files changed, 496 insertions(+), 1 deletion(-) create mode 100644 secrets/ssh/ed25519_deploy.pub create mode 100644 secrets/ssh/ed25519_lidarr-reports.pub create mode 100644 specs/004-vps-migration/checklists/requirements.md create mode 100644 specs/004-vps-migration/contracts/openapi.yaml create mode 100644 specs/004-vps-migration/data-model.md create mode 100644 specs/004-vps-migration/plan.md create mode 100644 specs/004-vps-migration/quickstart.md create mode 100644 specs/004-vps-migration/research.md create mode 100644 specs/004-vps-migration/spec.md create mode 100644 specs/004-vps-migration/tasks.md diff --git a/AGENTS.md b/AGENTS.md index 5f22ae7..d77f575 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,6 +7,8 @@ Auto-generated from feature plans. Last updated: 2026-01-30 - None (in-memory tool definitions; filesystem access for repo interactions) (002-mcp-server) - Nix (flakes; nixpkgs 25.11) + nixpkgs, flake-parts, sops-nix (003-vps-image-migration) - N/A (configuration repo) (003-vps-image-migration) +- Nix (flakes; nixpkgs 25.11) + NixOS modules, sops-nix, nginx, wireguard, openssh, iptables (004-vps-migration) +- Files (configuration and secrets) (004-vps-migration) - Documentation set (AI-facing constitution and playbooks) in Markdown (001-ai-docs) @@ -28,9 +30,9 @@ specs/001-ai-docs/ # Planning artifacts (plan, research, tasks, data model - Keep language business-level and technology-agnostic in AI-facing docs. ## Recent Changes +- 004-vps-migration: Added Nix (flakes; nixpkgs 25.11) + NixOS modules, sops-nix, nginx, wireguard, openssh, iptables - 003-vps-image-migration: Added Nix (flakes; nixpkgs 25.11) + nixpkgs, flake-parts, sops-nix - 003-vps-image-migration: Added [if applicable, e.g., PostgreSQL, CoreData, files or N/A] -- 003-vps-image-migration: Added Nix (flakes; nixpkgs 25.11) + nixpkgs, flake-parts, sops-nix diff --git a/secrets/ssh/ed25519_deploy.pub b/secrets/ssh/ed25519_deploy.pub new file mode 100644 index 0000000..4593ffc --- /dev/null +++ b/secrets/ssh/ed25519_deploy.pub @@ -0,0 +1 @@ +ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG6scNSRnOprOvqm5DSTSMORvh9c5z0S1GzX1D7u+gMw deploy@portfolio diff --git a/secrets/ssh/ed25519_lidarr-reports.pub b/secrets/ssh/ed25519_lidarr-reports.pub new file mode 100644 index 0000000..214c3ff --- /dev/null +++ b/secrets/ssh/ed25519_lidarr-reports.pub @@ -0,0 +1 @@ +ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKbCQ/f117hL7Z02Vog1RCaOVUi95beYf//Qppnqf2Ha lidarr-reports@lidarr-reports diff --git a/specs/004-vps-migration/checklists/requirements.md b/specs/004-vps-migration/checklists/requirements.md new file mode 100644 index 0000000..ce76831 --- /dev/null +++ b/specs/004-vps-migration/checklists/requirements.md @@ -0,0 +1,34 @@ +# Specification Quality Checklist: VPS Migration + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-02-04 +**Feature**: /home/jawz/Development/NixOS/specs/004-vps-migration/spec.md + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders +- [x] All mandatory sections completed + +## Requirement Completeness + +- [x] No [NEEDS CLARIFICATION] markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic (no implementation details) +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification + +## Notes + +- All checks passed on first review. diff --git a/specs/004-vps-migration/contracts/openapi.yaml b/specs/004-vps-migration/contracts/openapi.yaml new file mode 100644 index 0000000..b5c6aab --- /dev/null +++ b/specs/004-vps-migration/contracts/openapi.yaml @@ -0,0 +1,38 @@ +openapi: 3.0.3 +info: + title: VPS Migration Verification API + version: 0.1.0 + description: | + Optional verification endpoints for migration validation. These describe + checks that can be automated; if no API is implemented, treat as a checklist. +paths: + /verify/proxy: + get: + summary: Verify reverse proxy routing to host services + responses: + "200": + description: Proxy mappings resolve to services on host server + /verify/firewall: + get: + summary: Verify iptables ruleset parity + responses: + "200": + description: Firewall flows match expected allow/deny behavior + /verify/vpn: + get: + summary: Verify VPN peer connectivity and address assignment + responses: + "200": + description: All peers connect with correct addresses + /verify/ssh: + get: + summary: Verify SSH access for authorized principals + responses: + "200": + description: Authorized keys allow expected access only + /verify/analytics: + get: + summary: Verify analytics data migrated successfully + responses: + "200": + description: Historical analytics data present on new server diff --git a/specs/004-vps-migration/data-model.md b/specs/004-vps-migration/data-model.md new file mode 100644 index 0000000..a958d62 --- /dev/null +++ b/specs/004-vps-migration/data-model.md @@ -0,0 +1,41 @@ +# Data Model: VPS Migration + +## Host + +- **Fields**: name, role (primary/secondary), publicIp, vpnEndpoint, services[], proxyMappings[], firewallRuleSet +- **Rules**: Exactly one primary host for reverse proxying. + +## Service + +- **Fields**: name, enabled, runsOnHost, proxyEnabled, domains[] +- **Rules**: Services remain on host server; proxyEnabled true on VPS for all enabled services. + +## ProxyMapping + +- **Fields**: domain, targetService, tlsRequired +- **Rules**: domain must be unique across mappings; domain must match service definitions. + +## FirewallRuleSet + +- **Fields**: sourceFile (iptables), rules[], appliedHost +- **Rules**: Ruleset must be applied as-is; no translation allowed. + +## VPNPeer + +- **Fields**: name, publicKeyRef, allowedIps[] +- **Rules**: allowedIps must be unique across peers; publicKeyRef must resolve via secrets system. + +## VPNInterface + +- **Fields**: addressRanges[], listenPort, privateKeyRef +- **Rules**: privateKeyRef stored in secrets system; listenPort exposed on VPS. + +## ServiceUser + +- **Fields**: username, group, authorizedKeys[] +- **Rules**: deploy uses ed25519_deploy.pub; lidarr-reports uses ed25519_lidarr-reports.pub. + +## MigrationChecklistItem + +- **Fields**: task, verificationStep, status +- **Rules**: each migration task must have a verification step. diff --git a/specs/004-vps-migration/plan.md b/specs/004-vps-migration/plan.md new file mode 100644 index 0000000..3b39684 --- /dev/null +++ b/specs/004-vps-migration/plan.md @@ -0,0 +1,52 @@ +# Implementation Plan: VPS Migration + +**Branch**: `004-vps-migration` | **Date**: 2026-02-04 | **Spec**: /home/jawz/Development/NixOS/specs/004-vps-migration/spec.md +**Input**: Feature specification from `/specs/004-vps-migration/spec.md` + +## Summary + +Migrate VPS responsibilities to the new NixOS host by making it the primary reverse-proxy host (nginx only), mirroring the existing iptables ruleset, enabling wireguard with secret-managed keys, and restoring SSH/service-user access, while keeping all services running on the host server. Provide validation steps, review historical configs for gaps, and document analytics data migration. + +## Technical Context + +**Language/Version**: Nix (flakes; nixpkgs 25.11) +**Primary Dependencies**: NixOS modules, sops-nix, nginx, wireguard, openssh, iptables +**Storage**: Files (configuration and secrets) +**Testing**: Manual validation steps (no automated test harness) +**Target Platform**: Linux server (NixOS) +**Project Type**: configuration repo +**Performance Goals**: N/A (configuration change) +**Constraints**: Services remain on host server; VPS only terminates proxy and exposes wireguard port; iptables parity required +**Scale/Scope**: Single VPS + host server, small set of VPN peers and admin SSH principals + +## Constitution Check + +No enforceable constitution rules are defined (placeholders only). Gate passes by default. + +Post-design check: unchanged (no enforceable gates found). + +## Project Structure + +### Documentation (this feature) + +```text +specs/004-vps-migration/ +├── plan.md +├── research.md +├── data-model.md +├── quickstart.md +├── contracts/ +└── tasks.md +``` + +### Source Code (repository root) + +```text +hosts/ +modules/ +secrets/ +iptables +scripts/ +``` + +**Structure Decision**: Use the existing NixOS configuration layout (`hosts/`, `modules/`, `secrets/`) and the root `iptables` ruleset file. diff --git a/specs/004-vps-migration/quickstart.md b/specs/004-vps-migration/quickstart.md new file mode 100644 index 0000000..cb350b3 --- /dev/null +++ b/specs/004-vps-migration/quickstart.md @@ -0,0 +1,36 @@ +# Quickstart: VPS Migration + +## Prerequisites + +- Access to this repo and the new VPS host configuration +- Existing iptables ruleset file available at repo root: `iptables` +- VPN keys present in the secrets system +- SSH public keys present in `secrets/ssh/` + +## Steps + +1. Review the spec and clarifications: + - `/home/jawz/Development/NixOS/specs/004-vps-migration/spec.md` + +2. Ensure secrets are available: + - VPN private/public keys are stored in the secrets system + - `secrets/ssh/ed25519_deploy.pub` and `secrets/ssh/ed25519_lidarr-reports.pub` exist + +3. Update host configuration: + - Set new VPS as primary reverse proxy host + - Enable proxying for all enabled services (services remain on host server) + - Apply iptables ruleset as-is + - Enable wireguard on VPS and expose port + - Add service users and admin SSH keys + - Update VPS public IP to `45.33.0.228` in SSH configuration + - Update host server VPN client to target the new VPS + +4. Provide and review legacy proxy config: + - Supply caddy files for subdomain comparison + +5. Migrate analytics data: + - Export data from existing server + - Import into new server + - Validate historical data is present + +6. Run verification steps for each task (per spec FR-012). diff --git a/specs/004-vps-migration/research.md b/specs/004-vps-migration/research.md new file mode 100644 index 0000000..41c739b --- /dev/null +++ b/specs/004-vps-migration/research.md @@ -0,0 +1,31 @@ +# Research: VPS Migration + +## Decision 1: Reverse proxy role + +- **Decision**: New VPS runs nginx as the primary reverse proxy; services remain on the host server. +- **Rationale**: Matches the clarified scope and minimizes service migration risk while restoring proxy functionality. +- **Alternatives considered**: Migrating services to VPS; keeping old proxy (caddy) on Fedora VPS. + +## Decision 2: Firewall parity + +- **Decision**: Apply the existing iptables ruleset as-is on the new VPS. +- **Rationale**: Ensures exact behavioral parity for complex routing and hot-swap behavior. +- **Alternatives considered**: Translating to another firewall system; partial translation with mixed rules. + +## Decision 3: VPN key handling + +- **Decision**: Store VPN keys only in the existing secrets system; no plaintext keys in config. +- **Rationale**: Preserves confidentiality and aligns with encrypted secrets workflow. +- **Alternatives considered**: Plaintext inline keys; separate unmanaged secrets store. + +## Decision 4: Admin SSH principals + +- **Decision**: Limit admin SSH authorized_keys entries to workstation, server, deacero, and galaxy. +- **Rationale**: Keeps access scope bounded to explicitly requested principals. +- **Alternatives considered**: Auto-adding other hosts found in config; adding only after confirmation. + +## Decision 5: Analytics (Plausible) migration + +- **Decision**: Migrate existing analytics data to the new server. +- **Rationale**: Preserves historical reporting and continuity of metrics. +- **Alternatives considered**: Fresh start with no history; read-only legacy instance for history. diff --git a/specs/004-vps-migration/spec.md b/specs/004-vps-migration/spec.md new file mode 100644 index 0000000..f47f946 --- /dev/null +++ b/specs/004-vps-migration/spec.md @@ -0,0 +1,176 @@ +# Feature Specification: VPS Migration + +**Feature Branch**: `004-vps-migration` +**Created**: 2026-02-04 +**Status**: Draft +**Input**: User description: "start feature branch 004, the git fetch command will fail, so force 004. Feature 003 added a new hosts vps, as a linode host, I want to now fully migrate my existing fedora vps to this new nixos vps. to do so I want to bring in the configurations fedora vps has. 1. right now the nginx logic of my servers is disabled, because I let the fedora vps handle the reverse proxy through caddy. But I dont want that caddy logic, on nixos I want to let nginx take care of the reverse proxies, plus the logic is already backed in, there is a isLocal logic to the factory, and I dont remember exactly the name of the code. but there is some flag under the my. options that specifies the mainHost, the constitution mentions that mainHost is the host handling nginx and because the vps will be it, then main host needs to become vps, I think before it was miniserver. This change means, that all the currently enabled servers on the toggles.nix from the host server, should have the enableProxy flag on vps (double check the logic) this should make it so, that nginx runs on vps, and the servers run on server. 2. Add a step to ask me for the caddy files, just to check that the subdomains caddy handles for each server match the subdomains on the servers/.*nix files. 3. I use iptables on the fedora vps, and the nixos vps, well I dont mind you using another firewall but there are some complex firewall rules that I need them to work 100% as the original vps, the rules will be on a file named iptables, this is perhaps the most important step, otherwise the complex network configuration this vps has wont be able to hot swap and serve my servers to the world. + +4. modify the existing wireguard.nix module, doublecheck that isnt toggled anywhere, toggle it on vps and add this configuration to it +[Interface] +#DNS = 10.77.0.1 +Address = 10.77.0.1/24, 10.8.0.1/24, 10.9.0.1/24 +ListenPort = 51820 +PrivateKey = aDQHN3DfAGEFjVHRKIJ34CJKPcKx7HdYzkEbRNBNWGw= + +# me +[Peer] +PublicKey = OUiqluRaS4hmGvLJ3csQrnIM3Zzet50gsqtTABaUkH4= +AllowedIPs = 10.77.0.2/32 + +# friends +[Peer] # 7351 +PublicKey = rFgT6TXzRazK6GMazMNGjtOvzAAPST0LvCfN7QXsLho= +AllowedIPs = 10.8.0.2/32 +[Peer] +PublicKey = R1CTx5+CXivMI6ZEmRYsyFUFILhe6Qnub0iEIRvvrEY= +AllowedIPs = 10.8.0.3/32 +[Peer] +PublicKey = ecPNSacD6yVwpnLBs171z0xkw9M1DXKh/Kn70cIBcwA= +AllowedIPs = 10.8.0.4/32 +[Peer] +PublicKey = yg+2miZCrx89znFaUlU/le/7UIPgEAMY74fZfEwz8g4= +AllowedIPs = 10.8.0.5/32 + +# # gooners +# [Peer] +# PublicKey = GawtOvsZ75avelIri5CjGoPXd8AFpi9qlZ6dSsqUISE= +# AllowedIPs = 10.77.0.2/32, 10.9.0.2/32 + +can I use sops to encrypt the public and private keys? if so, on modules.nix you will see that the ips on that wireguard config correspond to wg-friend1...n when you get to this step pause and tell me to create the sops secrets for these public keys. + +5. I have two cicds on this server +drwxrwxr-x. 11 deploy www-data 4096 Dec 26 20:47 blog +drwxr-xr-x. 2 lidarr-reports lidarr-reports 4096 Nov 11 17:52 lidarr-mb-gap +drwxrwxr-x. 12 deploy www-data 4096 Dec 26 21:01 portfolio +I need you to create the service users and groups for deploy and lidarr-reports. +in those, I need you to add ./secrets/ssh/ed25519_deploy.pub to authorized_keys for the user deploy +and for lidarr-reports ed25519_lidarr-reports.pub + +6. similar to every other host, add ssh login authorized_keys for workstation, server, deacero, galaxy and check if Im missing one. Because this will replace the ssh vps on the ssh config, you need to replace the existing vps ip with 45.33.0.228. 7. change the configuration on the host server, so that its wireguard session, connects to this server (i think will ve done automagically when the ip changes right?) 8. Ive added sudo_hist and jawz_hist, which are a dump of the histfile of this server, just check if there is a configuration that Im missing, something I did on there that I missed, and add it to the clarification list, so when I run clarify I tell you if I want that or not, granted lots of those commands are trial and error, so I think I have everything. 9. I have setup a plausible server, write the steps necesary to migrate it, I dont know. + +10. add verification steps for every task we did, when youre done and" + +## Clarifications + +### Session 2026-02-04 + +- Q: Are any services being migrated to the new VPS, and what does enableProxy do? → A: No services are migrated; enableProxy only configures nginx on the VPS, wireguard exposes the port, and services continue running on the host server. +- Q: How should the analytics service be migrated? → A: Migrate existing analytics data to the new server. +- Q: How should firewall parity be achieved on the new VPS? → A: Use the existing iptables ruleset as-is. +- Q: Where should VPN keys be stored? → A: Preserve keys only in the existing secrets system. +- Q: Which admin hosts should receive SSH authorized_keys entries? → A: Only the listed hosts (workstation, server, deacero, galaxy). + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - Migrate VPS as Primary Host (Priority: P1) + +As an operator, I want the new VPS to become the primary host for reverse proxying and networking while services continue running on the host server, so public traffic and internal tunnels continue working after the migration. + +**Why this priority**: This is the core migration goal and failure would cause outages. + +**Independent Test**: Can be fully tested by switching the primary host role to the new VPS and verifying proxy and tunnel connectivity without depending on the other stories. + +**Acceptance Scenarios**: + +1. **Given** the new VPS is designated as the primary host, **When** proxying is enabled, **Then** public endpoints resolve through the new VPS while services remain on the host server. +2. **Given** the previous VPS is no longer handling proxying, **When** traffic is routed through the new VPS, **Then** no service loses external access. + +--- + +### User Story 2 - Preserve Firewall Behavior (Priority: P1) + +As an operator, I want the firewall behavior on the new VPS to match the existing VPS so that all current network paths continue to function. + +**Why this priority**: Firewall parity is critical to avoid breaking complex routing and hot-swap behavior. + +**Independent Test**: Can be fully tested by comparing allowed/blocked traffic and confirming all required network paths remain functional. + +**Acceptance Scenarios**: + +1. **Given** the firewall rules are applied to the new VPS, **When** all known inbound and outbound paths are exercised, **Then** they behave identically to the existing VPS. + +--- + +### User Story 3 - Restore Secure Access and VPN Peers (Priority: P2) + +As an operator, I want VPN peers and SSH access to be configured on the new VPS so administration and CI/CD access remain available. + +**Why this priority**: Secure access is required for operating and deploying services. + +**Independent Test**: Can be fully tested by connecting each VPN peer and verifying SSH access for each authorized user. + +**Acceptance Scenarios**: + +1. **Given** the VPN configuration is enabled on the new VPS, **When** each peer connects, **Then** each peer receives the correct addresses and can reach intended resources. +2. **Given** service users and admin users are created on the new VPS, **When** their authorized keys are used, **Then** SSH access succeeds with the expected permissions. + +--- + +### User Story 4 - Capture Migration Gaps and Validation (Priority: P3) + +As an operator, I want a checklist of potential missing configuration from existing server history and clear verification steps so the migration is safe and complete. + +**Why this priority**: This reduces risk of overlooked manual changes and provides confidence during cutover. + +**Independent Test**: Can be fully tested by running the verification steps and confirming no missing items remain. + +**Acceptance Scenarios**: + +1. **Given** historical command logs are reviewed, **When** likely missing configurations are identified, **Then** they are listed as clarifications for user confirmation. +2. **Given** verification steps are provided for each task, **When** the operator executes them, **Then** each migration task can be validated. + +--- + +### Edge Cases + +- What happens when a subdomain mapping differs between the previous proxy configuration and the current service definitions? +- How does the system handle a firewall rule that is ambiguous or conflicts with existing policy? +- What happens if an SSH key file is missing or invalid for a service user? + +## Requirements *(mandatory)* + +### Functional Requirements + +- **FR-001**: The system MUST designate the new VPS as the primary host for reverse proxying and ensure all enabled services are routed through it without relocating the services. +- **FR-002**: The system MUST ensure proxy configuration is enabled for all services currently enabled on the host server so traffic flows through the new VPS while services remain on the host server. +- **FR-003**: The system MUST request existing proxy configuration files for verification and flag any subdomain mismatches against current service definitions. +- **FR-004**: The system MUST apply firewall rules on the new VPS that match the existing VPS behavior for all documented inbound and outbound flows. +- **FR-014**: The system MUST apply the existing iptables ruleset as-is to achieve firewall parity. +- **FR-005**: The system MUST enable the VPN configuration on the new VPS with the specified peer addresses and ensure each peer is uniquely identified. +- **FR-006**: The system MUST support encrypting sensitive VPN keys and pause for user-provided secret material when required. +- **FR-015**: The system MUST store VPN keys only in the existing secrets system and must not place them in plaintext configuration. +- **FR-007**: The system MUST create service users and groups for deployment workflows and grant SSH access via specified public keys. +- **FR-008**: The system MUST configure SSH access for all standard admin hosts and update the VPS connection target to the new public IP. +- **FR-016**: The system MUST grant SSH access only to workstation, server, deacero, and galaxy admin hosts. +- **FR-009**: The system MUST update dependent host configurations so existing VPN client connections target the new VPS. +- **FR-010**: The system MUST review provided history logs and produce a clarification list of potential missing configurations. +- **FR-011**: The system MUST document migration steps for the analytics service and include them in the migration plan. +- **FR-013**: The system MUST include analytics data migration as part of the analytics service migration steps. +- **FR-012**: The system MUST provide verification steps for each migration task performed. + +### Key Entities *(include if feature involves data)* + +- **Host**: A server instance that can be assigned primary or secondary roles and hosts services. +- **Service**: A deployable workload with external endpoints and internal configuration. +- **Proxy Mapping**: The set of subdomains and routing rules that map public traffic to services. +- **Firewall Rule Set**: The collection of allowed and blocked network flows required for the VPS. +- **VPN Peer**: A client identity with assigned addresses and access constraints. +- **SSH Key**: A public key used for authenticated access to a user account. +- **Migration Checklist**: A list of tasks and verification steps that confirm readiness. + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-001**: 100% of services previously reachable via the old VPS are reachable via the new VPS after cutover. +- **SC-002**: All documented firewall flows (inbound and outbound) pass or block with the same outcomes as the old VPS. +- **SC-003**: 100% of configured VPN peers can connect and reach required internal addresses. +- **SC-004**: 100% of authorized SSH users can authenticate using their specified keys. +- **SC-005**: Migration verification steps can be completed in a single run without unresolved failures. + +## Assumptions + +- The existing proxy configuration files will be provided by the user for comparison. +- The firewall rules from the existing VPS are authoritative and should be mirrored on the new VPS. +- The list of standard admin hosts for SSH access is complete unless the review identifies an omission. +- The analytics service migration steps are documentation-only and do not require immediate cutover. diff --git a/specs/004-vps-migration/tasks.md b/specs/004-vps-migration/tasks.md new file mode 100644 index 0000000..65ee45a --- /dev/null +++ b/specs/004-vps-migration/tasks.md @@ -0,0 +1,83 @@ +# Tasks: VPS Migration + +**Branch**: `004-vps-migration` +**Date**: 2026-02-04 +**Spec**: /home/jawz/Development/NixOS/specs/004-vps-migration/spec.md +**Plan**: /home/jawz/Development/NixOS/specs/004-vps-migration/plan.md + +## Implementation Strategy + +Deliver MVP as User Story 1 (primary host reverse proxy + keep services on host server). Then complete firewall parity (US2), secure access (US3), and migration gap review + verification (US4). + +## Phase 1: Setup + +- [ ] T001 Confirm baseline files exist: iptables, secrets/ssh/ed25519_deploy.pub, secrets/ssh/ed25519_lidarr-reports.pub, secrets system entries for VPN keys +- [ ] T002 Create working checklist placeholder for verification steps in /home/jawz/Development/NixOS/specs/004-vps-migration/tasks.md (this file) + +## Phase 2: Foundational + +- [ ] T003 [P] Review toggles and mainHost options to identify reverse-proxy owner in hosts/ and modules/ (record candidate paths) +- [ ] T004 [P] Locate wireguard module and host toggles in modules/ and hosts/ (record candidate paths) +- [ ] T005 [P] Review SSH config locations and vps IP references to update to 45.33.0.228 +- [ ] T006 [P] Review caddy config locations to prepare subdomain comparison (record file paths) + +## Phase 3: User Story 1 (P1) - Primary VPS reverse proxy + +**Story goal**: New VPS is primary reverse-proxy host (nginx only) while services remain on host server. + +**Independent test criteria**: Proxy mappings resolve through VPS to host server services without relocating services. + +- [ ] T007 [US1] Set mainHost to vps in the relevant host/module option file (update file path once located) +- [ ] T008 [US1] Enable proxying for all enabled services on the VPS without moving service runtime (update relevant hosts/*/toggles.nix or equivalent) +- [ ] T009 [US1] Capture caddy config files and compare subdomains to servers/*.nix domain definitions; document mismatches in specs/004-vps-migration/quickstart.md + +## Phase 4: User Story 2 (P1) - Firewall parity + +**Story goal**: Firewall behavior on new VPS matches old VPS by applying iptables ruleset as-is. + +**Independent test criteria**: Known inbound/outbound flows match existing VPS behavior. + +- [ ] T010 [US2] Apply iptables ruleset as-is to VPS firewall configuration in hosts/vps/ or modules/ (reference repo root iptables file) + +## Phase 5: User Story 3 (P2) - Secure access and VPN peers + +**Story goal**: Wireguard enabled on VPS with secrets-managed keys; SSH access for service users and admin hosts. + +**Independent test criteria**: VPN peers connect with correct addresses; SSH keys authenticate as expected. + +- [ ] T011 [US3] Enable wireguard module on VPS host configuration (hosts/vps/ or equivalent) and ensure listen port exposed +- [ ] T012 [US3] Update wireguard peer configuration in modules/wireguard.nix using secrets refs for public/private keys (no plaintext) +- [ ] T013 [US3] Add service users and groups deploy and lidarr-reports with authorized_keys from secrets/ssh/ed25519_deploy.pub and secrets/ssh/ed25519_lidarr-reports.pub +- [ ] T014 [US3] Add admin SSH authorized_keys for workstation, server, deacero, galaxy in the standard SSH config files +- [ ] T015 [US3] Update SSH config to replace VPS IP with 45.33.0.228 +- [ ] T016 [US3] Update host server wireguard client configuration to target the new VPS endpoint + +## Phase 6: User Story 4 (P3) - Migration gaps and verification + +**Story goal**: Identify missing configuration from history logs and provide verification steps for every task. + +**Independent test criteria**: Clarification list exists and each task has a verification step. + +- [ ] T017 [US4] Review sudo_hist and jawz_hist for missing configuration; record clarification list in specs/004-vps-migration/quickstart.md +- [ ] T018 [US4] Document analytics data migration steps (export, import, validate) in specs/004-vps-migration/quickstart.md +- [ ] T019 [US4] Add verification steps for each task in specs/004-vps-migration/quickstart.md + +## Phase 7: Polish & Cross-Cutting Concerns + +- [ ] T020 [P] Update any references to old VPS proxy logic (caddy) to ensure nginx is the only proxy in documentation (README.org or docs/ if applicable) +- [ ] T021 [P] Validate that all tasks have explicit file paths and update task descriptions accordingly + +## Dependencies + +- US1 → US2 → US3 → US4 + +## Parallel Execution Examples + +- US1: T007, T008, T009 can proceed once T003 and T006 identify the correct files. +- US2: T010 can proceed once iptables application location is identified. +- US3: T011 and T015 can proceed after T004 and T005 identify file locations; T012 depends on secrets references. +- US4: T017, T018, T019 can proceed independently once logs are reviewed and quickstart.md is open. + +## Validation + +- All tasks use the required checklist format with IDs, story labels, and file paths (to be filled precisely in T021).