Skip to content

Quick Start

This guide gets a RomM instance up and running with the default stack (MariaDB + Valkey) using Docker Compose. If you're on Unraid, Synology, TrueNAS, or Kubernetes, check out the Install & Deploy section for platform-specific guides.

Before you start

You'll need:

Metadata providers are recommended

Scans work without a metadata API for basic use but setup problems and companion-app integrations (e.g. Playnite) can fail without them. Setting up at least one provider before your first scan is strongly recommended.

1. Write your docker-compose.yml

Start from the reference file shipped in the repo. A known-good, minimally-edited version is included below. Save it as docker-compose.yml in an empty directory on your host.

docker-compose.yml

`yaml version: "3"

volumes:
    mysql_data:
    romm_resources:
    romm_redis_data:

services:
    romm:
        image: rommapp/romm:latest
        container_name: romm
        restart: unless-stopped
        environment:
            - DB_HOST=romm-db
            - DB_NAME=romm # Should match MARIADB_DATABASE in mariadb
            - DB_USER=romm-user # Should match MARIADB_USER in mariadb
            - DB_PASSWD= # Should match MARIADB_PASSWORD in mariadb
            - ROMM_AUTH_SECRET_KEY= # Generate a key with `openssl rand -hex 32`
            - SCREENSCRAPER_USER= # These are the recommended metadata providers
            - SCREENSCRAPER_PASSWORD= # https://docs.romm.app/latest/getting-started/metadata-providers/#screenscraper
            - RETROACHIEVEMENTS_API_KEY= # https://docs.romm.app/latest/getting-started/metadata-providers/#retroachievements
            - STEAMGRIDDB_API_KEY= # https://docs.romm.app/latest/getting-started/metadata-providers/#steamgriddb
            - HASHEOUS_API_ENABLED=true # https://docs.romm.app/latest/getting-started/metadata-providers/#hasheous
        volumes:
            - romm_resources:/romm/resources # Resources fetched from IGDB (covers, screenshots, etc.)
            - romm_redis_data:/redis-data # Cached data for background tasks
            - /path/to/library:/romm/library # Your game library. Check https://github.com/rommapp/romm?tab=readme-ov-file#folder-structure for more details.
            - /path/to/assets:/romm/assets # Uploaded saves, states, etc.
            - /path/to/config:/romm/config # Path where config.yml is stored
        ports:
            - 80:8080
        depends_on:
            romm-db:
                condition: service_healthy
                restart: true

    romm-db:
        image: mariadb:latest
        container_name: romm-db
        restart: unless-stopped
        environment:
            - MARIADB_ROOT_PASSWORD= # Use a unique, secure password
            - MARIADB_DATABASE=romm
            - MARIADB_USER=romm-user
            - MARIADB_PASSWORD=
        volumes:
            - mysql_data:/var/lib/mysql
        healthcheck:
            test: [CMD, healthcheck.sh, --connect, --innodb_initialized]
            start_period: 30s
            start_interval: 10s
            interval: 10s
            timeout: 5s
            retries: 5

`

You'll want to edit the following values before launching:

Where Variable What to put
romm-db MARIADB_ROOT_PASSWORD A long, randomly generated password.
romm-db MARIADB_PASSWORD A separate long, randomly generated password.
romm DB_PASSWD Must match MARIADB_PASSWORD above.
romm ROMM_AUTH_SECRET_KEY Generate with openssl rand -hex 32 and keep it secret.
romm Metadata provider creds Fill in only the providers you've registered with (see Metadata Providers).
romm /path/to/library volume Host path to the directory containing your roms/ folder.
romm /path/to/assets volume Host storage paths for saves, states and screenshots.
romm /path/to/config volume Host path to a directory that will hold config.yml.

Generate the auth secret now so you don't forget:

openssl rand -hex 32
# -> 03a054b6ca27e0107c5eed552ea66becd9f3a2a8a91e7595cd462a593f9ecd09

2. Start the stack

From the directory containing your docker-compose.yml:

docker compose up -d

On the first run Docker will pull rommapp/romm:latest and mariadb:latest, bring up the database, wait for the healthcheck, then bring up the app. Verify everything is running:

docker ps -f name=romm
Docker Compose install
 

3. Create the admin user

Open http://<host>:8080 in a browser. On first start, you'll be redirected to the Setup Wizard. Set an admin username and password (the first user created always gets the Admin role), then log in.

Next steps