dev/docs/00 INBOX/ai/romm-5-4-deployment-changes-design-tree.md

date-created, date-modified

date-created	date-modified
2026-10-20 19:15	2026-10-20 19:20

RomM 5.4 deployment changes

Known facts

• The deployed Nixpkgs package is RomM 5.2.0.
• RomM 5.4.0 requires Python 3.14 or later.
• The pinned Nixpkgs contains Python 3.14.
• The pinned Python package set lacks some RomM 5.4.0 dependency versions.
• For example, it provides RQ 2.10 while RomM requires RQ 2.12 or later.
• In this design, upstream means the Nixpkgs repository.
• Nixpkgs upstream still packages RomM 5.2.0.
• Two open Nixpkgs pull requests update RomM to 5.4.0.
• Pull request 574089 adds a required compatibility patch for Nixpkgs Redis 8.0.1.
• Pull request 574089 has not run the NixOS module test.
• The existing romm derivation already uses Python 3.14 from the pin.
• The package can override the current derivation without copying it.
• The override evaluates successfully with the RomM 5.4.0 source and frontend hashes.
• RomM reads config.yml from /var/lib/romm/config/config.yml.
• Systemd tmpfiles L+ replaces that path with a generated Nix-store symlink.
• NixOS modules use L+ symlinks for declaratively managed files in persistent application directories.
• The existing Nixpkgs RomM NixOS test starts the application with PostgreSQL, Redis, nginx, and the filesystem watcher in a local VM.
• The test does not deploy to Pikachu.
• The automated update changes only the version, source hash, and frontend dependency hash.
• The manual update also removes a Redis maintenance-notification import and argument.
• RomM does not require the rom-converto executable while ROM_CONVERTO_ENABLED is false.
• As checked on 2026-10-20, both pull requests remain open.
• Neither pull request has a review or a discussion comment.
• Both pull requests request review from the RomM package maintainers.
• Both pull requests pass evaluation and lint checks.
• Their package-test checks have a neutral result.
• The Darwin package-test jobs remain queued.
• RomM 5.3.0 added a required filesystem.structure declaration.
• RomM will not start without that declaration.
• The existing mounts match Structure A.
• Structure A maps ROMs to roms/{platform}/{game}.
• Structure A maps firmware to bios/{platform}.
• RomM 5.4.0 enables emulatorjs.auto_save_sync by default.
• RomM 5.4.0 adds optional in-place library conversion through rom-converto.
• Library conversion requires ROM_CONVERTO_ENABLED=true.
• Conversion deletes original files after conversion.
• The task requires declarative config.yml management.
• The task requires disabled browser save synchronization.
• The task requires disabled library conversion.
• The task retains the IGDB, ScreenScraper, and SteamGridDB configuration.
• The task reuses the Nixpkgs services.romm module.

Sources

• RomM 5.3.0 release
• RomM 5.4.0 release
• RomM 5.4.0 configuration example
• RomM 5.4.0 Python requirement
• 0015-romm-5-4-package

Decision tree

• RomM 5.4 deployment
  • Package runtime
    • Settled: Build the local package with Python 3.14.
    • Package source
      • Settled: Maintain a local package.
      • Constraint: Do not rely on either unreviewed Nixpkgs pull request.
    • Package exposure
      • Settled: Expose the package as pkgs.alexion.romm.
  • Library layout
    • Settled: Manage config.yml declaratively with Nix.
    • Configuration materialization
      • Settled: Replace the configuration file with a Nix-store symlink on activation.
    • Settled: Declare Structure A.
    • Settled: Set filesystem.structure.default to roms/{platform}/{game}.
    • Settled: Set filesystem.structure.firmware to bios/{platform}.
  • File safety
    • Settled: Keep library conversion disabled.
    • Settled: Do not enable ROM_CONVERTO_ENABLED.
  • Browser emulation
    • Settled: Set emulatorjs.auto_save_sync to false.
  • Existing integration
    • Settled: Reuse services.romm.
    • Settled: Keep IGDB, ScreenScraper, and SteamGridDB configuration unchanged.
  • Validation
    • Settled: Build the local package and the Pikachu configuration.
    • Settled: Do not run a local NixOS VM test.
    • Settled: The operator validates the deployment on Pikachu.

Settled decisions

• Build a local RomM 5.4.0 package.
• Do not rely on either unreviewed Nixpkgs pull request.
• Expose the package as pkgs.alexion.romm.
• Reuse services.romm.
• Generate config.yml with Nix.
• Replace config.yml with a Nix-store symlink on activation.
• Declare Structure A with roms/{platform}/{game} and bios/{platform}.
• Keep ROM_CONVERTO_ENABLED disabled.
• Set emulatorjs.auto_save_sync to false.
• Keep IGDB, ScreenScraper, and SteamGridDB configuration unchanged.
• Build the local package and Pikachu configuration.
• Do not run a local NixOS VM test.
• Let the operator validate the deployment on Pikachu.

Frontier

No in-scope decisions remain.