Migrate PorteGumi from the NucBox to Kubernetes without losing state #23

New issue

Open

opened 2026-10-13 18:43:37 -05:00 by portegumi · 0 comments

portegumi commented

2026-10-13 18:43:37 -05:00

Collaborator

Why

PorteGumi currently runs as a Hermes gateway on the NucBox. Moving it to the RKE2 cluster with TrueNAS-backed state could reduce pressure on the control-plane host, but this is deferred work, not authorization to migrate or interrupt the current service now. Forgegumi and Loregumi are separate running profiles and are not automatically in scope.

Scope

Inventory the default profile's durable Hermes home (conversations, memories, skills, plugins, scripts, cron, webhook routing, auth), local source customization, and necessary workspaces/unpushed changes outside Hermes home.
Decide on a version-matched single-replica container on a worker and TrueNAS-backed persistent storage. Prefer iSCSI RWO/ext4 for the existing SQLite WAL database, rather than placing the live WAL database on NFS. Give the durable volume a retention and backup/restore policy; the current truenas-iscsi class uses Delete reclaim behavior.
Stage a protected full Hermes backup or quiesced copy onto the PVC; test restore before any cutover. Keep credentials out of Git. Size and constrain disposable scratch/cache separately so the pod does not recreate node disk pressure.
Cut over Discord/webhook routing with only one default gateway active. Preserve the old host state, disabled but intact, until rollback has been tested and an observation period agreed.

Acceptance criteria

Current state, profiles, source patches, external workspaces, credentials, callbacks, and dependencies are inventoried; scope explicitly excludes or separately accounts for the other two profiles.
A TrueNAS volume with appropriate reclaim behavior and an independently verified backup/restore path is selected; SQLite state is not live-copied or shared between writers.
Restored conversations, memories/, skills, custom Forgejo review tools, cron, Discord, and a signed Forgejo webhook work in a disconnected test before cutover.
A single gateway runs on a suitable worker; restart/reschedule, storage persistence, and ephemeral-disk limits are validated.
The old gateway is stopped before enabling the new one; routing is switched and rollback to the intact host installation is documented and exercised before decommissioning.

Dependencies

Follow the storage conventions in #6 and application migration/rollback runbook in #11. No deployment or cutover is requested by creating this issue.

## Why PorteGumi currently runs as a Hermes gateway on the NucBox. Moving it to the RKE2 cluster with TrueNAS-backed state could reduce pressure on the control-plane host, but this is **deferred work**, not authorization to migrate or interrupt the current service now. Forgegumi and Loregumi are separate running profiles and are not automatically in scope. ## Scope - Inventory the default profile's durable Hermes home (conversations, memories, skills, plugins, scripts, cron, webhook routing, auth), local source customization, and necessary workspaces/unpushed changes outside Hermes home. - Decide on a version-matched single-replica container on a worker and TrueNAS-backed persistent storage. Prefer iSCSI RWO/ext4 for the existing SQLite WAL database, rather than placing the live WAL database on NFS. Give the durable volume a retention and backup/restore policy; the current `truenas-iscsi` class uses `Delete` reclaim behavior. - Stage a protected full Hermes backup or quiesced copy onto the PVC; test restore before any cutover. Keep credentials out of Git. Size and constrain disposable scratch/cache separately so the pod does not recreate node disk pressure. - Cut over Discord/webhook routing with only one default gateway active. Preserve the old host state, disabled but intact, until rollback has been tested and an observation period agreed. ## Acceptance criteria - [ ] Current state, profiles, source patches, external workspaces, credentials, callbacks, and dependencies are inventoried; scope explicitly excludes or separately accounts for the other two profiles. - [ ] A TrueNAS volume with appropriate reclaim behavior and an independently verified backup/restore path is selected; SQLite state is not live-copied or shared between writers. - [ ] Restored conversations, `memories/`, skills, custom Forgejo review tools, cron, Discord, and a signed Forgejo webhook work in a disconnected test before cutover. - [ ] A single gateway runs on a suitable worker; restart/reschedule, storage persistence, and ephemeral-disk limits are validated. - [ ] The old gateway is stopped before enabling the new one; routing is switched and rollback to the intact host installation is documented and exercised before decommissioning. ## Dependencies Follow the storage conventions in #6 and application migration/rollback runbook in #11. No deployment or cutover is requested by creating this issue.

portegumi added the

app-migration

storage

labels

2026-10-13 18:43:37 -05:00