Add VPS 12-24-720 migration plan

docs/ops/HYPERTWIST_VPS_12_24_720_FORGEJO_WOODPECKER_MIGRATION_PLAN_2026-05-29.md

@@ -0,0 +1,288 @@
+# HyperTwist VPS 12-24-720 Forgejo/Woodpecker migration plan
+
+Last updated: `2026-05-29` (`Europe/Berlin`)
+
+## Purpose
+
+This is the tracked, non-sensitive migration plan for moving the current
+Forgejo/Woodpecker control-plane VPS to a new IONOS `VPS 12-24-720` Ubuntu
+`24.04` Linux server, while also preparing the host for JetBrains Rider Gateway
+remote development and Visual Studio Community 2022 remote Linux development.
+
+Sensitive companion:
+
+- local-only runbook copy:
+  `C:\HyperTwist\docs\refs\FORGEJO_WOODPECKER_VPS_A_TO_Z_SENSITIVE_RUNBOOK_VPS_12_24_720_UBUNTU_24_04_HYPERTWIST_MIGRATION_2026-05-29.md`
+
+Reason this companion is not pushed:
+
+- `docs/refs` is intentionally ignored
+- the runbook copy carries live and historical secret-bearing material
+
+## Current baseline
+
+Current source runbook:
+
+- `C:\HyperTwist\docs\refs\FORGEJO_WOODPECKER_VPS_A_TO_Z_SENSITIVE_RUNBOOK.md`
+
+Current live control-plane shape documented there:
+
+- Forgejo
+- Woodpecker server
+- VPS-local ops-only Woodpecker Docker agent
+- stack root: `/srv/scriptorium-stack`
+- NGINX reverse proxy
+- certbot-managed TLS
+- backup scripts and cron jobs
+- ops guards and journald retention policy
+
+## Recommended migration method
+
+Preferred method:
+
+- fresh Ubuntu `24.04` bootstrap on the new VPS
+- then explicit application-level stack migration
+
+Not recommended as the default:
+
+- whole-disk clone
+- opaque VM/image lift-and-shift
+
+Reason:
+
+- explicit migration preserves the stack and data that matter
+- it avoids dragging stale host state into the replacement server
+- rollback is simpler because the old VPS can remain live until the new one is
+  validated
+
+## Exact migration scope
+
+Migrate:
+
+- Forgejo Postgres data
+- Woodpecker Postgres data
+- Forgejo data directory
+- Woodpecker server-data directory
+- `/srv/scriptorium-stack/.env`
+- `/srv/scriptorium-stack/docker-compose.yml`
+- active NGINX vhost files that still belong on the replacement host
+- backup scripts
+- cron files
+- ops guard scripts
+- journald retention config
+- alerting env, if still in use
+
+Recreate on the new host rather than copying blindly:
+
+- SSH host keys
+- firewall state
+- certbot certificate issuance
+- machine-specific `systemd` state
+- package caches
+- Docker image/cache churn
+
+## Pending operator input
+
+### New VPS access
+
+Need:
+
+- new VPS public IPv4
+- new VPS public IPv6, if any
+- root SSH access method
+- confirmation that Ubuntu `24.04` is installed
+- confirmation whether the IONOS image includes Plesk or any other panel
+
+### DNS and nameserver information
+
+Need:
+
+- exact hostnames to move
+- current authoritative DNS provider
+- whether nameserver delegation itself is changing, or only record targets
+- if nameservers are changing:
+  - new nameserver hostnames
+  - glue IPs, if relevant
+- if only records are changing:
+  - exact `A` and `AAAA` targets
+- whether shared-zone `MX`, `TXT`, SPF, DKIM, DMARC, or unrelated records must
+  remain untouched
+- approved TTL-lowering window before cutover
+
+### Cutover scope
+
+Need:
+
+- confirm whether this VPS replacement is:
+  - control-plane only
+  - or control-plane plus app/API/static vhosts currently on the old host
+
+### Development-access setup
+
+Need:
+
+- desired non-root Linux username for development
+- whether that user should receive Docker-group access
+- whether the repo should be cloned fresh on the new VPS or copied from the old
+  server
+
+## Execution sequence
+
+### Phase A. Audit and freeze
+
+1. Verify the old VPS is healthy enough to migrate.
+2. Export and verify:
+   - Forgejo Postgres dump
+   - Woodpecker Postgres dump
+   - Forgejo data tarball
+   - Woodpecker data tarball
+3. Snapshot current live config:
+   - compose
+   - NGINX vhosts
+   - cron files
+   - timers
+   - certbot state
+4. Lower TTLs before cutover if possible.
+
+### Phase B. Bootstrap the new host
+
+1. Patch and harden Ubuntu `24.04`.
+2. Install baseline packages:
+   - `openssh-server`
+   - `rsync`
+   - `curl`
+   - `unzip`
+   - `zip`
+   - `make`
+   - `gdb`
+   - `build-essential`
+   - `nginx`
+   - `certbot`
+   - `python3-certbot-nginx`
+   - `docker.io`
+   - `docker-compose-plugin`
+   - `postgresql-client`
+3. Remove any unwanted panel image components before stack deployment.
+
+### Phase C. Restore the control-plane stack
+
+1. Recreate `/srv/scriptorium-stack`.
+2. Copy in `.env` and `docker-compose.yml`.
+3. Restore data directories.
+4. Start the stack before DNS cutover.
+5. Restore Postgres data if needed.
+
+### Phase D. Recreate backup and guard surfaces
+
+Reinstall and verify:
+
+- `/usr/local/bin/scriptorium-nightly-backup.sh`
+- `/usr/local/bin/scriptorium-disk-guard.sh`
+- `/usr/local/bin/scriptorium-forgejo-health-guard.sh`
+- `/etc/cron.d/scriptorium-nightly-backup`
+- `/etc/cron.d/scriptorium-ops-guards`
+- `/etc/cron.d/scriptorium-maintenance`
+- `/etc/systemd/journald.conf.d/90-scriptorium-limits.conf`
+- `/etc/scriptorium/ops-alerts.env`
+
+### Phase E. Recreate NGINX and TLS
+
+1. Install intended NGINX vhosts.
+2. Validate `nginx -t`.
+3. After DNS points to the new VPS, reissue certbot certificates on the new
+   host.
+
+### Phase F. Pre-cutover validation
+
+Validate locally on the new VPS:
+
+- containers healthy
+- Forgejo reachable
+- Woodpecker reachable
+- gRPC loopback binding present
+- cron files present
+- backup scripts callable
+- NGINX config valid
+
+### Phase G. DNS or nameserver cutover
+
+1. Change only the intended records or nameserver delegation.
+2. Wait for propagation.
+3. Reissue TLS if needed after propagation.
+4. Verify every moved hostname externally.
+
+### Phase H. Acceptance checks
+
+Require all of the following before deleting the old VPS:
+
+- Forgejo login works
+- SSH clone/fetch works
+- Woodpecker UI loads
+- webhook-triggered pipeline activity works
+- at least one real backup run completes on the new host
+- Rider remote development connects
+- Visual Studio remote Linux development connects
+
+## Rider remote-development setup
+
+Official source basis:
+
+- JetBrains Rider remote-development docs
+
+Key requirements:
+
+- SSH to a Linux host
+- SFTP enabled
+- recent AMD64 Linux
+- JetBrains recommends `2+` cores, `4+ GB` RAM, `5+ GB` disk
+- outbound access to JetBrains download URLs, or manual installer upload
+
+Recommended HyperTwist setup:
+
+- create a non-root development user
+- clone HyperTwist to `/home/<user>/src/HyperTwist`
+- use Rider Gateway from the local machine to connect over SSH
+- keep enough space available under the backend cache path, or choose a custom
+  install path
+
+## Visual Studio Community 2022 remote Linux setup
+
+Official source basis:
+
+- Microsoft Learn Visual Studio 2022 Linux development docs
+
+Important distinction:
+
+- this is not the same thin-client remote IDE model as Rider Gateway
+- for C++/CMake, Visual Studio uses SSH plus `rsync` and builds remotely
+- for .NET on Linux, Visual Studio supports SSH attach-debug scenarios
+
+Linux-side prerequisites for the C++ path include:
+
+- `openssh-server`
+- `build-essential`
+- `gdb`
+- `rsync`
+- `make`
+- `zip`
+- `cmake`
+
+Recommended use:
+
+- Rider Gateway for full remote IDE sessions
+- Visual Studio Community 2022 for Linux C++/CMake remote build/debug and, when
+  needed, .NET SSH attach-debug
+
+## Recommended next action
+
+Do not start live server migration yet.
+
+Next action is to fill the pending-input section above with:
+
+1. new VPS IP and access details
+2. DNS/nameserver details
+3. hostname cutover scope
+4. preferred development username
+
+Once those are supplied, the live execution pass can begin from the new-host
+bootstrap phase.