Docker Template XML Schema


Recommended Posts

What will "break" is during an update to the container if the template also has changes then the update process will not pick up any changes.  Since template updates are rare this isn't a huge deal

 

Fix Common Problems will complain and inform everyone that the URL has changed and will prompt the installed user base to click a button to automatically update the URL (which fixes the above)

Link to comment
  • 3 weeks later...
On 2/20/2020 at 4:43 PM, Squid said:

Regarding <TemplateURL>

 

If having this entry populated with the URL causes problems for you, then going forward (as of Feb 21) maintainers can manually edit the appropriate xml in their repositories and either change the existing entry or add in

 

<TemplateURL>false</TemplateURL>

If the appfeed sees false in that entry, then it will not populate it automatically with the URL of your template.  This has the result of if a user deletes a variable, then on the next container update dockerMan will not re-add that variable back into their template.

 

This is a manual only edit, and cannot be done via dockerMan's GUI.   If any one starts bugging you about FCP complaining about a missing template URL via FCP, then tell your users to simply ignore that error.

 

Note that any of your users will also either have to reinstall the app from scratch or manually edit their user template to get rid of the existing entry.

 

@Roxedus

 

 

In reference to a github issue I raised, specific to the linuxserver homeassistant docker Github Comment, upon updating homeassistant, multiple mandatory path/to/device fields populate and cause the container to fail to start until I manually delete them. 

 

Initially, the dev instructed that I get Docker into author mode and delete the TemplateURL, but then discovered the existence of this thread and the end of TemplateURL in author mode. However, they state that the template sync is turned off on their end. Is there anything I can do on my end to remedy this? I apologize if this needs to be posted elsewhere. 

Link to comment

Just a note regarding template updates.

 

Since Unraid 6.2, the OS has automatically updated templates to always reflect the currently available version.  (IE: It will add in any missing path, port, variables that the user's template does not have).

 

This was done on the theory that a new update to the container may also require any missing new entries.  This behaviour has been troublesome for certain templates and how some users configure their systems.  A flag to indicate to the OS to not update the templates has been in place to avoid this:

<TemplateURL>false</TemplateURL>

 

Starting however with the release of Unraid 6.10-rc3+ the system will no longer automatically update user's templates.  Effectively this means that should you issue an update to the container which requires an update to the template you will need communicate this to the users via your support venues.  

 

Currently, CA (and FCP) will still ensure that the templates are still being updated on versions of the OS < 6.10.  If this change in the OS proves to lessen support requests to the maintainers, then CA and FCP will be modified to prevent those legacy versions of the OS from also updating the templates.

 

IE: If you were using the above flag to signal to the system to not update the templates, you should continue to do so.

  • Like 2
Link to comment
On 1/20/2022 at 8:18 AM, Squid said:

Starting however with the release of Unraid 6.10-rc3+ the system will no longer automatically update user's templates.

 

Are you aware of the reasoning behind this change in 6.10?  Why don't we continue let the maintainer chooses if its templates should be automatically updated or not?  I find this update mechanism very useful to provide fixes, enhancements and additions to the template.

 

Personally, I think I had only 1 reported issue related to the automatic template update.  So I don't think that stopping template updates would reduce the number of support requests.  This will probably increase it!

 

Link to comment
4 hours ago, JonathanM said:

A VERY vocal group complaining that the automatic updates were continually breaking their stuff, and basically saying Unraid should never be able to change the templates behind their back.

Thanks, I will provide my though in the thread you mentioned.

Link to comment
  • 2 weeks later...

To quickly deprecate any given template in your repository, two choices

 

Either add in <Deprecated>true</Deprecated> into the xml, or now you can also simply put those templates into a subdirectory named "deprecated" of your repository, and the feed will automatically apply that tag to them.

  • Like 1
Link to comment

Starting with CA version 2022.02.06, in the <Requires> field you now have the option to have CA actually do a search for whatever is required

 

<Requires>//Redis\\ installed</Requires>

 

Will in the sidebar make a search link for Redis to allow the user to easily install it.  (The " installed" part of the above is just extra text and not part of the "link" itself)

 

This link is sanitized when transmitting the xml to the OS for installation, so the extra characters (// \\) will not appear when installing or editing the app within dockerMan

 

Link to comment
  • 2 weeks later...

Going forward, the application feed is going to automatically remove any template within a template Repository that:

  1. Refers to the exact same dockerHub repository as another template within the same repository AND
  2. Has the exact same application name as the other template

Currently Apps falling into this are hard to find because everything "looks right" until you actually go to install one of them (and even there it still "looks" right even though it's not and the wrong template gets installed

 

This rare situation to be handled otherwise requires a major overhaul (Read that as a full day's work in overhauling CA, and basically starting the ENTIRE QA process in CA all over again (ie: Months of regression testing)

 

IMO, the ideal way to handle this type of stuff from a Maintainer's side is to use CA's Branches, but I do understand why authors don't always want to integrate branches.

 

@hernandito

Link to comment

Re the previous post.  The appfeed is now enforcing something a little more generalize.  Every template within a template maintainer's repository must have a unique name on the template (not just the obvious filename). This catches @alturismo and xteve. 

 

Note that this has nothing to do with "Plex" being in one repository and "Plex" being in another repository -> that's perfectly acceptable

Link to comment
To quickly deprecate any given template in your repository, two choices
 
Either add in true into the xml, or now you can also simply put those templates into a subdirectory named "deprecated" of your repository, and the feed will automatically apply that tag to them.

Wil FCP or CA warn users if any or both of these is true?
Link to comment
  • 1 month later...
On 1/21/2022 at 5:09 PM, JonathanM said:

A VERY vocal group complaining that the automatic updates were continually breaking their stuff, and basically saying Unraid should never be able to change the templates behind their back.

 

 

 

What will be the mechanism for users to update the template if the developer maintaining it does need a change?

 

I would have considered the ability to update the template as important as updating the container, and having a flag to disable updates in the UI would be good for end users who choose not to take the recommended config from the maintainer.

Link to comment
 
What will be the mechanism for users to update the template if the developer maintaining it does need a change?
 
I would have considered the ability to update the template as important as updating the container, and having a flag to disable updates in the UI would be good for end users who choose not to take the recommended config from the maintainer.

Considering unraid is the only plattform offering this, its not unreasonable to ask users to somewhat keep up with the updates for a container.
  • Thanks 1
Link to comment
On 5/30/2015 at 3:27 PM, Squid said:

<Overview> Contains a condensed description for the container (basically the same thing as the description, but without any formatting or instructions  http://lime-technology.com/forum/index.php?topic=39106.msg365627#msg365627  unRaid 6.2+ generates this tag instead of the <Description> tag

I'm double checking here, but it is not just that either Overview or Description are required, but if both are provided, the first one listed in the XML will be displayed and the other ignored, is that the expected behaviour?

 

I was trying to have both a short Overview and a longer Description with instructions but seem to have ended up with only the Overview rendering in the Apps listings.

Link to comment
  • 2 weeks later...
On 4/9/2022 at 5:55 PM, Roxedus said:


Considering unraid is the only plattform offering this, its not unreasonable to ask users to somewhat keep up with the updates for a container.

I'm willing to do that, but if the template changes, it'd be a very good idea to have those templates versioned.

At least on breaking changes.

And for sure it should be automated when there's new path mappings offered. Reason being that you may end up writing into your docker image all of a sudden.

Considering unRAID these days is typically recommended as "the go to" for simple, fully managed DIY NAS solutions you kinda have to account for maybe not user errors at every corner, but user laziness.

Also, we all have personal lifes, sometimes you really can't keep up with your homelab for a while, if stuff that's important breaks in the meantime and you don't know what happened or why, that can spiral into a lot of wasted time.

It's good that templates can use release notes, that they can be updated, etc... (although it's not the only platform offering this, Portainer can pull changes from a git-managed docker compose for example)

However that doesn't mean it's unimprovable.

As far as wishing for a deactivation of updates for templates is concerned, I doubt that's really feasible or needed.

The underlying app's docker container won't suddenly not have those needed new mappings and the like just because the template doesn't define visual fields to fill for them. So I get if you're coming from that side and I may have misunderstood your entire post. :D

Link to comment
On 4/13/2022 at 6:50 PM, Goobaroo said:

I'm double checking here, but it is not just that either Overview or Description are required, but if both are provided, the first one listed in the XML will be displayed and the other ignored, is that the expected behaviour?

 

I was trying to have both a short Overview and a longer Description with instructions but seem to have ended up with only the Overview rendering in the Apps listings.

Long story behind the evolution of <Overview> vs <Description> which TBH I'm still annoyed about (although it's currently 7:51 am and I'm now considering having a beer before work to calm down now that this has come up again ;) )

 

If Overview is present, then Description is completely ignored

  • Thanks 1
  • Haha 2
Link to comment

Sorry to bring up past development trauma, I've had many of those events in my carrier as well.

 

I'll just redo my templates to use the <Description> tag instead.  Thankfully they are all templated and generated out of my CI/CD pipeline.  

 

I don't know if there is a community development group for reviewing and recommending changes, but I'd love to be part of it.

Link to comment
On 4/26/2022 at 9:41 AM, Glassed Silver said:

As far as wishing for a deactivation of updates for templates is concerned, I doubt that's really feasible or needed.

Of course this (deactivation) is needed and already possible, especially for my game server containers…


For example if someone runs multiple CS GO servers they have to delete the old port mapping, and create a new port mapping with the config for the game server changed too.

The reason behind this is that you easily can‘t translate ports from one to another, for example container:27015/host:27016 won‘t work or better speaking if you do so you can query the server but you can‘t connect because some game servers send information on which port the server runs to make sure it wasn‘t tampered with…


Same goes for Valheim and many more.

 

Ultimately when I leave automatic updates turned on all container will break that have custom ports in it because they get readded when CA Update or whatever kicks in.

 

On 4/26/2022 at 9:41 AM, Glassed Silver said:

Reason being that you may end up writing into your docker image all of a sudden.

Considering unRAID these days is typically recommended as "the go to" for simple, fully managed DIY NAS solutions you kinda have to account for maybe not user errors at every corner, but user laziness.

From my perspective it shouldn‘t be updated automatically and the user should go to the forums/repo, look up what changed and fix it themselves.

 

I really don‘t like it that something is fully updated/changed automatically when I changed it by intention, well yes, if something breaks or doesn‘t work properly anymore I have to look up what changed and fix it.

 

I don‘t think that‘s laziness by the users…

 

Just my 2 cents…

  • Like 1
Link to comment

@ich777 You raise excellent points there, one question though:

 

when we see that needed local changes getting yote is the problem, why do we not tackle the problem at its root?

 

IMHO unRAID should track your changes, stash and apply stash them.

 

Git-style merges of local deviations.

 

These sorts of problems have long been solved, the problem is that unRAID CA templates get updates in a way where settings are applied again, but not the template modifications.

Link to comment
31 minutes ago, Glassed Silver said:

IMHO unRAID should track your changes, stash and apply stash them.

TBH I really don‘t want that a template changes on it‘s own and or a maintainer can easily change things in my template that I changed on purpouse…

 

It happened once for a OpenVPN-Client template IIRC that out of no where pointed to a completely different container where the source has no where to be found or at least it was some really suspicious source.

 

I think the users should take care of that themselve if a container breaking change is introduced.

 

I‘m really not a huge fan of self changing templates or better speaking maintainer changable templates.

  • Like 1
Link to comment

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.