RomM

v1.0.0

Manage a ROM library with artwork, metadata, saves, and browser play.

games by getarcaneapp

x-arcane:
  icon: "https://cdn.jsdelivr.net/gh/selfhst/icons@main/svg/romm.svg"
  urls:
    - "https://docs.romm.app/latest/getting-started/quick-start/"
services:
  romm:
    image: "rommapp/romm:latest"
    restart: "unless-stopped"
    ports:
      - "${PORT:-8080}:8080"
    environment:
      DB_HOST: "db"
      DB_NAME: "romm"
      DB_USER: "romm"
      DB_PASSWD: "${DB_PASSWORD:?Set DB_PASSWORD in .env}"
      ROMM_AUTH_SECRET_KEY: "${AUTH_SECRET:?Set AUTH_SECRET in .env}"
      SCREENSCRAPER_USER: "${SCREENSCRAPER_USER:-}"
      SCREENSCRAPER_PASSWORD: "${SCREENSCRAPER_PASSWORD:-}"
      RETROACHIEVEMENTS_API_KEY: "${RETROACHIEVEMENTS_API_KEY:-}"
      STEAMGRIDDB_API_KEY: "${STEAMGRIDDB_API_KEY:-}"
      IGDB_CLIENT_ID: "${IGDB_CLIENT_ID:-}"
      IGDB_CLIENT_SECRET: "${IGDB_CLIENT_SECRET:-}"
      HASHEOUS_API_ENABLED: "true"
    volumes:
      - "resources:/romm/resources"
      - "redis-data:/redis-data"
      - "${LIBRARY_PATH:-/data/media/roms}:/romm/library"
      - "assets:/romm/assets"
      - "config:/romm/config"
    depends_on:
      db:
        condition: "service_healthy"
    labels:
      com.getarcaneapp.arcane.icon: "https://cdn.jsdelivr.net/gh/selfhst/icons@main/svg/romm.svg"
  db:
    image: "mariadb:11.4"
    restart: "unless-stopped"
    environment:
      MARIADB_DATABASE: "romm"
      MARIADB_USER: "romm"
      MARIADB_PASSWORD: "${DB_PASSWORD:?Set DB_PASSWORD in .env}"
      MARIADB_ROOT_PASSWORD: "${DB_ROOT_PASSWORD:?Set DB_ROOT_PASSWORD in .env}"
    volumes:
      - "db-data:/var/lib/mysql"
    healthcheck:
      test:
        - "CMD"
        - "healthcheck.sh"
        - "--connect"
        - "--innodb_initialized"
      interval: "10s"
      timeout: "5s"
      retries: 10
      start_period: "30s"
    labels:
      com.getarcaneapp.arcane.icon: https://cdn.jsdelivr.net/gh/selfhst/icons@main/svg/mariadb.svg
volumes:
  resources: {}
  redis-data: {}
  assets: {}
  config: {}
  db-data: {}

# Replace every change-me with an independent secret before deployment.
# Generate secrets with: openssl rand -hex 32
PORT=8080
DB_PASSWORD=change-me
DB_ROOT_PASSWORD=change-me
AUTH_SECRET=change-me
SCREENSCRAPER_USER=
SCREENSCRAPER_PASSWORD=
RETROACHIEVEMENTS_API_KEY=
STEAMGRIDDB_API_KEY=
IGDB_CLIENT_ID=
IGDB_CLIENT_SECRET=
# Existing ROM collection, writable by the container.
LIBRARY_PATH=/data/media/roms

README

Manage a ROM library with artwork, metadata, saves, and browser play.

Copy .env.example to .env, review the settings, then run docker compose up -d. In Arcane, import the template and supply the same environment variables. Replace every change-me value before starting. Generate independent secrets with openssl rand -hex 32; use hexadecimal database passwords so connection URLs need no escaping. Use docker compose ps and docker compose logs to check startup.

Open http://localhost:8080 and create the initial administrator account. Set LIBRARY_PATH to an existing absolute host directory; /data/media/roms is the example. Ensure the container can read and write it. Populate that directory using the upstream folder structure, typically roms/<platform>/, then scan from the UI. The library is a bind mount; back it up separately from the named volumes.

Metadata providers are optional and configured independently: ScreenScraper needs a username and password; RetroAchievements and SteamGridDB need API keys; IGDB needs a Twitch application client ID and secret. Hasheous is enabled without credentials. See metadata provider setup. Assets, resources, configuration, internal Redis state, and MariaDB each have persistent volumes.

Named volumes preserve server data across container recreation. Back up these volumes before upgrades; docker compose down -v deletes them. Set PORT to an unused host port. For remote browser access, put HTTPS in front of the application and update its public URL setting where provided.

Upstream documentation: RomM deployment.