RomM

Deploy RomM (Rom Manager) using Docker Compose.

Description

RomM is a self-hosted ROM manager and player for retro game libraries, with metadata scraping from ScreenScraper, RetroAchievements, SteamGridDB, and Hasheous.

Variables

Required

Variable	Default	Description
`romm_db_password`	`""`	MariaDB password for the RomM user
`romm_db_root_password`	`""`	MariaDB root password
`romm_auth_secret_key`	`""`	Auth secret; generate with `openssl rand -hex 32`
`romm_library_path`	`{{ app_dir }}/library`	Host path holding the ROM library

Optional — Deployment

Variable	Default	Description
`romm_http_port`	`8080`	Web interface port
`romm_container_version`	`latest`	RomM image tag
`romm_db_container_version`	`latest`	MariaDB image tag
`romm_assets_path`	`{{ app_dir }}/assets`	Uploaded saves, states, screenshots
`romm_config_path`	`{{ app_dir }}/config`	Location of `config.yml`
`romm_resources_path`	`{{ app_dir }}/resources`	Fetched metadata (covers, screenshots)
`romm_mysql_data_path`	`{{ app_dir }}/mysql-data`	MariaDB data directory
`romm_redis_data_path`	`""`	Optional host path to persist RomM's in-container Redis cache. Leave empty to use the ephemeral default.
`romm_db_name`	`romm`	MariaDB database name
`romm_db_user`	`romm-user`	MariaDB username

Optional — Metadata providers

All metadata providers are optional. See the RomM metadata providers docs for how to obtain credentials. Empty credentials and disabled toggles are omitted from the rendered .env — no need to null out unused providers.

Variable	Default	Description
`romm_igdb_client_id`	`""`	IGDB client ID
`romm_igdb_client_secret`	`""`	IGDB client secret
`romm_screenscraper_user`	`""`	ScreenScraper username
`romm_screenscraper_password`	`""`	ScreenScraper password
`romm_mobygames_api_key`	`""`	MobyGames API key (paid subscription)
`romm_launchbox_api_enabled`	`false`	Enable the LaunchBox provider
`romm_launchbox_scheduled_update_enabled`	`false`	Enable scheduled LaunchBox metadata refresh
`romm_launchbox_scheduled_update_cron`	`""`	Cron expression for the LaunchBox refresh (defaults to RomM's built-in schedule when unset)
`romm_hasheous_api_enabled`	`true`	Enable the Hasheous provider
`romm_playmatch_api_enabled`	`false`	Enable the Playmatch provider
`romm_steamgriddb_api_key`	`""`	SteamGridDB API key
`romm_retroachievements_api_key`	`""`	RetroAchievements API key
`romm_flashpoint_api_enabled`	`false`	Enable the Flashpoint provider
`romm_hltb_api_enabled`	`false`	Enable the HowLongToBeat provider

By default, backups include assets, config, resources, and mysql-data. The library directory is excluded (typically large and often on separate storage), and the Redis cache is not mounted at all by default (RomM's built-in Redis is ephemeral). Override app_backup_subdirectories to change this.

Runtime environment variables for the romm service are rendered to {{ app_dir }}/.env (loaded via env_file: in the compose file), so the compose file itself stays short. The romm-db service reads the three shared DB values (DB_NAME, DB_USER, DB_PASSWD) from the same .env via compose's ${VAR} interpolation, so there's a single source of truth for the DB credentials. MARIADB_ROOT_PASSWORD stays inline in the compose file — it's DB-only and shouldn't be injected into the RomM container. app_compose_validate is disabled because compose validation runs against a temp path where the .env isn't co-located.

Example

- role: patrickj.docker_apps.romm
  vars:
    romm_http_port: 8080
    romm_library_path: /mnt/storage/roms
    romm_db_password: "{{ vault_romm_db_password }}"
    romm_db_root_password: "{{ vault_romm_db_root_password }}"
    romm_auth_secret_key: "{{ vault_romm_auth_secret_key }}"
    romm_igdb_client_id: "{{ vault_romm_igdb_client_id }}"
    romm_igdb_client_secret: "{{ vault_romm_igdb_client_secret }}"
    romm_screenscraper_user: "{{ vault_romm_screenscraper_user }}"
    romm_screenscraper_password: "{{ vault_romm_screenscraper_password }}"
    romm_retroachievements_api_key: "{{ vault_romm_retroachievements_api_key }}"
    romm_steamgriddb_api_key: "{{ vault_romm_steamgriddb_api_key }}"