Use docker labels for UnRaid-specific information in docker templates to allow for a 1:1 map between UnRaid templates and docker-compose files.

[Taako]

Original comment thread where idea was suggested by reddit user /u/neoKushan :

https://old.reddit.com/r/unRAID/comments/mlcbk5/would_anyone_be_interested_in_a_detailed_guide_on/gtl8cbl/

 

The ultimate goal of this feature would be to create a 1:1 map between unraid docker templates and docker-compose files. This would allow users to edit the docker as either a compose file or a template and backing up and keeping revision control of the template would be simpler as it would simply be a docker-compose file.

 

I believe the first step in doing so is changing the unraid template structure to use docker-compose labels for all the metadata that unraid uses for its templates that doesn't already have a 1:1 map to docker-compose. this would be items such as WebUI, Icon URL, Support Thread, Project Page, CPU Pinning, etc. 

 

Most of the meat of these templates are more or less direct transcriptions of docker-compose, put into a GUI format. I don't see why we couldn't take advantage of this by allowing users to edit and backup the compose file directly.

Edited April 8, 2021 by Taako

[Kushan]

Oh hey, it's a me! 

 

Yeah, this is something I was hoping was already being done under the hood, but alas the docker manager used by unRAID handles metadata its own way (If anyone can point me in the direction of how that metadata is stored and used, please let me know).

 

The template system used by unRAID is great, it makes adding docker containers pretty straightforward and blings them up on the dashboard, with a nice icon or direct link to the container's WebUI. The only issue is that this system is somewhat proprietary and specific to unRAID. If you're using an image that doesn't have a matching template, there's currently no easy way (That I've found) to add them yourself without creating a whole template file. Or if you created your container outside of unRAID's own docker manager, you're equally out of luck. I prefer to manage my containers using docker compose, others use portainer, we'll all encounter the same issue (I understand that this is a tradeoff we make knowingly and I appreciate that you can argue if we're not using unRAID to manage our containers, then why should we care how they look on the dashboard).

 

A good solution to this (in my opinion) would be to update the dashboard to check for some of this data using docker labels if a template doesn't exist. To clarify something that @Taako may have slightly misunderstood: This isn't anything specific to docker compose, but rather it's baked into docker itself. Compose just uses labels to add metadata to containers, but labels are a docker specific feature.

 

Labels are key-value pairs and their use is pretty well defined. It would be great (And I think relatively easy?) to specify a bunch of unRAID specific labels so people can apply them themselves, then have unRAID's docker manager fall back on them (Or even prefer them so users can tweak them on the fly) for example:

 

net.unraid.docker.icon="https://www.example.com/icon.png"
net.unraid.docker.description="An example description"
net.unraid.docker.webui="http://[IP]:[PORT:4040]/"

 

This would supplement the existing template engine rather than replace it, it would mean almost any docker management tool (Like portainer) can manage these assets and, for my own personal use, would mean I can add them to my compose files as well. Image authors can even preemptively add them to their images (The Linuxserver.io guys apply some labels to their containers already) again without having to manage an entire unRAID template. 

 

To be clear: I have nothing against the template system, it's pretty neat and has helped a lot of people get their feet wet with docker. I think it's great. I'd just like to be able to take advantage of some unRAID specific gubbins without having to go the whole hog and have my containers managed entirely by unRAID 

 

Edited April 6, 2021 by Kushan

[drsprite]

This is a great idea and I'm surprised it's not implemented since labels are native to docker

[drsprite]

On 4/6/2021 at 6:40 PM, Kushan said:

Labels are key-value pairs and their use is pretty well defined. It would be great (And I think relatively easy?) to specify a bunch of unRAID specific labels so people can apply them themselves, then have unRAID's docker manager fall back on them (Or even prefer them so users can tweak them on the fly) for example:

 

net.unraid.docker.icon="https://www.example.com/icon.png"
net.unraid.docker.description="An example description"
net.unraid.docker.webui="http://[IP]:[PORT:4040]/"

 

 

Turns out this is pretty simple to implement. It requires editing core files - which means it'll probably be lost one day on upgrades. I have no idea if this can be done with a community app, but this is at least a beginning for us who are used to docker-compose but still able to use the dynamix docker manager web interface. 

 

Tested this in version 6.9.2

 

I take no responsibility if you break something. Make sure you have a backup of this file before you begin. 

 

It would be great to see this included in the core of unraid since it's such a simple addition. 

 

Edit /usr/local/emhttp/plugins/dynamix.docker.manager/include/DockerClient.php

 

Look for public function getAllInfo($reload=false) { and at the very end of the foreach add:

 

if ($ct['Icon']) $tmp['icon'] = $ct['Icon'];
if ($ct['url']) $tmp['url'] = $ct['url'];

 

Look for public function getDockerContainers() { and inside the foreach, beneath the line containing $c['BaseImage'], add:

$c['Icon'] = $info['Config']['Labels']['net.unraid.docker.icon'] ?? false;
$c['url'] = $info['Config']['Labels']['net.unraid.docker.webui'] ?? false;

 

Clear browser cache and reload the unraid web ui. Icons and webui links from unraid templates still work, and those from a docker container label also now work. 

 

Edited April 14, 2021 by drsprite

[Kushan]

Ohh, this is brilliant work @drsprite! I'm going to try tinkering with this on my own server.

[bonienl]

Docker labels is probably something we can do in Unraid 6.10

 

Thx for the explanation.

 

[primeval_god]

I have actually been toying around with a very similar idea myself for some time. In my case specifically however i was looking to have dockerman add this label 

net.unraid.dockerman.managed

along with ones for the webui and icon to every docker container. The idea would be to have an option for unraid to display only containers labeled with the net.unraid.dockerman.managed label on the dashboard and an option on the docker page to have tabs for managed and unmanaged containers. This would allow me to hide any containers created by other sources (such as ephemeral containers) from the main interface. 

 

For getting the labels added to containers I believe adding the following lines to the xmlToCommand function in dockerman's Helpers.php was were i was looking

 

  // Add HOST_OS variable
  $Variables[]   = 'HOST_OS="Unraid"'

  // Dockerman Control Labels
  $Labels[]   = 'net.unraid.dockerman.managed';
  $Labels[]   = strlen($xml['WebUI']) ? 'net.unraid.dockerman.webui='.escapeshellarg($xml['WebUI']) : '';
  $Labels[]   = strlen($xml['Icon']) ? 'net.unraid.dockerman.icon='.escapeshellarg($xml['Icon']) : '';  

@bonienl

Edited April 16, 2021 by primeval_god

[Kushan]

That's really good to know! I haven't had time to look into the above yet, but more info on this is certainly helpful. 

 

On 4/14/2021 at 6:04 PM, bonienl said:

Docker labels is probably something we can do in Unraid 6.10

 

Thx for the explanation.

 

 

That's great to hear! Thank you. If you need any help or thoughts on the implementation, feel free to reach out!

[Ryonez]

I'm happy to see any steps towards docker-compose support. So many use it now.

[NewDisplayName]

I really like this too, btw its relativly easy to use docker compose with unraid, just install docker portainer... flawlessly for years now.. but ofc would be much nicer to have integrated... 

Edited April 16, 2021 by nuhll

[Kushan]

I haven't posted this beyond reddit so far, but I'm currently working on a guide on everything to do with using compose on unraid, you can check it out here: https://unraid.kushan.fyi/

 

I'll make a dedicated thread on it when it's more complete but for anyone reading this topic, feel free to take a look. 

[bling]

count me as another user who's migrated everything over the docker-compose so this is a welcome development.

 

i've also found the missing icons annoying.  rather than editing core files i'm opted to create templates instead with the same container name and leave everything else blank.  this is enough to trick unraid.  something like this:

 

<?xml version="1.0"?>
<Container version="2">
  <Name>portainer</Name>
  <Repository>portainer/portainer-ce</Repository>
  <Registry>https://hub.docker.com/r/portainer/portainer-ce/</Registry>
  <WebUI>http://[IP]:9000/</WebUI>
  <Icon>https://secure.gravatar.com/avatar/681edab450c1ebab7d83e7266b1d0fbb.jpg</Icon>
</Container>

 

you'll have to edit the files directly instead of going through dockerman.  and while you can use dockerman to start/stop containers, you can't use it to do anything else like editing containers, updates, etc. otherwise you will mess up your compose configuration and be forced to manually delete conflicting containers.

 

but, once you're fully committed to compose it's literally just a 

docker-compose pull
docker-compose up -d

 

to get the latest of all images and restart everything.

 

dockerman will still inaccurately state that everything is out-of-date, but i've learned to ignore that.

Edited April 17, 2021 by bling

[korey_sed]

On 4/17/2021 at 9:00 AM, bling said:

count me as another user who's migrated everything over the docker-compose so this is a welcome development.

 

i've also found the missing icons annoying.  rather than editing core files i'm opted to create templates instead with the same container name and leave everything else blank.  this is enough to trick unraid.  something like this:

 

<?xml version="1.0"?>
<Container version="2">
  <Name>portainer</Name>
  <Repository>portainer/portainer-ce</Repository>
  <Registry>https://hub.docker.com/r/portainer/portainer-ce/</Registry>
  <WebUI>http://[IP]:9000/</WebUI>
  <Icon>https://secure.gravatar.com/avatar/681edab450c1ebab7d83e7266b1d0fbb.jpg</Icon>
</Container>

 

you'll have to edit the files directly instead of going through dockerman.  and while you can use dockerman to start/stop containers, you can't use it to do anything else like editing containers, updates, etc. otherwise you will mess up your compose configuration and be forced to manually delete conflicting containers.

 

but, once you're fully committed to compose it's literally just a 

docker-compose pull
docker-compose up -d

 

to get the latest of all images and restart everything.

 

dockerman will still inaccurately state that everything is out-of-date, but i've learned to ignore that.

 

I got this to work for one of my dockers buts some do not work.  how do you name the tamplate? or what is the trick to make unraid realize and link the template to the contianer?

[bling]

12 hours ago, korey_sed said:

 

I got this to work for one of my dockers buts some do not work.  how do you name the tamplate? or what is the trick to make unraid realize and link the template to the contianer?

take a look at /boot/config/plugins/dockerMan/templates-user, which is where unraid stores all the XML templates.  any time you add a docker container from the community apps, for example, creates a file and saves it here.

 

if you're using docker-compose you don't need to fill in the rest, just the high level things like the name, repository, icon, URL, etc.

 

and of course, this is all non-standard and really the only reason why you would do this is if you want nice icons on your dashboard.  you do not want to use unraid to manage your containers because it will mess up both unraid and docker-compose.

[Corbot3000]

Would love to see this feature added 

[bonienl]

This is added in Unraid version 6.10

[hasown]

On 2/1/2022 at 6:37 PM, Corbot3000 said:

Would love to see this feature added 

 

There isn't good official documentation afaik, but I gave an example in a comment here.

[aomine]

star

[primeval_god]

@bonienl Does the 6.10 implementation of this feature cache the icons (specified by label) on disk like it does with icons specified in templates?

[bonienl]

9 hours ago, primeval_god said:

@bonienl Does the 6.10 implementation of this feature cache the icons (specified by label) on disk like it does with icons specified in templates?

 

yes icons are locally cached.

[ScreN]

Quote

It would be great to see this included in the core of unraid since it's such a simple addition. 

 

Edit /usr/local/emhttp/plugins/dynamix.docker.manager/include/DockerClient.php

 

Look for public function getAllInfo($reload=false) { and at the very end of the foreach add:

 

How to fix this bug?

And this changes removed from file DockerClient.php after reboot server

 

Edited May 14, 2022 by ScreN

[bling]

just upgraded to 6.10.1.  are the labels working for anyone else?  here's a simple compose file.

 

version: "2.2"
services:
  nginx:
    image: nginx
    labels:
      - net.unraid.docker.icon=https://some.server.com/image.png

 

launched the container, went to the docker tab, but the image doesn't get loaded.

[ScreN]

12 minutes ago, bling said:

just upgraded to 6.10.1.  are the labels working for anyone else?  here's a simple compose file.

 

version: "2.2"
services:
  nginx:
    image: nginx
    labels:
      - net.unraid.docker.icon=https://some.server.com/image.png

 

launched the container, went to the docker tab, but the image doesn't get loaded.

 

Labels

- net.unraid.docker.icon

working only for local path and only .PNG format

 - net.unraid.docker.icon=/mnt/user/appdata/icons/icons.png

 

Edited May 25, 2022 by ScreN

[primeval_god]

It would also be nice to have be able to specify the shell to use when clicking "Console" via a label. To that end i have made a pull request https://github.com/limetech/webgui/pull/1152 to add usage of net.unraid.docker.shell. (In additional to my request to fix icon caching https://github.com/limetech/webgui/pull/1146)

 

@bonienl