serverAppConfigs/docs/Dankserver/RomM.md

RomM

RomM (ROM Manager) is a self-hosted ROM library manager and player. It scans a ROM collection, enriches it with metadata and cover art from multiple providers, and serves it through a clean web interface. RomM also supports browser-based emulation via EmulatorJS and native emulator streaming.

Host: Dankserver — Hostname: romm.dankserver.local — Docs: https://docs.romm.app

Facts

Item	Value
Latest version	5.2.0 (released 2026-07-29)
Image	ghcr.io/rommapp/romm:latest
Port	8085 (host) → 8080 (container)
Database	MariaDB (default); PostgreSQL optional
Cache / Queue	Redis or Valkey (required for task queue)
Frontend	React SPA
Backend	FastAPI / Node
Metadata providers	IGDB, Screenscraper, MobyGames, Hasheous, Playmatch, LaunchBox, Flashpoint, HowLongToBeat, SteamGridDB, RetroAchievements, TGDB, ES-DE gamelist
Emulator player	EmulatorJS (WebAssembly RetroArch cores)
Emulator streaming	Native containers (PCSX2, Dolphin, Xemu) → browser

Architecture

RomM 5.2.0 requires three supporting services. The compose stack includes romm, mariadb, and redis (or valkey).

graph LR
    U[User] --> C[Caddy :80/:443]
    C --> R[RomM :8085]
    R --> DB[(MariaDB)]
    R --> Cache[(Redis)]
    R --> Lib[/romm/library]
    R --> Res[/romm/resources]

Configuration

Environment Variables

Variable	Required	Description
ROMM_USERNAME	Yes	Initial admin username
ROMM_PASSWORD	Yes	Initial admin password (set on first boot)
ROMM_AUTH_SECRET_KEY	Yes	JWT signing key. Generate with openssl rand -hex 32. Replaces the old ROMM_SECRET_KEY.
DB_HOST	Yes	MariaDB hostname (e.g. mariadb)
DB_NAME	Yes	Database name (e.g. romm)
DB_USER	Yes	Database user
DB_PASSWD	Yes	Database password
REDIS_HOST	Yes	Redis hostname (e.g. redis)
DISABLE_SETUP_WIZARD	No	Set to true to skip the first-run wizard
OIDC_ENABLED	No	Enable OpenID Connect authentication
OIDC_CLIENT_ID	No	OIDC client ID
OIDC_CLIENT_SECRET	No	OIDC client secret
OIDC_REDIRECT_URI	No	OIDC redirect URI
STREAMING_BROKER_SECRET	No	Secret for native emulator streaming
STREAMING_SAVE_TIMEOUT	No	Timeout for save states during streaming
KIOSK_MODE	No	Enable kiosk mode
ROMM_SESSION_SECURE_COOKIE	No	Secure cookie flag for sessions

Metadata Provider Credentials

These are set via environment variables or in config.yml:

Variable	Provider	Notes
IGDB_CLIENT_ID / IGDB_CLIENT_SECRET	IGDB (Twitch OAuth2)	Create app at Twitch Developer Portal. Free tier: ~10 req/sec.
SCREENSCRAPER_USER / SCREENSCRAPER_PASSWORD	Screenscraper	Account credentials (not API key). Free, community-driven.
MOBYGAMES_API_KEY	MobyGames	Paid hobbyist API. Note: RomM recommends Screenscraper as free alternative.
RETROACHIEVEMENTS_API_KEY	RetroAchievements	Hash-based achievements via bundled RAHasher binary.
STEAMGRIDDB_API_KEY	SteamGridDB	Custom cover art via the search cover button.
HASHEOUS_API_ENABLED	Hasheous	Set to true. Free, hash-based, proxies IGDB data. Fast scans.
PLAYMATCH_API_ENABLED	Playmatch	Set to true. Multi-provider hash matching (IGDB, SS, SteamGridDB, RA).

Config File

RomM uses config.yml for scan settings, available through the admin UI (Scan Settings). Place the file at /opt/romm/config/config.yml on the host.

Key scan config options:

scan:
  priority:
    metadata:
      - igdb
      - ss        # Screenscraper
    artwork:
      - igdb
      - ss
    region:
      - us
      - eu
      - jp
    region_mode: prefer_rom_tags   # or prefer_config
  media:
    - box2d
    - screenshot
    - manual
  gamelist:
    export: true    # Export ES-DE compatible gamelist.xml

Volumes

Container path	Host path (convention)
/romm/library	/opt/romm/library
/romm/resources	/opt/romm/resources
/romm/config	/opt/romm/config

The library volume contains ROM files and subdirectories per platform. The resources volume stores cached artwork, metadata, and the SQLite/SQLite-backed asset cache. The config volume holds config.yml and other configuration.

Docker Compose

services:
  romm:
    image: ghcr.io/rommapp/romm:latest
    container_name: romm
    restart: unless-stopped
    environment:
      ROMM_USERNAME: "${ROMM_USERNAME}"
      ROMM_PASSWORD: "${ROMM_PASSWORD}"
      ROMM_AUTH_SECRET_KEY: "${ROMM_AUTH_SECRET_KEY}"
      DB_HOST: mariadb
      DB_NAME: romm
      DB_USER: "${ROMM_DB_USER}"
      DB_PASSWD: "${ROMM_DB_PASSWD}"
      REDIS_HOST: redis
    ports:
      - "8085:8080"
    volumes:
      - /opt/romm/library:/romm/library
      - /opt/romm/resources:/romm/resources
      - /opt/romm/config:/romm/config
    depends_on:
      mariadb:
        condition: service_healthy
      redis:
        condition: service_healthy

  mariadb:
    image: docker.io/mariadb:11
    container_name: romm-mariadb
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: "${MARIADB_ROOT_PASSWORD}"
      MARIADB_DATABASE: romm
      MARIADB_USER: "${ROMM_DB_USER}"
      MARIADB_PASSWORD: "${ROMM_DB_PASSWD}"
    volumes:
      - /opt/romm/mariadb:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mariadb-admin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 3

  redis:
    image: docker.io/redis:7-alpine
    container_name: romm-redis
    restart: unless-stopped
    volumes:
      - /opt/romm/redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

Healthcheck

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 30s
  timeout: 10s
  retries: 3

Gotchas

• First login overwrites env credentials. The ROMM_PASSWORD env var sets the initial password. After first login, the admin password is controlled in the UI. The env var only applies on first boot.
• MariaDB and Redis are required. RomM 5.2.0 no longer supports SQLite-only deployments. Both MariaDB and Redis must be running.
• Reverse proxy cache stale index.html. Purge Caddy proxy cache after RomM version bumps to avoid serving a stale frontend after an upgrade.
• RAHasher build time. Enabling RetroAchievements hashing increases the first image build. Skip unless you need achievement data.
• MobyGames is paid. The hobbyist API has strict rate limits. Screenscraper is the recommended free alternative.
• OIDC requires additional services. Authentik, Keycloak, or another OIDC provider must be running before enabling OIDC_ENABLED.

See Also

• Dankserver Stack
• RomM Scraping — metadata providers, cover art, naming conventions, emulator integration
• Calibre-Web — sibling library web UI