# 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.