What are the host volume paths and the container paths

From Unraid | Docs
Jump to: navigation, search

What are the host volume paths and the container paths

Just in case this is too hard to read, if you're reading this part of the FAQ, you're probably going to be best off setting up your docker paths as /mnt mapped to /mnt. Similar to this:


Note: You'll notice throughout this that I talk about "best practice" a lot. Truth be told the risks associated with violating the best practices are pretty low.

I've always had a real tough time trying to explain this because it is a confusing issue to try and explain, but trust me that once you understand it will make 100% perfect sense.

First thing: Docker Containers are (for all intents and purposes) completely separate from the rest of the unRaid system. A container has no idea that its running on unRaid (or any other system), and has no concept of any other containers that may also be running. What this section really needs is a video with lots of arrows, hand waving, etc. But, this is my best shot at it purely using text.

A container usually needs to access information (either read only or read/write) on the host (unRaid) system. Because a container is completely separate from the unRaid system we have to tell it what folders (paths) that it has access to.

This is done in the mapping section of the Add Container screen.

There are two parts to every line. The container volume path and the host path.

The host path is (generally) your shares that you want to give the container access to. Best practice for containers dictates that if the container only needs access to a Downloads share, that you only create a mapping for the Downloads share.

On the host path this would be something like /mnt/user/Downloads.

On the container path side of things, you tell the container how it should "refer" to the host path. IE: If the container path is /Downloads, then when ever you tell the container to save something into /Downloads, docker will then "map" it and actually store it on your unRaid system at /mnt/user/Downloads.

In most cases, it really doesn't matter that much what your host path and container paths are as long as you can get to the data that you want. Where it begins to matter is if you have multiple containers that need to communicate with each other. EG: SabNZBD and Sonaar. In this case, Sab tells Sonaar "I just downloaded a file and stored it in /Downloads" (remember that /Downloads is mapped to /mnt/user/Downloads)

Now, if Sonaar has different mappings (eg:/MyDownloads mapped to /mnt/user/Downloads), then its not going to be able to find the downloaded file because it will be looking in /Downloads for the file (like sab told it to), but that folder (/Downloads) does not exist in the Sonarr container.

"Best Practice" in this case dictates that both Sab and Sonaar have to have identical matching mappings for the downloads folder.

Here's a thread showing one user's issues with this: http://lime-technology.com/forum/index.php?topic=43337.0

Maybe an easy way to think about this is to compare it to mapping a network drive in windows. When you map a network drive in windows to something like //tower/MyMovies, windows creates a new drive letter (Z:) and when ever it sees a reference to Z:MyParticularMovie, what it actually does is translate that internally to be //tower/MyMovies/MyParticularMovie. Docker does the same. If you map /Downloads to be /mnt/user/Downloads, the container refers to everything as /Downloads, but internally docker substitutes /Downloads/MyParticularMovie to be /mnt/user/Downloads/MyParticularMovie.

In my sample picture above, you will notice that I have a separate /config line. This is where the docker actually stores its data (not its downloads, or whatever). This is almost always mapped to /mnt/cache/appdata/dockername. The template authors have now pretty much settled on using appdata/dockername. The one big caveat is that the appdata share that you create must be a "cache only" share. If you do not set it to be cache only, when the mover script comes along every day at 3am, it will move the files from your cache drive to your array. In the process, permissions on the files will get changed with the net result that your docker application probably will not work correctly the next time you use it.

Confused yet?

An easy work around to this (but not "best practice") is for on the container and host paths to pass through either /mnt/user or /mnt on both sides on all of your containers.

This has the advantage that when you're browsing (within a container) to select a folder, you are going to see the exact folder structure that you're already used to from browsing your shares on your server. In my sample picture above, I would tell Ubooquity (in its UI) that my ebook collection is stored in /mnt/user/ebooks. This happens to be the EXACT same path that you would refer to it within unRaid. Hence why this trick is so easy.

The downside is that your container then has access to all of your shares (when there's no real need for it to). And, you pretty much also have to make sure that /mnt/user is always passed with read/write privileges. (One huge advantage of docker is that the container does not have to have write privileges to shares which it doesn't need to.

Confused yet?

And now for a final kicker. Adding a line called /mnt mapped to /mnt may not work on all containers. Some containers will outright insist on having a /workdirectory or a /downloads folder which you then have to suitable map to a particular share. But, for the majority of them (probably at least the ones with a UI), you should be safe using the /mnt mapped to /mnt trick.

P.S. If anyone else can try and come up with something that makes more sense that the above, please be my guest.