This guide explains how to run the official Roon Server Docker image on TrueNAS SCALE (specifically version 24.10 "Electric Eel" or later). TrueNAS 24.10 and later features a native Docker-based runtime, and custom applications are deployed using Docker Compose YAML configuration through the Apps interface.

Useful Links:

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

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

Before you begin

Make sure your TrueNAS server has:

• TrueNAS SCALE 24.10 (Electric Eel) or newer.

• x86_64 / amd64 processor. ARM is not supported.

• 4 GB RAM minimum.

• Roon Remote devices on the same local network as the TrueNAS system.

Create ZFS Datasets: Before generating your configuration, create a dedicated ZFS dataset for each volume Roon will mount. Per-app datasets give you independent snapshots and cleaner migrations later. Go to Datasets, select your pool, click Add Dataset, and name each one. For example, on a pool called Main:

• Main/Roon

• Main/Music

• Main/RoonBackups

Note: We strongly recommend storing the Roon database on SSD-backed storage for optimal performance. The dataset used for your /Roon Volume should live on an SSD pool.

Deploy the container (Install via YAML)

1. Open the Roon Docker Configuration Generator.

2. Select TrueNAS as your platform.
   

(Note: The generator automatically adds user: "0:0" to the YAML output. This overrides TrueNAS Apps' default non-root UID, under which Roon's startup script cannot execute).

1. Enter your timezone and the full host paths to the datasets you created (e.g., /mnt/Main/Roon).
   

2. Copy the generated Docker Compose output.

3. In the TrueNAS web interface, go to Apps.

4. Click Discover Apps.

5. Click the ⋮ overflow menu next to the blue Custom App button and select Install via YAML.
   

Warning: Clicking the Custom App button directly opens a wizard form. That is a different install path and not what we want).

1. Provide an application name, for example roonserver.
   

2. Paste the Docker Compose YAML from the generator into the Custom Config field.

3. Double-check the host paths on the left side of each colon (:) to ensure they perfectly match the datasets you created.

4. Click Save. TrueNAS will pull the image and start the container based on your YAML configuration.

⚠️ Important Path Warning

TrueNAS paths are strictly case-sensitive. /mnt/Main/ and /mnt/main/ are different paths. Typos can produce Permission denied errors because Docker may silently create a directory on the boot-pool's noexec filesystem instead of your actual storage pool. Double-check capitalization against the exact pool name shown in Storage > Pools.

Tip: Third-party container managers like Portainer or Dockge also work well with TrueNAS 24.10+. They can be convenient for complex setups, but for a first-time deployment, the built-in Apps > Install via YAML path is safer because it keeps the setup inside the native TrueNAS flow

Storage mappings

Required settings

• Network Type: The generator sets network_mode: host. Host networking is absolutely required for Roon discovery. Without it, Roon Remote may not find the server, and the server may not discover audio endpoints on your network.

Release Branches

Two release branches are available:

• production — stable releases. This is the default.

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

You can set this via the configuration generator before copying your YAML. Switching channels takes effect on the next container restart.

Migrating from a Native Installation

If you are moving an existing Roon installation into Docker, use Roon's built-in backup and restore:

1. In your current native Roon installation, disable all watched storage folders (Settings > Storage). This avoids path conflicts after migration.

2. Create a backup (Settings > Backups > Back Up Now).

3. Copy the backup to a location accessible from your new TrueNAS dataset mapping (e.g., your Main/RoonBackups dataset).

4. Start the new Docker container. On first launch, it will prompt you to set up or restore.

5. Choose Restore and point it to the backup.

6. Once the restore is complete, edit your music folders' paths with the paths as they appear inside the Docker container (i.e., /Music).

After installation

After the container starts:

1. Confirm the application is running in the TrueNAS Apps interface.

2. Open Roon on your phone, tablet, or computer.

3. Make sure your Roon Remote device is on the same local network as the TrueNAS system.

4. Select the Roon Server running on TrueNAS.

5. Set up a new Roon Server or restore from backup.

6. Go to Settings > Storage and confirm your music folder is visible.

Common issues

Permission denied errors / App fails to deploy. Confirm you have not made a typo in your host paths. Remember that TrueNAS paths are case-sensitive. Verify that the generator is included user: "0:0" in the YAML.

Roon Remote cannot find Roon Server Confirm that host networking is active and that your Roon Remote device is on the same local network as the TrueNAS system.

Performance is poor Confirm that the /Roon mapping points to an SSD-backed ZFS pool. For the best experience, the Roon database should not live on a spinning disk array.