Skip to content

Synology Setup

External Written Guides

While you can follow the below guide, Marius Bogdan Lixandru has written excellent guides which focus on Synology infrastructure and with support for both MariaDB and PostGresSQL:

We suggest following the above guides if they fit your setup, and the guide below is available for all other use cases.

Prerequisites

This guide assumes you're familiar with Docker and have basic knowledge of server management. You'll need:

  • A Synology NAS or similar server
  • Docker installed
  • Basic command line knowledge
  • Access to manage network settings

Setup Process

1. Folder Structure Setup

ROM Storage Folders

Create the following directory structure for game assets and configuration:

mkdir -p /volume1/data/media/games/assets
mkdir -p /volume1/data/media/games/config

ROM Library Structure

RomM requires a very specific folder structure for rom files:

mkdir -p /volume1/data/media/games/library/roms
mkdir -p /volume1/data/media/games/library/bios

Note: For supported platforms and their specific folder names, refer to the official RomM wiki.

Docker Data Folders

Create these folders for project and container data:

mkdir -p /volume1/docker/romm-project/
mkdir -p /volume1/docker/romm/resources
mkdir -p /volume1/docker/romm/redis-data
mkdir -p /volume1/docker/mariadb-romm

2. Network Bridge Setup

Create a new network bridge named rommbridge following standard Docker networking practices. You can use this guide for reference.

3. Key Generation

Authentication Key

Generate your authentication key using:

openssl rand -hex 32
> 03a054b6ca27e0107c5eed552ea66bacd9f3a2a8a91e7595cd462a593f9ecd09

Save the output - you'll need it for the ROMM_AUTH_SECRET_KEY in your configuration.

API Integration Setup

Follow the dedicated wiki page for API key generation to set up your API keys.

4. MariaDB Configuration

Important

  • This guide uses a dedicated MariaDB container for RomM, but you can use an existing MariaDB instance if preferred
  • We're using MariaDB version 10.7 for compatibility
  • The container uses port 3306 internally, mapped to 3309 externally
  • A simplified health check is implemented for stability

5. Docker Compose Configuration

Create a docker-compose.yml file with the following content:

Example Docker Compose 
version: "3"

volumes:
    mysql_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:
            - /volume1/docker/romm/resources:/romm/resources
            - /volume1/docker/romm/redis-data:/redis-data
            - /volume1/data/media/games/library:/romm/library
            - /volume1/data/media/games/assets:/romm/assets
            - /volume1/data/media/games/config:/romm/config
        ports:
            - 7676:8080
        network_mode: rommbridge
        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=
        ports:
            - 3309:3306
        network_mode: rommbridge
        volumes:
            - /volume1/docker/mariadb-romm:/var/lib/mysql
        healthcheck:
            test: [CMD, healthcheck.sh, --connect, --innodb_initialized]
            start_period: 30s
            start_interval: 10s
            interval: 10s
            timeout: 5s
            retries: 5

6. Initial Launch

  1. Start the containers using Docker Compose
  2. Be patient! The container can take a few minutes to setup on first launch
  3. Monitor progress through container logs
  4. Access RomM through your browser at http://your-server-ip:7676

Important

  • Replace placeholder values (UIDs, GIDs, passwords, API keys) with your own
  • Ensure proper permissions on all created directories
  • Back up your configuration after successful setup
  • Monitor logs during initial startup for any errors

Troubleshooting

  • If the web interface shows "page not found," wait for initial setup to complete
  • For database connection issues, verify MariaDB container health status
  • Check logs for both containers if experiencing issues
  • Ensure all volumes are properly mounted with correct permissions

Contributing

This guide is an abridged version of ChopFoo's original guide. If you have any suggestions or improvements, please submit a pull request to the RomM wiki.