Skip to content

Quick Start Guide

This quick start guide will help you get a RomM instance up and running. It is split into 3 parts:

  • Prepare
  • Build
  • Configure

Prepare

This guide will assume that you already have the following done, if not - stop here and come back when you do.

  • Docker and Docker Compose installed
  • A Twitch account (optional)
    • 2-factor authentication set up on your Twitch account
    • This is required to get a developer account and an IGDB key
  • A MobyGames account (optional)
  • Your ROMs organized in the correct format

Warning

Not setting up RomM with a metadata API will work for basic operation but can cause issues with, for instance, the Playnite plugin. It is recommended to setup IGDB API keys to avoid issues during setup.

Twitch and MobyGames API Keys

Head over to API key docs to get your Twitch and/or MobyGames keys, then come back here

Generating Authentication Keys

This step will generate a key that is used in the authorization of RomM. Without this, you will be unable to log in and use the platform

Run the following command in a terminal:

openssl rand -hex 32

Then copy the output and save it to the ROMM_AUTH_SECRET_KEY variable in the docker-compose file. It should look like this:

~$: openssl rand -hex 32
03a054b6ca27e0107c5eed552ea66becd9f3a2a8a91e7595cd462a593f9ecd09

Build

Now that we have everything gathered, we can begin getting your instance set up!

  1. Download a copy of the latest docker-compose.example.yml file from GitHub
  2. Edit the file and modify the following values to configure the database
    • MYSQL_ROOT_PASSWORD: Sets the root password of the database. Use a unique and secure password (use a password generator for simplicity)
    • MYSQL_DATABASE: Sets the database name for RomM. This can be modified - but it's not necessary
    • MYSQL_USER: User to connect to the database with. This can be modified - but it's not necessary
    • MYSQL_PASSWORD: Password for the user to connect to the database with. Use a unique and secure password (use a password generator for simplicity)
  3. Modify the following values in the environment to configure the application. -- Other values can be changed, but should not be done unless you know what you are doing, and are outside the scope of this guide
    • DB_NAME: Name of the database set in the database section
    • DB_USER: Name of the user to connect to the database
    • DB_PASSWD: Password of the user to connect to the database
  4. Modify the following values in the volumes to configure the application
    • /path/to/library: Path to the directory where your rom files will be stored
    • /path/to/assets: Path to the directory where you will store your saves, etc
    • /path/to/config: Path to the directory where you will store the config.yml

  5. Save the file as docker-compose.yml instead of docker-compose.example.yml. It should look something like this:

    Example Docker Compose 
    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`
            - IGDB_CLIENT_ID= # Generate an ID and SECRET in IGDB
            - IGDB_CLIENT_SECRET= # https://api-docs.igdb.com/#account-creation
            - MOBYGAMES_API_KEY= # https://www.mobygames.com/info/api/
            - STEAMGRIDDB_API_KEY= # https://github.com/rommapp/romm/wiki/Generate-API-Keys#steamgriddb
        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

  6. Open the terminal and navigate to the directory containing the docker-compose file

  7. Run docker compose up -d to kick off the docker pull. You will see it pull the container and set up the volumes and network:
    RomM docker compose install
     
  8. Run docker ps -f name=romm to verify that the containers are running
  9. Open a web browser and navigate to http://localhost:8080, where you should be greeted with the RomM setup page
  10. Go through the setup wizard, setting your admin username and password
  11. Log in with the credentials you set in the setup flow

Configure

Now that the container is running, we will configure it by importing your ROMs

Uploading Your ROMs via Web Interface

This method is certainly viable, but not recommended if you have a lot of ROMs and/or multiple platforms. It is good for adding after the fact as your collection grows, but wouldn't be recommended for the first set up, nor for multi-file ROMs

  1. Log into RomM with your user credentials
  2. Navigate to Library -> Upload ROMs
  3. Select the platform, then click ADD ROMs and select the ROMs you want to upload in the file selector that appears
  4. Click UPLOAD to begin uploading the ROMs
  5. Repeat for all the roms/platforms you have

upload dialog

Importing Your ROMs via Scanner

This method is generally the fastest and recommended for first time setup

  1. Stop your RomM instance. docker compose down if you are in the terminal and directory containing the docker-compose file, otherwise docker stop romm
  2. Go to the library folder created by RomM, set in the docker-compose file under :/romm/library and create a folder named roms
  3. Copy your platform folders/rom files into the roms folder you created
  4. Start the RomM instance back up. docker compose up -d if you are in the terminal and directory containing the docker-compose file, otherwise docker start romm
  5. Log into RomM with your user credentials
  6. Navigate to Library -> Scan
  7. The system will now begin scanning the rom files and applying metadata to them. You can click on any of the items that it has tagged to see the metadata it pulled without having to stop the scan
  8. After the scan completes, click the RomM logo to go back to the main screen. You should see the platforms and recent games it has scanned. You are now ready to rock and RomM! ```