This guide explains how to run the official Roon Server Docker image on a Synology NAS. The setup process depends on your DSM (DiskStation Manager) version.

Useful Links:

• GitHub repository: https://github.com/RoonLabs/roon-docker

• Configuration generator: https://roonlabs.github.io/roon-docker/

Before you begin

Make sure your Synology NAS has:

• Container Manager (for DSM 7.2 or later) OR the legacy Docker app (for DSM 7.1 and older) installed from the Package Center.

• x86_64 / amd64 processor. ARM is not supported.

• 4 GB RAM minimum.

• Roon Remote devices on the same local network as the NAS.

Note: We strongly recommend storing the Roon database on SSD-backed storage for optimal performance. On Synology, this usually means placing your Roon database on an SSD volume (e.g., /volume2), keeping your spinning disks for music and backups.

Step 1: Installing Container Manager

When installing Synology Container Manager from the Package Center, accept all the defaults.

Note: This creates a new top-level docker shared folder. For optimal performance, ensure this docker shared folder is located on your SSD volume. If it was created on a spinning disk, you can easily move it to your SSD volume via Control Panel > Shared Folder.

Step 2: Creating the Folder Structure that Docker will use for Roon

To avoid "Access Denied" or permission errors, Docker needs the host folders to exist before deploying the container. Open File Station on your NAS and create the following structure:

1. Create the main folder: Open your docker shared folder and create a new folder called RoonOnDocker. This folder will hold your Compose configuration file.

2. Create the database subfolder: Inside this folder, create a subfolder named Roon. Your absolute path will look something like /volume1/docker/RoonOnDocker/Roon or /volume2/docker/RoonOnDocker/Roon, depending on where your SSD is located.

3. Music Folder: If you do not already have a dedicated shared folder for your music collection, create one now (e.g., /volume1/Music).

4. Roon Backups Folder: Create a dedicated shared folder for your new Docker setup (e.g., /volume1/roon-backups).

   • Note for migrating users: To restore your database in Docker, you will need a recent backup from your native app. You have three options to handle this:

     • Option A (Copy manually): Create a final backup in your native app's existing backup folder. Then, use File Station to copy that backup into this newly created /volume1/roon-backups folder.

     • Option B (Reuse existing folder): Skip creating a new backup folder entirely. During the Docker setup, simply map the container's /RoonBackups path to the existing native Roon backup folder on your NAS.

     • Option C (Direct backup via permissions): If you want the native app to write directly to this new folder before you shut it down, you must grant it permissions. In File Station, right-click the new backup share, click Edit > Permissions, select System Internal User from the dropdown, check Read/Write for RoonServer, and hit Save.
       
       

     • Important: Regardless of the method you choose, do not create your final backup yet! Please read the Migrating from an Existing Installation section at the bottom of this guide first, as you MUST disable your watched folders before backing up to avoid losing your history.

Method 1: DSM 7.2 or later (Using Container Manager Projects)

Synology Container Manager (introduced in DSM 7.2) supports Docker Compose through "Projects". This is the recommended setup method because the configuration generator creates the exact Compose file you need.

1. Open the Roon Docker Configuration Generator.

2. Select Synology as your platform.

3. Enter your timezone and the paths to the folders you created in File Station. Pay close attention to the volume numbers! The generator defaults to /volume1. If your docker folder is on /volume2, make sure to update the Roon data path accordingly (e.g., /volume2/docker/RoonOnDocker/).

4. Copy the generated Docker Compose output.

5. Open Container Manager on your NAS.

6. Go to the Project tab and click Create.

7. Give the project a name, for example roonserver.

8. Set the Path to the main RoonOnDocker folder you created earlier inside the docker share.

9. Change the Source to Create docker-compose.yml and paste the generated Compose YAML into the text field.

10. Review the volume paths carefully to ensure they match your NAS structure perfectly.

11. Click Next (skip the Web Portal Settings screen), then Done to deploy.
    
    

Please note: The initial download of the image and creation of the container will take some time. Please wait 5-10 minutes before trying to connect.

Method 2: DSM 7.1 or older (Using the legacy Docker app)

If you are running an older version of DSM, you must use the standard "Docker" app and configure the container manually via the graphical interface.

1. Open the Docker app on your Synology NAS.

2. Go to the Image tab, click Add, and choose Add From URL.

3. Enter https://ghcr.io/roonlabs/roonserver:latest (leave the Hub Page blank) and click Add. Wait for the image to download.

4. Once downloaded, select the image and click Launch.

5. Network: It is critical to select "Use the same network as Docker Host" (this is Synology's term for Host Networking).

6. Advanced Settings / Volume: Click Add Folder to map your Synology host folders to the container paths:

   • Map your newly created Roon folder to /Roon (Read/Write, SSD strongly recommended).

   • Map your Music folder to /Music (Read-Only recommended).

   • Map your newly created Backup folder to /RoonBackups (Read/Write).

7. Environment: Add a new variable named TZ and set the value to your timezone (e.g., America/New_York).

8. Check the box to Enable auto-restart.

9. Click Apply or Done to start the container.

Storage mappings

Whether you use Compose or the manual method, your setup should map these three main Roon folders:

Only edit the Synology host paths (the path on the left side of the colon). Do not change /Roon, /Music, or /RoonBackups inside the container unless you have a specific reason.

Required settings

Host networking is absolutely required for Roon discovery. Without it, Roon Remote may not find the server. Also, ensure your container is set to restart automatically after a NAS reboot (e.g., restart: unless-stopped).

Release Branches

Two release branches are available:

• production — stable releases. This is the default.

• earlyaccess — pre-release builds, updated more frequently.

If you are using Method 1 (Compose), you can set this via the configuration generator. If using Method 2, add an environment variable ROON_INSTALL_BRANCH with the value earlyaccess. Switching channels takes effect on the next container restart.

Migrating from an Existing Installation

If you are moving an existing Synology Roon installation into Docker, follow these steps carefully to ensure a smooth transition.

Note: If you are migrating from a completely different system, simply create a backup on your old system, copy it to the /roon-backups folder on your Synology NAS)

Important: You must complete Step 1 below before creating your final backup!

1. In your current native Roon installation, disable all watched storage folders (Settings > Storage). This is crucial to avoid path conflicts and duplicate scanning after migration. If you skip this, all files will be treated as new music, and you will lose all edits and listening history.
   

2. Create a backup (Settings > Backups > Back Up Now) and save it to the new /roon-backups folder you created and permissioned in Step 2.
   

   Note: This process may take time depending on your library size.

3. Stop the old native Roon app on your Synology NAS package center.

4. Start your new Docker container as described in Method 1 or 2, and wait 5-10 minutes for it to fully initialize.

5. Open the Roon desktop application on your computer. It will likely say "Waiting for Roon Server". Click Select a different Roon Server and connect to your new Docker-based install (look for the green "Ready" icon). 

6. Look closely at the bottom of the screen and click the Restore a backup link. Follow the prompts to restore the backup you just created.

7. After the restore process finishes, you will be prompted to relaunch. Be patient—it may seem stuck or show red/green server statuses. If it cycles endlessly, restart the desktop application until you see the Login screen.

8. Log in via your web browser. Once returned to the Roon app, click Unauthorize for your old Roon Server.

9. You will now see a screen showing you have nothing in your collection. Do not worry! Go to Settings > Storage, find your previously disabled storage location, click the three dots, and select Enable.

10. A notice will appear saying the drive is not available. Click edit this folder, select Browse..., find your /Music folder (the container path), click Select this folder, and save. Roon will now begin scanning your library.

Common issues

Roon Remote cannot find Roon Server / "Waiting for Roon Server" When you first start the container, it takes time to initialize. Wait 5-10 minutes. If it still doesn't appear, confirm that "Host networking" (or "Use the same network as Docker Host") is enabled.

Access Denied / Permission problems If the container fails to start or deploy, Docker likely cannot create the folders. Make sure you manually create the host folders in File Station before starting the container.

Formatting errors when pasting YAML If the copy-paste method fails or produces formatting errors (e.g., "Make sure you configure all the necessary settings first") in Container Manager, you can download the docker-compose.yml file directly from the Roon Docker Configuration Generator. During the project creation step, change the Source to Upload docker-compose.yml and select your downloaded file instead of Create docker-compose.yml.

Performance is poor Confirm that the /Roon mapping points to SSD-backed storage. The Roon database should not live on a spinning disk.

Music folder is missing Confirm that the Synology host folder is mapped to /Music inside the container. In Roon's storage settings, use the container path (/Music), not the Synology host path (/volume1/Music).