# 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 (treat this as the reference ruleset for nftables parity), 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.79.25.87. 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 the source of truth and implement equivalent nftables/NixOS firewall rules; document any intentional deviations. - 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 mirror the existing iptables behavior on the new VPS using nftables/NixOS firewall rules and document any intentional deviations from the source ruleset. - **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-017**: The system MUST configure SSHD to use port 3456 and disable root/password authentication to match the existing VPS security posture. - **FR-018**: The system MUST harden remote rebuild access by using a non-root SSH user with least-privilege access for rebuild operations. - **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, even if implemented via nftables equivalents. - 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.