RoonServer can run in Docker using the official RoonServer image from GitHub Container Registry. This is the recommended containerized setup for Linux, NAS devices, home servers, and other systems where Docker provides a practical way to run and maintain RoonServer.

If you are already comfortable with Docker, you can find the image, setup details, and configuration tools here:

GitHub repository: github.com/RoonLabs/roon-docker
Configuration generator: roonlabs.github.io/roon-docker/

The rest of this article explains the setup in more detail, including requirements, key terminology, installation guides, etc..

Requirements

Before setting up RoonServer in Docker, confirm that your system meets these requirements:

• x86_64 / amd64 processor. ARM is not supported.

• 4 GB RAM minimum.

• SSD storage is strongly recommended for the Roon database to get the optimal experience.

• Docker Engine 20.10 or later, or an equivalent container runtime on your platform.

• Host networking mode. Roon relies on multicast and SSDP for device discovery. Bridged networking will prevent this from working correctly.

Basic Docker terminology

This section explains the Docker terms used throughout the setup guides. These terms are also useful if you ever need to contact Support for help.

Docker

Docker is a technology that gives a way to run applications inside self-contained, isolated environments called containers.

This means you don't install RoonServer the traditional way (downloading a package, installing its dependencies, hoping nothing on your OS conflicts with it). Instead, Docker pulls down a single pre-built bundle that already contains everything it needs to run RoonServer.

Image / Docker Image

An image is a read-only template that contains everything that is needed to run RoonServer.

Think of the image as a recipe and the container as the finished, running meal. Docker downloads the image once, then uses it to create your container. The same image can be used to recreate the container any number of times.

Container / Docker Container

A container is the live running copy of RoonServer that Docker creates from the image

You can stop, start, restart, or update the container without deleting your Roon database, as long as your Roon data is stored in a persistent host folder.

If the image is the recipe, the container is the meal as you're eating it. Containers are designed to be disposable — you can stop, restart, delete, or recreate them freely. Anything you want to keep across those operations (your Roon database, backups) needs to live outside the container, on a folder you've mapped in. See Volume mapping below.

Volume mapping

A volume mapping connects a real folder on the host machine – your NAS or Linux system – to a folder inside the container.

This matters because the container is replaceable. When you update, delete, or recreate the container, Docker can throw away the old container and create a fresh one from the image. Anything stored only inside the old container can be lost.

A folder on the host machine is different. It lives on the actual disk and stays there until you delete it.

A volume mapping is the bridge between the two. It lets RoonServer write to a folder inside the container, while Docker saves the data in a real folder on the host machine.

Example:

1. `/share/RoonServer:/Roon`

The left side (before : ) is the real folder on the host machine:

1. `/share/RoonServer`

The right side (after : ) is the folder RoonServer sees inside the container:

1. `/Roon`

So when RoonServer writes data to `/Roon`, Docker stores that data in `/share/RoonServer` on the host machine.

Host networking

Host networking lets the container share the host machine's network connection, instead of being put on its own small private network.

This matters because RoonServer has to be on the same network as the rest of your gear to find your audio devices (DACs, streamers, AirPlay endpoints, etc.) and to be reachable by your Roon Remote apps.

With Docker's default – a private network just for the container – those discovery announcements can't reach the rest of your home network, so RoonServer can't see your audio devices and Roon Remote can't see RoonServer.

With host networking on, RoonServer appears on your home network just like the host machine itself does, and discovery works.

Environment variable

An environment variable is a named setting passed to the container when it starts.

RoonServer uses these for things like timezone, release branch, and many others:
Example

Compose file / Docker Compose

It is a single configuration file that tells Docker how to create and run the container. It usually has a .yml or .yaml extension and is commonly named docker-compose.yml.

For RoonServer, this file can include the Docker image, folder mappings, network mode, restart behavior, timezone, release branch, and optional device access etc

To make this easier, we provide the RoonServer Docker Configuration Generator:

https://roonlabs.github.io/roon-docker/

The generator lets you select the needed options instead of writing the Compose file by hand.

Note: the generated volume mappings are our best effort. Your setup may be different because we cannot know where your Roon database, music library, or backups are stored. Always review the generated folder paths before using the file.

Volume mappings

RoonServer uses three main storage locations:

Release branches

Two release branches are available:

• production - stable releases. This is the default and does not require configuration in the environment variables.

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

To select the Early Access branch, set the ROON_INSTALL_BRANCH environment variable in your container configuration:

ROON_INSTALL_BRANCH=earlyaccess

Switching channels takes effect on the next container restart.

Warning: Early Access builds may include database changes incompatible with Production, usually noted in the release notes. Please create a fresh backup before switching branches. Be especially careful if switching from Early Access to Production, as the Production branch may not be able to read an Early Access database.

Installation guides