From f1a93199c755f248118b6882de8a4c04ad96cefe Mon Sep 17 00:00:00 2001 From: alexion Date: Mon, 19 Oct 2026 20:04:50 -0400 Subject: [PATCH] docs: plan RomM migration --- .../00 INBOX/ai/romm-migration-design-tree.md | 106 ++++++++++++++++++ docs/03 wrk/tasks/0013-oidc-provider.md | 17 +++ docs/03 wrk/tasks/0014-romm-guest.md | 42 +++++++ docs/03 wrk/tasks/0015-romm-5-4-package.md | 31 +++++ .../tasks/0016-romm-manual-rom-migration.md | 24 ++++ 5 files changed, 220 insertions(+) create mode 100644 docs/00 INBOX/ai/romm-migration-design-tree.md create mode 100644 docs/03 wrk/tasks/0013-oidc-provider.md create mode 100644 docs/03 wrk/tasks/0014-romm-guest.md create mode 100644 docs/03 wrk/tasks/0015-romm-5-4-package.md create mode 100644 docs/03 wrk/tasks/0016-romm-manual-rom-migration.md diff --git a/docs/00 INBOX/ai/romm-migration-design-tree.md b/docs/00 INBOX/ai/romm-migration-design-tree.md new file mode 100644 index 0000000..9970a25 --- /dev/null +++ b/docs/00 INBOX/ai/romm-migration-design-tree.md @@ -0,0 +1,106 @@ +# RomM migration design tree + +## Known facts + +- RomM is listed under the Pikachu and Pichu Proxmox migration. +- Pikachu already runs VLAN 20 guests with persistent storage. +- Nixpkgs provides a tested `services.romm` module at version 5.2.0. +- `services.romm.dataDir` defaults to `/var/lib/romm`. +- RomM stores the game library below `/var/lib/romm/library`. +- RomM stores saves, states, user-uploaded screenshots, and profile avatars below `/var/lib/romm/assets/users//`. +- RomM derives `` from its database ID, so it is not a stable configured username. +- RomM stores scraped covers and provider-sourced game screenshots below `/var/lib/romm/resources/roms///`. +- RomM 5.4.0 exists upstream but Nixpkgs does not package it. +- RomM 5.3.0 requires an explicit library-structure declaration in `config.yml`. +- The 5.4.0 package phase must add the Structure A declaration for `roms/{platform}/{game}` and `bios/{platform}`. +- RomM 5.4.0 can modify ROM files in place only when library conversion is explicitly enabled. +- RomM 5.3.0 identifies hashed ROMs by CRC, MD5, and SHA-1 after a scan. +- RomM 5.3.0 matches moved or renamed hashed ROMs to their existing database records. +- This migration is a fresh installation. +- The new library will receive selected ROMs from the old installation. +- Copyparty serves `/pikachu/media` as its writable `/media` volume. + +## Decision tree + +- RomM deployment + - Target location + - Settled: Deploy a dedicated guest on Pikachu. + - Package source + - Settled: Start with Nixpkgs's RomM 5.2.0 package. + - Settled: Package RomM 5.4.0 locally as follow-up work. + - Persistent storage + - Settled: Use `/var/lib/romm` in the guest. + - Settled: Mount `/pikachu/data/romm` at `/var/lib/romm`. + - Settled: Mount the ROM library separately at `/var/lib/romm/library`. + - Settled: Mount user assets separately for Copyparty browsing. + - Settled: Keep scraped resources in `/pikachu/data/romm`. + - Settled: Mount `/pikachu/media/games/emulation/roms` at `/var/lib/romm/library/roms`. + - Settled: Mount `/pikachu/media/games/emulation/bios` at `/var/lib/romm/library/bios`. + - Settled: Mount `/pikachu/media/games/emulation/users` at `/var/lib/romm/assets/users`. + - Settled: Mount `/pikachu/data/romm/postgresql` at `/var/lib/postgresql`. + - Settled: Mount `/pikachu/data/romm/redis` at `/var/lib/redis-romm`. + - Guest networking + - Settled: Follow the standard guest-provisioning protocol, including its VLAN 20 DHCP reservation. + - Public route + - Settled: Retain the old installation's public domain. + - Metadata and authentication secrets + - Settled: Configure IGDB, ScreenScraper, and SteamGridDB. + - Settled: Use RomM's default metadata and artwork priority. + - Settled: Manage the 5.4.0 `config.yml` declaratively with Nix. + - Settled: Use RomM's default region and English-language priority. + - Save synchronization + - Settled: Disable automatic browser save synchronization in 5.4.0. + - Authentication + - Settled: Use RomM's built-in accounts initially. + - Deferred: Configure RomM as an OpenID Connect client after an identity provider exists. + - ROM selection and import + - Settled: The operator manually selects and copies ROMs after deployment. + - Settled: Do not create automatic import tooling or a ROM manifest. + - Capacity and service limits + - Settled: Limit the guest to `4G` memory, `200%` CPU, and `512` tasks. + - Library scanning + - Settled: Enable the filesystem watcher for library changes. + - Cutover and retirement + - Out of scope: The operator manages the old installation and public-domain cutover outside this monorepo. + - Work phases + - Settled: Create a RomM guest module with Nixpkgs's package in [[0014-romm-guest]]. + - Settled: Package RomM 5.4.0 locally and reuse `services.romm` in [[0015-romm-5-4-package]]. + - Settled: Move selected ROMs after the service deployment is ready in [[0016-romm-manual-rom-migration]]. + +## Settled decisions + +- **Migration model:** Start with a fresh RomM installation. +- **Data scope:** Copy selected ROMs from the old installation. +- **Old application state:** Do not migrate the database, users, sessions, or job queue. +- **Deployment target:** Deploy a dedicated guest on Pikachu. +- **Initial package:** Use Nixpkgs's RomM 5.2.0 package. +- **Package follow-up:** Package RomM 5.4.0 locally. +- **Work phases:** Deploy the guest, update the package, then import selected ROMs. +- **Guest data directory:** Use RomM's default `/var/lib/romm`. +- **Host application data:** Mount `/pikachu/data/romm` at `/var/lib/romm`. +- **ROM library:** Mount it separately at `/var/lib/romm/library`. +- **Storage classification:** Preserve the distinction between application data and browsable media. +- **User assets:** Mount `/pikachu/media/games/emulation/users` at `/var/lib/romm/assets/users` to expose saves, states, user-uploaded screenshots, and profile avatars through Copyparty. +- **ROM paths:** Mount `/pikachu/media/games/emulation/roms` and `/pikachu/media/games/emulation/bios` at the corresponding children of `/var/lib/romm/library`. +- **Guest networking:** Follow the standard guest-provisioning protocol. +- **Public route:** Retain the old installation's public domain. +- **Metadata providers:** Configure IGDB, ScreenScraper, and SteamGridDB in both package phases. +- **Metadata priority:** Use RomM's default metadata and artwork priority. +- **RomM configuration:** Manage the required 5.4.0 `config.yml` declaratively with Nix. +- **Scan region and language priority:** Use RomM's defaults. +- **Initial authentication:** Use RomM's built-in accounts. +- **OIDC follow-up:** Track it in [[0013-oidc-provider]]. +- **ROM migration:** The operator manually selects and copies ROMs after deployment. +- **Guest limits:** Cap the guest at `4G` memory, `200%` CPU, and `512` tasks. +- **Library watcher:** Enable the filesystem watcher. +- **PostgreSQL:** Mount `/pikachu/data/romm/postgresql` at `/var/lib/postgresql`. +- **Redis:** Mount `/pikachu/data/romm/redis` at `/var/lib/redis-romm`. +- **Browser save synchronization:** Disable it in 5.4.0 until browser emulation is needed. + +## Frontier + +No in-scope decisions remain. + +## Next question + +None. Present the settled design for confirmation before implementation. diff --git a/docs/03 wrk/tasks/0013-oidc-provider.md b/docs/03 wrk/tasks/0013-oidc-provider.md new file mode 100644 index 0000000..468bbb6 --- /dev/null +++ b/docs/03 wrk/tasks/0013-oidc-provider.md @@ -0,0 +1,17 @@ +--- +aliases: + - "0013" + - OIDC Provider +date-created: 2026-10-19 19:40 +date-modified: 2026-10-19 19:40 +status: open +area: "[[homelab]]" +blocked-by: [] +subtasks: [] +--- + +# OIDC Provider + +Deploy an OpenID Connect provider for homelab services. + +Configure a RomM client after the provider is available. diff --git a/docs/03 wrk/tasks/0014-romm-guest.md b/docs/03 wrk/tasks/0014-romm-guest.md new file mode 100644 index 0000000..a4d6caf --- /dev/null +++ b/docs/03 wrk/tasks/0014-romm-guest.md @@ -0,0 +1,42 @@ +--- +aliases: + - "0014" + - RomM Guest +date-created: 2026-10-19 19:40 +date-modified: 2026-10-19 19:40 +status: open +area: "[[homelab]]" +blocked-by: [] +subtasks: [] +--- + +# RomM Guest + +Deploy a dedicated RomM guest on Pikachu with Nixpkgs RomM 5.2.0. + +Follow the standard guest-provisioning protocol. +Keep the old installation's public domain. + +Use the local PostgreSQL and Redis instances from `services.romm`. +Set guest limits to `4G` memory, `200%` CPU, and `512` tasks. +Enable the library watcher. +Use RomM built-in accounts. + +Mount persistent application data: + +```text +/pikachu/data/romm -> /var/lib/romm +/pikachu/data/romm/postgresql -> /var/lib/postgresql +/pikachu/data/romm/redis -> /var/lib/redis-romm +``` + +Mount browsable media: + +```text +/pikachu/media/games/emulation/roms -> /var/lib/romm/library/roms +/pikachu/media/games/emulation/bios -> /var/lib/romm/library/bios +/pikachu/media/games/emulation/users -> /var/lib/romm/assets/users +``` + +Configure IGDB, ScreenScraper, and SteamGridDB from secrets. +Use RomM's default metadata, artwork, region, and language priorities. diff --git a/docs/03 wrk/tasks/0015-romm-5-4-package.md b/docs/03 wrk/tasks/0015-romm-5-4-package.md new file mode 100644 index 0000000..6ca1746 --- /dev/null +++ b/docs/03 wrk/tasks/0015-romm-5-4-package.md @@ -0,0 +1,31 @@ +--- +aliases: + - "0015" + - RomM 5.4 Package +date-created: 2026-10-19 19:40 +date-modified: 2026-10-19 19:40 +status: open +area: "[[homelab]]" +blocked-by: + - "[[0014-romm-guest]]" +subtasks: [] +--- + +# RomM 5.4 Package + +Package RomM 5.4.0 locally. +Reuse `services.romm`. + +Manage `config.yml` declaratively with Nix. +Declare the Structure A library layout: + +```yaml +filesystem: + structure: + default: "roms/{platform}/{game}" + firmware: "bios/{platform}" +``` + +Keep library conversion disabled. +Disable automatic browser save synchronization until browser emulation is needed. +Keep the IGDB, ScreenScraper, and SteamGridDB configuration unchanged. diff --git a/docs/03 wrk/tasks/0016-romm-manual-rom-migration.md b/docs/03 wrk/tasks/0016-romm-manual-rom-migration.md new file mode 100644 index 0000000..c3a7147 --- /dev/null +++ b/docs/03 wrk/tasks/0016-romm-manual-rom-migration.md @@ -0,0 +1,24 @@ +--- +aliases: + - "0016" + - RomM Manual ROM Migration +date-created: 2026-10-19 19:40 +date-modified: 2026-10-19 19:40 +status: open +area: "[[homelab]]" +blocked-by: + - "[[0014-romm-guest]]" +subtasks: [] +--- + +# RomM Manual ROM Migration + +Manually copy selected ROMs and BIOS files from the old installation. + +Copy ROMs to `/pikachu/media/games/emulation/roms`. +Copy BIOS files to `/pikachu/media/games/emulation/bios`. + +Do not migrate the old database, users, sessions, job queue, or other application state. +Do not add automatic import tooling or a ROM manifest. + +This task does not change monorepo configuration.