Skip to content

Synology

Looking for an opinionated guide?

Marius Bogdan Lixandru maintains Synology guides for both MariaDB and Postgres:

For any other setup, follow the steps below.

Prerequisites

  • A Synology NAS with Container Manager (DSM 7.2+) or the legacy Docker package
  • SSH or a task that lets you run shell commands on the NAS
  • Basic comfort with Docker Compose

1. Create folders

Data is split across a few paths. Create them once over SSH:

ROM library

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

The platform folder names inside roms/ have to match the expected naming (see Folder Structure).

User uploads + config

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

Docker volumes for the app itself

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. Create a bridge network

The app and MariaDB need to reach each other by container name. Create a Docker bridge named rommbridge: guide here.

3. Generate the auth secret

openssl rand -hex 32
# -> 03a054b6ca27e0107c5eed552ea66bacd9f3a2a8a91e7595cd462a593f9ecd09

Keep the output. It becomes ROMM_AUTH_SECRET_KEY in your compose file. Don't lose it, because rotating invalidates every session and invite link.

4. Set up metadata provider credentials

Set these up before the first scan (see Metadata Providers).

5. Docker Compose

This compose file is adapted for Synology. It exposes MariaDB on port 3309 (to avoid colliding with Synology's built-in MariaDB) and uses a simplified healthcheck:

docker-compose.yml

`yaml 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
            interval: 10s
            timeout: 5s
            retries: 5

`

Replace placeholder passwords, API keys, and ROMM_AUTH_SECRET_KEY with your own before starting.

6. Launch

From the directory holding your compose file:

sudo docker compose up -d

The first start takes a few minutes while MariaDB initialises, migrations run, and resources get seeded. Tail the logs:

sudo docker compose logs -f

Once startup reports it's listening, open http://<nas-ip>:7676 in a browser. The Setup Wizard walks you through creating the first admin.

Notes

  • Permissions: make sure the UID/GID in your compose file has read-write on every host path you mounted. Synology's default docker user is often 1024:100, and the apps user is 568. Pick one and be consistent.
  • HTTPS: put Synology's built-in reverse proxy (Control Panel → Login Portal → Advanced → Reverse Proxy) in front, or use the Reverse Proxy recipes.
  • Back up /volume1/docker/romm and your DB volume before upgrading versions (see Backup & Restore).

Troubleshooting

Common Synology problems:

  • "Page not found" on first open: DSM hit it before first-run init finished. Wait until docker compose logs -f stops printing startup output.
  • Database connection errors: check the MariaDB container is healthy (docker ps → status healthy), and that DB_HOST matches the MariaDB service name in compose.
  • Permission errors on assets/resources folders: verify the UID/GID in the compose matches the owner of those host paths on the NAS (ls -la /volume1/data/media/games/).

More Synology-specific problems are covered in Synology Troubleshooting.

Contributing

Originally adapted from ChopFoo's guide. Suggestions welcome via PR.