How to migrate from Roon on NAS to the Container Manager (Docker) version on Synology

[DDPS]

Since I am the author of A Roon on (Synology) NAS Primer and @gtunes is the author of Walkthrough : Roon in a Docker container on Synology DSM 7 he and I figured it was worth collaborating on this, so many thanks to him, as he has vastly more experience with running Roon via Docker than I do.

Before I proceed, I want to offer many thanks to @Stephen the work that led to the creation of this guide:

Installing RoonServer on Synology with Docker

All that said, here are a series of important notes, directions and observations for those who are migrating from @crieke‘s Roon on NAS version in the event you wish to do so. The instructions below will only work on installations of Synology DSM that are capable of running Synology Container Manager, which was introduced in DSM 7.2.

There is something important to acknowledge in everything you read here, and that is the fact that I use a separate Synology top level volume (/volume2) on an SSD for my Roon Database, and all of these instructions assume that your /volume1 is comprised of spinning discs and that your SSD is on another volume like /volume2. If your setup does not resemble this, than this guide may not be for you.

Step 1: Installing Container Manager

When installing Synology Container Manager, accept all the defaults.

This creates a new top level “docker” shared folder. You will not be employing this folder at all in the setup I am about to describe.

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

What we will next is create a new folder on the same (presumably SSD) volume that has your current “RoonOnNAS” folder. We will call this folder “RoonOnDocker”.

In this folder, we will create a subfolder named “Roon”.

Step 3: Setting up your SSD volume

The instructions at Method 1: DSM 7.2 or later (Using Container Manager Projects) don’t specify the following, but in the defaults on RoonServer Docker Configuration Generator, the setting for /Roon will map to /volume1, which is likely not your separate SSD.

So, in File Station, create another folder on your SSD volume that is a peer of your existing RoonOnNAS folder. Call it something like RoonOnDocker. In there, create a subfolder called Roon. Then change your setting in the configurator to point to this folder, e.g.:

/volume2/Roon SSD/RoonOnDocker/Roon

This will create a setting on the right that looks like this (if you have spaces in any of your volume names, like I do, it will add quotes around things):

“/volume2/Roon SSD/RoonOnDocker/Roon:/Roon”

Note that it will still need the Shared Folder to be referenced (in this case Roon SSD) in addition to the subfolders you’ve created.

Step 4: Pre-setting your new backups folder

You probably have a dedicated shared folder where your Roon backups live. On mine, this was a shared folder called RoonBackups. Because most of your old backups will not be useful in your new environment, create a new shared folder for your new backups (this is where the backup you create in step 2 of Migrating from a Native Installation will go).

I called mine RoonDockerBackups. It is also a top-level shared folder off of /volume1.

You must configure this so that RoonOnNAS can write its final backup to this folder: In File Station, select this new share, click the “Edit” button, click on the “Permissions” tab. Then, under the dropdown that defaults to “Local Users,” select “System Internal User.” Scroll down to where you see “RoonServer” and click the “Read/Write” checkbox, then hit “Save.”

A note about the backup process

Please follow steps 1–3 of Migrating from a Native Installation carefully. Note that you have to disable your current watched folder before you create the backup, and note that after you are done, you must stop the RoonOnNAS package. Backups will take time. My Roon database, which is just under 11 GB for a 2.8TB music collection, took about 12 minutes.

When you are in Step 2 of Migrating from a Native Installation, you will be able to save your new backup to the folder we created and set up above rather than “copying them” per Step 4 of that page. Yes, this means you can skip Step 4 of “Migrating from a Native Installation.”

A note about step 5 of the migration processs

Step 5 of “Migrating from a Native Installation” should not read: Start the new Docker container. On first launch, it will prompt you to set up or restore. It should read: “After starting the new Docker container, launch your desktop Roon application. On first launch, it will prompt you to set up or restore.” More on that in Step 7 of this guide, below…

Step 5: Create your “docker-compose.yml” file using RoonServer Docker Configuration Generator

Follow the basic steps for creating the configuration file for your Roon-on-Docker installation. You will use RoonServer Docker Configuration Generator per the instructions at Installing RoonServer on Synology with Docker under the heading “Method 1: DSM 7.2 or later (Using Container Manager Projects)”

Step 6: Create Your Docker “Project” and Get Roon Server Running

In Container Manager, after selecting Create Project and giving it a name (e.g., roonserver), you must select the outer folder (e.g., RoonOnDocker) you created on your SSD volume using the Set Path button.

Once you have copied the docker-compose.yml contents that you created in Step 5 to your computer’s clipboard…

…go back to “Create Project” and switch “Source” from “Upload docker-compose.yml” to “Create docker-compose.yml” which will enable pasting per the instructions.

Next, paste the contents of your clipboard into the little text field as follows:

IMPORTANT — MEGA IMPORTANT — and illustrated above:

Modify this line:

- /volume1/music:/Music

So that it looks like this:

- /volume1/music:/MyMusic

If you really don’t want to use the one or two Roon features that allow you to make modifications to your music collection, append “:ro” to the end of that line to make this directory “read only”:

- /volume1/music:/MyMusic:ro

Skip the “Web Portal Settings” screen - simply hit “Next”

On the last screen, hit “Done.”

Step 7: Connecting Everything Up on the Desktop

Once your Docker container is running, launch your Roon desktop application, which will likely have a screen reporting that it’s Waiting for Roon Server, like this:

Press “Select a different Roon Server” - it should bring you to a place with a green “Ready” icon once your new Docker-based install is ready.

Press "Connect.”

Unfortunately, you may have to quit the application and relaunch it a few times and hit Connect each time until you get to the next part…

Once things are humming, you will get to step 5 of “After installation” (5. Set up a new Roon Server or restore from backup.)

Eventually after you hit connect, you should get a screen that has a “Restore a backup” link at the bottom, almost hidden. Select this.

After that, you will have to hit Relaunch to continue:

This may seem to bring you to a dead-end, so just be patient. You may watch your server status turn red and green for a bit.

If you get into a cycle, just quit and restart the desktop application until you see this screen again:

This time, though, instead of selecting "Restore a backup,” select "Login.”

After you finish logging in via your web browser, there is a button to go back to the Roon desktop application. When you do, you may find the jellyfish spinning. That’s OK. Be patient. After a few minutes, you should get the “You’re already signed in” screen you see below.

Hit “Unauthorize” for your old Roon Server.

Now, you will get the screen showing you have nothing in your collection

DO NOT FRET. The magic happens in the next step.

Go to Settings > Storage, and go to your previously disabled storage location. Press the three dots icon to the right, and select “Enable.”

From there, you will see a notice that the drive is not available, with a link to “edit this folder”.

Click “edit this folder” and then in the dialog box that appears, select “Browse…”

Find “MyMusic” and click on that.

You should see your music folder in there! Hit “Select this folder” then on the next box that appears, hit Save.

Then Roon will begin to scan your music collection just like it does with a normal reboot.

There will be a music location in Settings > Storage called “Music Folder” - use the … menu to set it to “Disabled” - it plays no role in this sort of environment.

Step 8: Loose Ends

1. Double check the location of your automated Roon backups and make sure they are pointing to the new folder you created in Step 4.

2. If you have extensions running, like RoPieee, you will need to re-enable them in your settings.**

3. Other than that, You’re done!

Step 9: A Note on Post-Migration Performance

I’ve added this update after my personal migration experience. When you restore a backup from a Roon on NAS library, everything looks all set in the Roon desktop application - history, tags, metadata, etc., are all there working as before.

BUT.

It appears that Roon needs to do fairly extensive background processing — including
Background Audio Analysis — after the migration. This will be manifest through Roon getting very slow to respond to things like track-to-track transitions, etc.

I don’t know if that is because that part of the underlying software cares about the fact that the internal path representation of each file changes during the migration (e.g., Roon on NAS pointed to
/var/packages/RoonServer/target/roonmnt/music/Non-Classical/Yes/Union/04 - Lift Me Up.flac and after migration to the Docker solution, the internal mapping for said song is /MyMusic/Non-Classical/Yes/Union/04 - Lift Me Up.flac). But it seems like a good possibility.

So, I recommend anyone noticing this slowdown be patient AND to turn on “Scheduled” background audio analysis for 12+ hour chunks for a couple of days. After 2 nights of this for my ~64,000 track library, things settled down. When you notice things settling down, it’s OK to reboot your Roon server and put the setting back to “Unscheduled.”

Appendix: Here is my YAML file, for reference

services:
  roonserver:
    image: ghcr.io/roonlabs/roonserver:latest
    container_name: roonserver
    network_mode: host
    environment:
      - ROON_INSTALL_BRANCH=production
      - TZ=America/New_York
    volumes:
      - "/volume2/Roon SSD/RoonOnDocker/Roon:/Roon"
      - /volume1/music:/MyMusic:ro
      - /volume1/RoonDockerBackups:/RoonBackups
    restart: unless-stopped
    logging:
      driver: local

[Stephen (Stephen Shaw)]

Thanks for putting this together! I can’t take credit for the documentation, but I’ll pass this along to the person taking care of it

[gTunes]

This is really fantastic. It’s a huge contribution to the community. Thank you!!!

[DDPS]

Thank you for YOUR contributions to this, @gTunes!

[SukieInTheGraveyard]

I’m not a NAS user but I do want to thank @DDPS and @gTunes for their excellent contributions. Hopefully this will smooth the transition for a good number of people.

[vadim]

Hello @DDPS,

Thank you for your effort on this. I’ll proceed with updating the documentation, but before I do, could you please clarify a few points:

1. Folder Renaming: What is the purpose of renaming the folder from Music to MyMusic inside the container, and why is this step important?
2. YAML Upload vs. Copy-Paste: I’ve seen reports that direct copy-pasting into the YAML editor doesn’t work for some users due to a bug in the Synology implementation. They’ve had to use the “Upload docker-compose.yml” feature instead. Did you encounter this during your testing?
3. Manual Folder Creation: My research suggests that all subdirectories within the project folder (e.g., the Roon and RoonBackups folders inside RoonOnDocker) must be created manually before deploying. Can you confirm if this is necessary?
4. default docker folder After instalation of the Container Station default docker folder created on the SSD or HDD drive?

I would appreciate your input on these details.

[Arindal]

@vadim

I’ve seen reports that direct copy-pasting into the YAML editor doesn’t work for some users due to a bug in the Synology implementation.

I thought it was a QNAP problem?

Anyways, downloading the .YML file and searching for it in Container Station, was my preferred way to go.

@vadim

After instalation of the Container Station default docker folder created on the SSD or HDD drive?

In my case, this was on HDD, as the primary volume of my machine is HDD. Surprisingly, the docker container ran fine on that one, I just don´t want my spinning discs to permanently move their heads.

[DDPS]

@vadim

• Folder Renaming: What is the purpose of renaming the folder from Music to MyMusic inside the container, and why is this step important?
• YAML Upload vs. Copy-Paste: I’ve seen reports that direct copy-pasting into the YAML editor doesn’t work for some users due to a bug in the Synology implementation. They’ve had to use the “Upload docker-compose.yml” feature instead. Did you encounter this during your testing?
• Manual Folder Creation: My research suggests that all subdirectories within the project folder (e.g., the Roon and RoonBackups folders inside RoonOnDocker) must be created manually before deploying. Can you confirm if this is necessary?
• default docker folder After instalation of the Container Station default docker folder created on the SSD or HDD drive?

1. Folder Renaming: Great question. The container’s built-in “Music Folder” storage area seems to have some logic baked in to associate with a mapped folder called “Music.” The problem is, when trying to use this mapping after restoring from a backup, it scans the user’s music collection as if it’s all-new. After playing around for a bit, @gTunes came up with an idea to use a folder name other than “Music” to avoid any potential of conflicting with the baked-in logic. In theory, pointing my Step 7 to the Music folder — if that was specified in the YAML mapping — should work, but we wanted to avoid messing with any of the built-in logic.
   
   I suggest that having the baked-in “Music Folder” in the package is great for new Roon users, but not a great idea for people migrating. It would be great for the configurator to offer some options on this front if possible, although I know it might be a stretch…

2. No, that was never an issue for me. The default drop-down behavior, however, assumes that a YAML file is already in place in said directory, so you could ask people to create the file and put it in place before creating the project, and then all they would have to do is locate the file during the project creation wizard without having to switch the dropdown.

3. Yes, that is the best idea, most especially to avoid Step 4 where it is suggested one copy the backups. It’s easiest to export the backup to the right folder from your old install.

4. Another great question: it’s created on the volume where you choose to install Container Manager. But nobody I know would ever want to install a package on anything other than /volume1.

And @vadim, a postscript…it’s annoying to be unable to remove an orphaned disabled folder that I am never going to use:

[Giancarlo_Rosso]

Thank you very much, I was just looking a way to migrate from RoonOnNas to Docker (even if my 219+ still works file with old version).

[DDPS]

I didn’t need to make the switch, because Roon on NAS was working fine for me, but my friends around here thought it would be good if I went through this sooner rather than later in an effort to help reduce the number of support requests that create noise in these forums.

[vadim]

Hello @DDPS,

Thank you for the update.

@DDPS

The problem is, when trying to use this mapping after restoring from a backup, it scans the user’s music collection as if it’s all-new

During my testing, I was able to avoid this by disabling the watched folders before creating the backup and editing the storage paths before enabling them again. However, this could certainly be added as an alternative migration path for users who are unable to disable their folders before moving to Docker.

@DDPS

1. Another great question: it’s created on the volume where you choose to install Container Manager. But nobody I know would ever want to install a package on anything other than /volume1.

As mentioned by @Arindal

@Arindal

In my case, this was on HDD, as the primary volume of my machine is HDD. Surprisingly, the docker container ran fine on that one; I just don´t want my spinning discs to permanently move their heads.

Based on the information that I was able to find, this folder can subsequently be moved to a different SSD volume in the Shared Folder configuration to avoid using the HDD (better performance, avoid constant spinning). Does it look like a working solution?

I have updated the documentation using your guide, along with a few adaptations of my own. Would you kindly take a quick look and let me know if anything needs to be improved or revisited from your point of view?

[DDPS]

@vadim

During my testing, I was able to avoid this by disabling the watched folders before creating the backup and editing the storage paths before enabling them again. However, this could certainly be added as an alternative migration path for users who are unable to disable their folders before moving to Docker.

Well, I did this, and it didn’t work for me during my testing. It may be as factor of moving from Roon on NAS. If it’s of use, Roon on NAS’ internal folder mapping looks like this:

/var/packages/RoonServer/target/roonmnt/music/Non-Classical/Yes/Union/04 - Lift Me Up.flac

After migration to the Docker solution, the internal mapping looks like this:

/MyMusic/Non-Classical/Yes/Union/04 - Lift Me Up.flac

(These come from an Excel export of a playlist.)

@vadim

Based on the information that I was able to find, this folder can subsequently be moved to a different SSD volume in the Shared Folder configuration to avoid using the HDD (better performance, avoid constant spinning). Does it look like a working solution?

I tried this yesterday during testing. It is not possible.

I will take a look at your updates when I have a chance!

[Peter_Gallagher]

@DDPS

Another great question: it’s created on the volume where you choose to install Container Manager. But nobody I know would ever want to install a package on anything other than /volume1.

thanks for putting this doc together - I was a day too late (early i guess?) as I migrated from RoonOnRas to docker yesterday and just missed your doc- It really would have sped things up for me!

I’m guilty as charged, and did install container manager on my volume2 SSD - it seems to be fine, but would it be recommended to move it to volume1 (spinning disks ) and start over? If Roon is the only container being used with it, does it matter?

Are folks seeing any noticeable performance improvement with the docker install compared to RoonOnNas? RoonOnNas was always solid for me, so maybe it’s more of a lateral shift?

[Arindal]

@vadim

I was able to avoid this by disabling the watched folders before creating the backup and editing the storage paths before enabling them again.

Can confirm that. Once the backup is restored, and roon is scanning the ´new´ shared music folder, it seemingly helps to remove the previous ones completely from ´Storage´. In my case, just a dozen of albums out of 4,000 were not recognized correctly.

@DDPS

it’s annoying to be unable to remove an orphaned disabled folder that I am never going to use:

I did it the other way ´round, removing the previous subfolder and leaving only the main share ´Music Folder´ active, which worked well, but it less flexible in terms of disabling parts of the library.

@vadim

this folder can subsequently be moved to a different SSD volume in the Shared Folder configuration to avoid using the HDD (better performance, avoid constant spinning). Does it look like a working solution?

You mean similar to the ´database location´ option in RoonOnNAS app? Sounds like a good solution to me, but I did not figure out, how that should work.

I opted for installing the complete container on a solid-state volume, separated from the standard /Container/ folder, which worked well with the correct share path in docker generator.

@vadim

I have updated the documentation using your guide, along with a few adaptations of my own.

If possible, I would explain the share path and folder name thing a bit more in detail. This is where rookies to QNAP file logic might face serious problems of various kinds. From the folder /Container/ being on HDD, if your primary volume is SSD, to using a different path for the /Music/ folder, which is quite common.

When I had set up my QNAP, the top-level folder had been named /Multimedia/, and many people create subfolders like /Multimedia/Music/.

Instead of “Click the Copy Button”, I found it more reliable to download the .YML file and load it from a volume into Container Station.

Starting up the application in the container for the first time, seems to be a crucial moment. Ideally, there should be some basic troubleshooting in the manual, what to do when the container is not created, not starting up, returning error messages. I would also love to see a comment which folders you have to create manually (Music, Backups), and which Container Station is creating.

@Peter_Gallagher

would it be recommended to move it to volume1 (spinning disks ) and start over? If Roon is the only container being used with it, does it matter?

I would leave the roon container on the SSD, as it contains roon´s internal database, which is not a good thing to have on HDD.

[DDPS]

@Peter_Gallagher

I’m guilty as charged, and did install container manager on my volume2 SSD - it seems to be fine, but would it be recommended to move it to volume1 (spinning disks ) and start over? If Roon is the only container being used with it, does it matter?

Are folks seeing any noticeable performance improvement with the docker install compared to RoonOnNas? RoonOnNas was always solid for me, so maybe it’s more of a lateral shift?

I don’t think it’s going to cause any real issue that you installed it on volume2, especially since Roon is your only container.

And I am not seeing a performance change at all from Roon on NAS, which always performed well for me. I would only say that upon initial launch, Roon Server uses less RAM in this release regardless of platform, and maybe a teeny bit less in the Docker container than via Roon on NAS - but negligble difference in RAM, and same performance.

[gTunes]

Hi, @vadim.

Just a couple of quick responses to the many threads.

• Synology’s YAML text editor has been historically buggy. People have had paste issues in the past. I forgot about this when @DDPS and I were working this yesterday. I wonder if the person who reported paste not working was on Safari on a Mac and I wonder how they were pasting. Chrome and Chromium based browsers have been more reliable. I think Command-V may be may more reliable than the Edit → Paste menu. I recall that @DDPS uses a Chromium browser (Brave) and I doubt he’s selecting Edit → Paste so he may avoided the issues. I recommend a note in the docs saying that if you are having issues try (Command-V or a different browser). Don’t switch to recommending the import from file option. It’s going to be far too confusing for some people.

• I’m not sure what the current RoonOnNAS package is doing with paths but @DDPS and I spent a bunch of time trying different strategies for path simulation and couldn’t figure out a better approach than what he proposed. I think it’s about as clean as it gets.

• We’re seeing people run into issues trying to install as container image instead of as a Project. They’re doing the wrong thing but it uncovered the fact that Synology doesn’t handle ghcr well as a container - it’s not a default and I’ve read that there are issues with it even when configured as an additional registry. I wonder if you should be investigating also pushing container images to docker hub. Those would always just work with Synology. The existing github workflow could push to both locations.

• I hope you guys get a Synology in-house for testing and to help document. The next big event you’re going to run into is if/when you recommend or require a container image update. Updating containers when using Project deployment is not trivial. Marius describes it in this walkthrough (you have to look at the second half) but you might want to bring the documentation in house and include it. To write it, and test it, you really need a Synology

Thanks for continuing to work on this.

[DDPS]

@gTunes is right - I use Brave. I use command-V for paste but with all this discussion about that field not working, you bring up something that I glossed over and just dealt with - it seems that if you have your cursor in the field ready for pasting and then leave the browser or tab to get something on your clipboard, the text field in Container Manager loses focus, and you have to use your mouse to click into it in order to paste…

And in regard to buying a Synology unit, you could do all the testing you need for DSM 7.3 environments with this unit, which is very basic:

Amazon.com: Synology 2-Bay DiskStation DS725+ (Diskless) : Electronics

Buy a couple of WD Red drives for it, and you will be set. You could buy some aftermarket RAM for your tests if you want to test larger libraries under load.

In regard to testing for 7.1 and lower, you will need to go to eBay and get something like this:

https://www.ebay.com/itm/377115186909

And then download DSM 6:

Synology Archive Download Site - Index of /download/Os/DSM

[DDPS]

@vadim

I have updated the documentation using your guide, along with a few adaptations of my own. Would you kindly take a quick look and let me know if anything needs to be improved or revisited from your point of view?

First thing:

Per above, this cannot be moved after install. There is no reason to worry about it. Just install Container Manager on /volume1, leave the /docker share empty and then just define the SSD paths in the configuration utility.

Second, I recommend doing a bit of URL handholding in your links - the configurator, if I can call it that, accepts parameters, so send Synology users to RoonServer Docker Configuration Generator.

Third, the instructions are still missing the step to switch “Source” from “Upload docker-compose.yml” to “Create docker-compose.yml”

Other than that, at first glance, it seems you have put in some very useful items from my instructions, but I don’t have the luxury today or in the foreseeable future to test these revised instructions first-hand (not to mention that I am all set for now and after doing 6 or so full migrations yesterday, I am ready to let my music play…) My recommendation is to get a Synology unit and walk through this yourselves, most especially testing the path I have to migrate from Roon on NAS, which seems to present unique challenges that I think our combined instructions manage to cover for now. Thanks for doing this.

[gTunes]

@DDPS

In regard to testing for 7.1 and lower, you will need to go to eBay and get something like this:

@DDPS - if they get this and stick an (approved) SSD into one of the M.2 slots, they can set that up as a second volume, right?

Today, many people set their M.2 drives up as cache in front of the spinning media volume (and do things like pin BTRFS) but for testing and documenting, it might be a better idea to set one up as a second volume.

You found a YAML bug! Nice!

[Arindal]

@gTunes

Today, many people set their M.2 drives up as cache in front of the spinning media volume (and do things like pin BTRFS) but for testing and documenting, it might be a better idea to set one up as a second volume.

Many of these little 2-bay machines have actually two M.2 slots, so one can be used as cache, the other one for a fast secondary volume to database, containers and alike.