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 Screenscraper account (optional)
  • Your ROMs organized in the correct folder structure

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.

IGDB and Screenscraper API Keys

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

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
    • MARIADB_ROOT_PASSWORD: Sets the root password of the database. Use a unique and secure password (use a password generator for simplicity)
    • MARIADB_DATABASE: Sets the database name for RomM. This can be modified - but it's not necessary
    • MARIADB_USER: User to connect to the database with. This can be modified - but it's not necessary
    • MARIADB_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. Run the following command in a terminal and save the output to the ROMM_AUTH_SECRET_KEY environment variable: 
    openssl rand -hex 32
    It should look something like this: 
    03a054b6ca27e0107c5eed552ea66becd9f3a2a8a91e7595cd462a593f9ecd09
  5. Add your metadata sources API keys:
    • IGDB: IGDB_CLIENT_ID and IGDB_CLIENT_SECRET
    • SCREENSCRAPER: SCREENSCRAPER_USER and SCREENSCRAPER_PASSWORD
  6. 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 (usually the parent folder of the roms folder)
    • /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

  7. 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
      - SCREENSCRAPER_USER= # Use your ScreenScraper username and password
      - SCREENSCRAPER_PASSWORD= # https://docs.romm.app/latest/Getting-Started/Generate-API-Keys/#screenscraper
      - 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

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

  9. 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
 
  1. Run docker ps -f name=romm to verify that the containers are running
  2. Open a web browser and navigate to http://localhost:80, where you should be greeted with the RomM setup page
  3. Go through the setup wizard, setting your admin username and password
  4. Log in with the credentials you set in the setup flow

Configure

Importing your ROMs via scanner

This method is generally the fastest and recommended for first time setup. You need your library properly mounted as a container volume:

  1. Log into RomM with your user credentials
  2. Click the Scan button in the sidebar
  3. Select the metadata providers you want to fetch metadata from
  4. 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
  5. 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!

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. Click the Upload button in the sidebar
  3. Select the platform, then click + ADD 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