# 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](https://docs.romm.app/latest/getting-started/metadata-providers) 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

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