dev/docs/00 INBOX/ai/romm-migration-design-tree.md

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.