ansible-collection-docker-apps/roles/romm/README.md

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 }}"