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


14 posts in this topic Last Reply

Recommended Posts

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 by Taako
  • Like 12
Link to post

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 by Kushan
Link to post
  • Taako changed the title to Use docker labels for UnRaid-specific information in docker templates to allow for a 1:1 map between UnRaid templates and docker-compose files.
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 by drsprite
Link to post

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 by primeval_god
Link to post

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!

Link to post

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 by nuhll
Link to post

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. 

Link to post

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 by bling
Link to post
  • 2 weeks later...
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?

Link to post
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.

Link to post

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Guest
Reply to this topic...

×   Pasted as rich text.   Restore formatting

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.