Docker Template XML Schema


Recommended Posts

The only caveat that I see however is that since CA is not integrated into unRaid, officializing the <Category> tag does tie my hands should the need (however remote) for an additional entry into that.

 

That's not a show stopper, we could always add that to Docker Manager if necessary.

Link to comment
  • 1 month later...

Sorry if this is not the right thread. I am updating my Unraid templates to point the Home Assistant templates to a new repo (migrated from balloob/home-assistant to homeassistant/home-assistant).

 

As part of the process I am cleaning up how Docker generates my images and I want to migrate from 2 repositories (home-assistant, home-assistant-dev) to 1 repository with two tags (latest, dev). However, I can't seem to find a way to specify a tag in a template. Is this possible?

Link to comment
  • 1 month later...

Can I use Status:Beta|Stable in "<Category>" tag with CA, or do I need to use the "<Beta>" tag? (any different for 6.1.9 and 6.2?)

 

Also, is the <Description> tag removed from 6.2? Is there an new way to have different information on CA (overview), and then you add the docker (where description was before).

This is working fine on 6.1.9, but not on 6.2b21 :(

 

Template if someone would like to take a look (it is in CA also):

https://github.com/bjonness406/Docker-templates/blob/master/Bjonness406/PlexRequestsNet.xml

 

 

Link to comment

Can I use Status:Beta|Stable in "<Category>" tag with CA, or do I need to use the "<Beta>" tag? (any different for 6.1.9 and 6.2?)

After it was determined (not by myself - although admittedly I was neutral on the change) to deprecate the <Beta> tag CA supports both methods.  dockerMan itself makes no use of the Category entry (and also doesn't implement it 100%), so it's irrelevant

 

Also, is the <Description> tag removed from 6.2? Is there an new way to have different information on CA (overview), and then you add the docker (where description was before).

This is working fine on 6.1.9, but not on 6.2b21 :(

Othersl decided to deprecate the description tag and instead utilize (and unilaterally change the specification without any consultation and then try to tell me that they know the specifications of CA's tag's better than myself) of the <Overview> tag in 6.2 which was previously a CA specific tag (and designed for its needs)

 

Net result is that the operation you are seeing is correct:  Only the overview displays under 6.2 (and in CA)

 

Link to comment

 

 

Also, is the <Description> tag removed from 6.2? Is there an new way to have different information on CA (overview), and then you add the docker (where description was before).

This is working fine on 6.1.9, but not on 6.2b21 :(

Othersl decided to deprecate the description tag and instead utilize (and unilaterally change the specification without any consultation and then try to tell me that they know the specifications of CA's tag's better than myself) of the <Overview> tag in 6.2 which was previously a CA specific tag (and designed for its needs)

 

Net result is that the operation you are seeing is correct:  Only the overview displays under 6.2 (and in CA)

Ahh :(

I liked the previous <overview> and <description> a lot more, looks more clean, and I don't see the point of changing it.

 

Link to comment
  • 3 months later...

One of the new features enabled by CA's rewrite of its rendering engine is user-selectable Branches to install.

 

If the template supports this, when the user installs (or defaults) a supported template, they will be presented with a pop up asking them which branch of the application to install.

 

Add this in to the template:

<Branch>
    <Tag>tag#1</Tag>
    <TagDescription>This is the description of tag #1</TagDescription>
</Branch>
<Branch>
    <Tag>tag #2</Tag>
    <TagDescription>This is the description of tag #2</TagDescription>
</Branch>
and so on...
 

 

When the user selects a branch, the tag (if any) that is already included in the <Repository> entry will be overwritten with the selected tag prior to the xml being sent to dockerMan.

 

The user will also be presented with a Default option which will send to dockerMan the xml with an unaltered <Repository> entry with whatever tag is already present in it (if no tag is present, dockerMan automatically appends :latest as a tag)

 

I don't really recommend adding more than a few branches to any container, as the user can ultimately still change the branch themselves in dockerMan, limited screen real estate, and who wants to add the 100 or so branches that something like MySQL offers to a template.

Additionally, this feature is not going to be back-ported to legacy mode in CA (ie: if you hit Update Applications, you will not see the popup)

 

This feature will be available within CA sometime the week of September 5

 

Advanced

 

Each branch also has the ability to replace any of the xml tags from the main template.

 

EG: If the default tag requires an environment variable of LAN=1, but the branch requires VMLAN=1, then you would have the xml set up something like this:

 

.
.
.
<Environment>
  <Variable>
    <Name>LAN</Name>
    <Value>1</Value>
  </Variable>
</Environment>
.
.
<Branch>
  <Tag>SomeTag</Tag>
  <TagDescription>This is the description</TagDescription>
  <Environment>
    <Variable>
      <Name>VMLAN</Name>
      <Value>1</Value>
    </Variable>
  </Environment> 
</Branch>
 

Note that ANY of the template schema can be replaced by the branch this way (including the repository - If replacing the repository, specify the full repo including the tag, as the tag identified by the <Tag> entry will not get appended in this case

 

Also note that if the template is a v2 template (ie: has the <Config Name..... > entries, you should include both the <Config entries AND the v1 legacy sections to be replaced for compatibility for 6.1.x

 

Also, note that for <Config> entries within Branches, ALL configs must be included in the Branch, not just additional ones.

 

For a couple of examples, look here: https://github.com/Squidly271/docker-test-repo

  • Like 1
Link to comment
  • 3 months later...

Briefly looking at the docker xml template scheme for 6.2 I have issues with the current proposal.

 

the new scheme as it is at the moment doesn't work in pre 6.2 versions.

 

if docker authors want to be fully 6.2 compliant, and not leave those wishing to stay on 6.1 behind, we will end up having to write two sets of tags for every path, variable, device or port mapping.

 

it's my experience that when you increase the complexity, you exponentialy increase the chances of mistakes. miss out one mapping, or make a mistake on either set of tags, you end up with a container that will only work properly on either post or pre 6.2, but not both.

If you use dockerMan to create templates, then there is no problem as its generated files are both v1 and v2 compliant.  Manually creating the xml is a recipe for disaster.  Going forward however this really isn't going to be a big deal as less and less users use 6.1.x / 6.0
Link to comment

To clarify further, a number of maintainers and myself were very vocal in questioning the switch to use of attributes vs extending v1 elements as that design choice didn't particularly make a whole lot of sense.  (Along with redefining the specifications on a few existing attributes)  Unfortunately the powers that be decided that attributes were going to be the way forward

Link to comment

Briefly looking at the docker xml template scheme for 6.2 I have issues with the current proposal.

 

the new scheme as it is at the moment doesn't work in pre 6.2 versions.

 

if docker authors want to be fully 6.2 compliant, and not leave those wishing to stay on 6.1 behind, we will end up having to write two sets of tags for every path, variable, device or port mapping.

 

it's my experience that when you increase the complexity, you exponentialy increase the chances of mistakes. miss out one mapping, or make a mistake on either set of tags, you end up with a container that will only work properly on either post or pre 6.2, but not both.

If you use dockerMan to create templates, then there is no problem as its generated files are both v1 and v2 compliant.  Manually creating the xml is a recipe for disaster.  Going forward however this really isn't going to be a big deal as less and less users use 6.1.x / 6.0

You were trolled by a bot  ;Dhttps://lime-technology.com/forum/index.php?topic=47482.0
Link to comment

Briefly looking at the docker xml template scheme for 6.2 I have issues with the current proposal.

 

the new scheme as it is at the moment doesn't work in pre 6.2 versions.

 

if docker authors want to be fully 6.2 compliant, and not leave those wishing to stay on 6.1 behind, we will end up having to write two sets of tags for every path, variable, device or port mapping.

 

it's my experience that when you increase the complexity, you exponentialy increase the chances of mistakes. miss out one mapping, or make a mistake on either set of tags, you end up with a container that will only work properly on either post or pre 6.2, but not both.

If you use dockerMan to create templates, then there is no problem as its generated files are both v1 and v2 compliant.  Manually creating the xml is a recipe for disaster.  Going forward however this really isn't going to be a big deal as less and less users use 6.1.x / 6.0

You were trolled by a bot  ;Dhttps://lime-technology.com/forum/index.php?topic=47482.0

>:(  >:(  >:(

 

Although what's funnier is that @Sparklyballs pointed out that post to me and also missed the fact that he wrote it in the first place...  (That and you took the time to actually search out the originating thread  :o )

Link to comment

(That and you took the time to actually search out the originating thread  :o )

Select body text of post, right click, search with google, first hit. 5 seconds max. Took longer to copy the thread URL into the reply.  ;D

Well, I guess 5 seconds of your life to make me look like a fool is time well spent  ;D  As I've stated, you are my new nemesis  ;)
Link to comment
  • 1 month later...

Minor change in XML requirements going forward.

 

Either <Description> or <Overview> is required.  Any template (plugin or docker) missing both of these (or empty) will automatically be dropped from CA.  You don't need both either one of them (standard v2 templates have both, v1 only has Description).  

 

If the maintainers can't be bothered to create a description for the app, I can't be bothered to have the app available in CA.  As of this writing, there are 7 apps from various repositories that fall into this category.

 

Any release of CA after 7/22/17 will incorporate this requirement change.

  • Upvote 1
Link to comment

And further refinements / enforcements:  Certain template errors which were originally being fixed by CA are now being reclassified as fatal.

 

These include:

 

Multiple <Repository> entries.  IE: CA used to pick one off the top of its head, and I've now decided that is the wrong way to go about things.

Multiple <PluginURL> entries.  Same as above

 

Anyone can always look at the statistics pop up in CA and click the link for template errors and see what templates have what wrong with them.  CA has numerous tests and fixes for various common mistakes that authors make on their templates, and the stats display will show everything that is happening under the hood.

 

 

 

  • Upvote 1
Link to comment
  • 10 months later...

PSA:

 

Going forward, <TemplateURL> is deprecated  (This is an entry you'll see when creating an entry via dockerMan)

 

After looking at some issues regarding template maintainers changing Support Threads, I discovered that of the maintainers that even set that value, fully 10% of the entries were incorrect, not to mention that tons of the templates (over 50%) never even included the entry in the first place.

 

The application feed for CA will now automatically overwrite any entry that the author sets with the proper entry.

 

In a nutshell, because of the pervasiveness of CA if you decide to populate that entry when creating a template, then you're just wasting your time.

 

FCP will catch all of the errors in already installed containers, and has a built-in fix for this.

Edited by Squid
Link to comment
  • 2 months later...

Hi, I'm looking for docs on how to expose devices like /dev/dri by default in an xml template. It looks like you can do that manually in the UI with the latest unraid.

 

Also https://wiki.unraid.net/DockerTemplateSchema appears to be out of date and doesn't features like <Branch>

Link to comment
7 minutes ago, tmm1 said:

Also https://wiki.unraid.net/DockerTemplateSchema appears to be out of date and doesn't features like <Branch>

Tags like "Branch" are unofficial additions created by CA and documented in the link provided in the OP.  Beyond that, I consider the xml to be an internal data structure and not needed to ever be manually edited, as every thing that you can do by editing the xml can be done via the GUI (except of course for the additional CA tags if needed)

 

7 minutes ago, tmm1 said:

how to expose devices like /dev/dri by default in an xml template

https://forums.unraid.net/topic/57181-real-docker-faq/page/2/#comment-566100

 

You can't do it by default.  Needs to be added to any given template

Link to comment
  • 2 months later...

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

 

 

  • Like 1
Link to comment
26 minutes ago, bling said:

Container.Environment.Variable vs Config[Type=Variable]?

The <Config> elements are the v2 version of the schema.  The <Environment> section and things line <Volume> and <Publish> sections are the v1 version of the schema (and are basically a duplicate of the v2 version minus the attributes it doesn't support)

 

It's still included for backwards compatibility with unRaid v6.0->6.1  (v2 elements take precedence over v1)

 

At the end of the day though, there's zero reason to ever have to manually edit the xml files except to add in any specific CA tags that aren't commonly used enough to be included in the GUI.

 

(And don't get me going on <Description> vs <Overview>)

Link to comment
  • 1 month later...

A new tag for your xml templates is available.

 

<multiLanguage>true</multiLanguage>

Adding this tag is a manual edit to your template.  dockerMan does NOT have the option to add this tag in.

 

 

If this line is in your template, CA (versions after unRaid 6.9.0-beta 2 is released) will show the user (if they click on the app's icon or the more info icon) that the application itself is multi-language compatible.  Use this where the app's GUI allows the user to easily switch between languages (eg: sabnzbd)

Link to comment
  • 4 months later...

How would I test out if my XML works as intended without submitting? Also how would I submit it? Where do I host the XML? 

 

Much of this information is hard to find as the documentation is scattered across multiple threads in multiple categories. Would be so much better if this info would be hosted in the plugin itself on its own page, "How to publish". 

Link to comment

Docker - Add Container, select your template

21 minutes ago, BoKKeR said:

Also how would I submit it? Where do I host the XML? 

 

Much of this information is hard to find as the documentation is scattered across multiple threads in multiple categories. Would be so much better if this info would be hosted in the plugin itself on its own page, "How to publish". 

https://forums.unraid.net/topic/57181-docker-faq/?tab=comments#comment-566084

 

Link to comment
  • 2 months later...
  • Squid pinned this topic

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.