---
date-created: 2026-10-20 19:15
date-modified: 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](https://github.com/rommapp/romm/releases/tag/5.3.0)
- [RomM 5.4.0 release](https://github.com/rommapp/romm/releases/tag/5.4.0)
- [RomM 5.4.0 configuration example](https://github.com/rommapp/romm/blob/5.4.0/examples/config.example.yml)
- [RomM 5.4.0 Python requirement](https://github.com/rommapp/romm/blob/5.4.0/pyproject.toml)
- [[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.