Until now, running the Roon Server software directly on the NAS was particularly easy for owners of a QNAP model. However, since April 27, 2026, the traditional installation via the App Center no longer works. The reason is new minimum requirements for the server operating system starting with software version Roon 2.65, Roon 2.66 or higher. Frustrating for many: after a successful update, the Roon Server simply no longer starts on the QTS operating system, completely without warning.
The solution offered by Roonlabs is a so-called container. This means the Roon Server no longer runs directly on the QTS operating system, but instead gets its own folder with the necessary system files and is subsequently launched by an app that manages such container applications. The built-in solution on QNAP NAS is called Container Station.
The following guide shows you step-by-step how to configure Roon 2.65 and 2.66 on QNAP NAS and get it running under Container Station. This does not apply to users of other systems; in particular, for users of MacOS 10/11 and Synology DSM7.1 or earlier, other alternatives are available, which we will cover in separate guides.
What is a Docker Container?
A Docker container is a folder on a computer in which applications or apps run independently and are not installed on the operating system.
You should be familiar with a few terms from the Docker world:
- Docker Image – the blueprint that controls the assembly of the container during installation. It contains user settings such as file paths, time zone, and hardware usage settings, and therefore needs to be individualized.
- Docker Container – the folder installed on the computer where the actual application runs. It also contains the system requirements necessary for communication between the application and the operating system.
- Docker Host – the application installed on the computer that controls the setup/execution/starting/stopping of containers. Popular applications for many platforms include Portainer or Docker Engine; QNAP users are more familiar with Container Station, and Synology owners with Container Manager, also called Docker App in earlier DSM versions.
- Docker Hub – a central library to find pre-built container images and download them according to a blueprint. The Roon Container is published on GitHub, a very large library.
Containers can have their own environment, such as network, folders, and storage management, on the computer on which they run. Therefore, when configuring and installing an application in a container, it is important to define the interfaces for the individual combination. Otherwise, there is a risk that remote devices may no longer be able to communicate with the server app, or the latter may not be able to access folders with music files.
Why does Roon Server run in a Docker Container on older systems?
Although the software builds upon the existing operating system and does not bring its own (unlike a full virtual machine that emulates an entire operating system), the container can include its own code, runtime environment, system tools, and libraries that are urgently needed. This ensures that the software also works on operating systems for which it was not programmed. This is practical for software developers because the application then behaves similarly on every operating system and does not have to be adapted and tested countless times.
The Roon Docker Container leverages this trick, enabling Roon 2.65 and 2.66 to run even on outdated, incompatible operating systems like QTS 5.x.
Step-by-step guide to Docker Container installation on QNAP servers
Step 1: Back up in old Roon 2.64 and uninstall
A manual backup in Roon to a dedicated folder somewhere on the NAS is highly recommended to later restore the database, playlists, album changes, etc., after the migration. Ideally, all local storage folders should be deactivated/disabled.
Afterward, the existing Roon app in the App Center should be completely uninstalled, and all components removed from the NAS.
Step 2: Install Container Station from the App Center
The management software for applications in containers must first be installed and running. You can find it in the App Center under Utilities:
Step 3: Configure individual Roon Docker
Now, you need to generate a version of the Roon Server that runs on your NAS. The corresponding Docker configurator is available on GitHub. It requires basic knowledge of setting up shared paths on the respective system:
Roon Server Docker Configurator on GitHub
This is what the Docker Configurator interface looks like, with important areas to adjust highlighted:
The following settings must be made for operation on QNAP, or the paths must be manually adjusted:
Platform > QNAP (highlighted in orange)
Roon Server Release Branch > Production
“VOLUMES“
Here, a redirection for accessing specific data folders is defined so that the Roon application in the container can see and work with them. It is important that each path is prefixed with “/share”, and volume names have no place in the path; instead, the top-level folder is named afterward, in this case “Container”:
/share/Container/roon
This path specification tells Container Station to unpack the application in the container into its own path named “Container” in the subfolder “roon” and start it. ATTENTION: Roon also stores its own database in this folder, which it needs to access very often and very quickly. It is therefore strongly recommended to direct this system path to SSD storage, not a magnetic hard drive/HDD. If the “Container” folder is already on a magnetic disk, you can create a new folder on an SSD volume as desired and enter it here, ideally with a subfolder “roon”. If no electronic storage is installed at all, it is recommended to redirect to an external USB flash drive, which must be fast. Then the path would be, for example, if the external drive is called “MySSD” and must be formatted in EXT4 format:
/share/MySSD/roon
Next, we continue with the reference to the local music collection under “/Music”. For example, if the music is in the main folder “Multimedia” and the subfolder “Music” (highlighted in red in the screenshot):
/share/Multimedia/Music
Afterward, the path to the database update made in Step 1 is still needed, for example:
/share/Container/roon-backups
Roon will also store future backups in this folder, which is why a local folder is better. If you already have a backup on an external USB stick, you can copy it to the backup folder that Roon will see in the future via File Station.
The other options should be checked, such as the time zone, and the activation/deactivation of local audio outputs like USB audio and HDMI.
Step 4: Download Docker Compose as .YML
If all settings are correct, you can download a .YML file using the small download button in the GitHub configurator. It contains the complete instructions for installing the container and application on the NAS.
Step 5: Pull container and generate application in Container Station
In the Container Station app on the QNAP NAS, select the “Application” section (orange) and then the “Create” function (highlighted in red):
A window for creating an application will open. You can upload the .YML file from your local computer or a folder on the NAS using the “Upload” function. Alternatively, the YAML code generated in the last step can simply be copied into the text field. Then confirm with “Create”. Container Station should now perform the setup, download the application data, and start Roon directly in the container. You can check this in the “Container” view:
Error messages may appear in the black text field, for example, if the used folders cannot be accessed, or if something went wrong during installation. The fact that the container itself shows green light for operation does not mean that the Roon Server application is actually running. To check, it is recommended to look at the Container Station overview page. The RAM usage should have increased significantly, and roonserver app´s share of RAM usage appearing in Top 5 under memory utilization.
Step 6: Connect Roon Remote and restore backup
Start your tablet, computer, or smartphone with the Roon Remote app. The Remote app will not automatically find the new Roon Server, which is what the “Connect to another Roon Server” function is for. Usually, the new Roon Server will then also ask for a re-login with username and password.
Afterward, you should restore the last backup of the internal Roon database. There is a dedicated function for this under “Settings > Backups”. It is important that the backup data is actually in the folder that we shared with the container in Step 3 under “Backups”.
Once the backup is restored, take a quick look at the “Storages” settings in Roon. The new music path shared with the container should now be visible, usually not yet activated. It is recommended to delete the older folders that Roon Server can no longer find before activating this folder. This makes it easier for Roon Server to recognize albums. In some exceptional cases, however, it may happen that albums are not recognized.
Good luck!
More detailed instructions for installing Roon Server in a Docker Container from Roonlabs (English)
Roonlabs has published a slightly different guide for setting up Roon Server in a Docker Container on QNAP at the following link:
Roonlabs Guide for Roon Docker Container under QNAP QTS
It contains further details. If the setup does not work, we recommend visiting the Roon Community Forum, providing the individual error messages produced by Container Station.
