docs: plan RomM migration
This commit was merged in pull request #197.
This commit is contained in:
106
docs/00 INBOX/ai/romm-migration-design-tree.md
Normal file
106
docs/00 INBOX/ai/romm-migration-design-tree.md
Normal file
@@ -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/<user-id>/`.
|
||||
- RomM derives `<user-id>` 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/<platform-id>/<rom-id>/`.
|
||||
- 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.
|
||||
Reference in New Issue
Block a user