Docker Template XML Schema

[Squid]

EDIT: It looks like all/most of the links within this post are not functional.  However, they would all either link to another post within this thread or to a post within the Application Categorizer plugin support thread or to a post within CA.  Reply to this thread if you have any questions about the optional tags.

 

CA relies upon a third party parser and hosting of the template author's xml files that is out of the author of CAs control. Because of this, the only supported XML format is that which is generated by unRaid's docker tab when hitting SAVE on the template. Any manual editing of the XML files may present compatibility issues for CA and if they turn out to be incompatible, will result in the template being blacklisted within CA until brought into conformity with the dockerMan generated files. As an example, the extra spacing on the various Config element attributes is incompatible with the third party parser and will result in either errors or incorrect entries being made when adding the container through CA. dockerMan does not generate the extra spacing as listed below, and CA has no problem with dockerMan's generated files.

 

With the changes to the docker template XML being introduced by the Community Repositories and Community Applications plugins, I figured that those changes should be documented somewhere rather than being buried in various threads.

 

The official XML (as generated by dockerMan) is as follows:  (probably described somewhere in this thread: http://lime-technology.com/forum/index.php?topic=33965.0 - TLDR

<?xml version="1.0" encoding="utf-8"?>
<Container>
  <Name>Pints</Name>
  <Description>Raspberry Pints, beer tap display app[br]IMPORTANT :- YOU MUST CHANGE THE HOST PORT BELOW</Description>
  <Registry>https://registry.hub.docker.com/u/sparklyballs/pints/</Registry>
  <Repository>sparklyballs/pints</Repository>
  <BindTime>true</BindTime>
  <Privileged>false</Privileged>
  <Environment/>
  <Networking>
    <Mode>bridge</Mode>
    <Publish>
      <Port>
        <HostPort>81</HostPort>
        <ContainerPort>80</ContainerPort>
        <Protocol>tcp</Protocol>
      </Port>
    </Publish>
  </Networking>
  <Data>
    <Volume>
      <HostDir>/mnt/cache/appdata/pints/www</HostDir>
      <ContainerDir>/var/www/Pints</ContainerDir>
      <Mode>rw</Mode>
    </Volume>
    <Volume>
      <HostDir>/mnt/cache/appdata/pints/config</HostDir>
      <ContainerDir>/config</ContainerDir>
      <Mode>rw</Mode>
    </Volume>
  </Data>
  <Version>05616fd2</Version>
  <WebUI>http://[iP]:[PORT:80]/</WebUI>
  <Banner>http://whatsmybeeragain.com/wp-content/uploads/2013/12/Whats-My-Beer-Logo-Banner-2-01-e1318366883801.png</Banner>
  <Icon>http://fullersbarbeerfest.co.uk/files/6113/8705/6693/light-beer.png</Icon>
  <ExtraParams></ExtraParams>
</Container>

 

EDIT: the above is the v1 specification  Unraid versions 6.2+ support v2 which have the ports and paths defined via <Config> entries and take precedence over v1.  Unraid 6.10+ no longer will generate the legacy v1 entries (although when installing an app it will read them)

 

Note that for CA / Apps Tab, either <Description> or <Overview> must be present and not empty.  IE: Its required.

 

Additionally, there are also some (currently) unofficial entries.

 

<Support> Contains a link to a support thread for the container.  http://lime-technology.com/forum/index.php?topic=39106.msg365627#msg365627 

 

<Overview> This is the same thing as <Description>  if <Overview> is present, then <Description> is completely ignored

 

<Beta>, <Category> (Both optional but highly recommended).  These entries are created by this plugin: http://lime-technology.com/forum/index.php?topic=40111.0

 

<Date> This entry contains the date the container has been created and/or updated http://lime-technology.com/forum/index.php?topic=40111.msg381735#msg381735.  If this tag is not present, but the <DateInstalled> tag is present, then the latter is used.

 

<Changes> This entry contains a changelog for the container.  http://lime-technology.com/forum/index.php?topic=40111.msg379576#msg379576

 

<Project> The entry contains a url to the project page (home page) for the container (eg: https://plex.tv)  http://lime-technology.com/forum/index.php?topic=40299.msg394762#msg394762

 

<Licence> or <License>  Optionally displays licence information for the app  http://lime-technology.com/forum/index.php?topic=40262.msg444243#msg444243

 

 

<Branch> (docker app only) will allow CA to ask the user which branch of the application to install.  See here: http://lime-technology.com/forum/index.php?topic=40299.msg495429#msg495429

 

<ExtraSearchTerms> extra search terms to use for the app see https://forums.unraid.net/topic/38619-docker-template-xml-schema/page/3/?tab=comments#comment-941891

 

<Requires> any additional requirements on the user's system the app may require https://forums.unraid.net/topic/38619-docker-template-xml-schema/page/3/?tab=comments#comment-1015826  Unraid 6.10 includes this entry when editing / creating a template in authoring mode

 

<ReadMe> https://forums.unraid.net/topic/38619-docker-template-xml-schema/page/4/?tab=comments#comment-1051557 Unraid 6.10-rc3+ includes this entry when editing / creating a template in authoring mode

 

<Screenshot> https://forums.unraid.net/topic/38619-docker-template-xml-schema/page/4/?tab=comments#comment-1051850

This specifies a screenshot (or multiple screenshots) to include in the sidebar for the app

 

Additionally, CA supports placing an optional donate button at the bottom of the popup changelogs and full descriptions.  The tags associated with this are:

 

 

<DonateText> A short blurb of why to donate (eg: Server's Cost Money, I'm paying for a divorce, I'm out of beer, etc

<DonateLink> A link to take you to the actual website where the donations are handled

2/21/21 - Donation links within templates are now deprecated, in favour of the links being present in the profiles.  This means that all you have to do is fill out the appropriate links within the CA profile and those links will get carried over to the templates automatically.  

 

NOTE that & are disallowed in entries.  You will need to replace them with this: &amp; Failure to do this will result in your application not displaying within CA (And not being able to be installed via dockerMan

 

<DonateText> is optional, but both <DonateLink> and <DonateImg> are mandatory for this to appear (One or the other missing will result in the button not appearing)

 

 

Side Note

 

Only the tags which are listed in this thread (and the companion PluginXML thead)are official / semi-official / unofficial.  If you happen to look at the XML's which are generated by CA and passed through to dockerMan at installation, there are many other tags that are contained within that are utilized only for CA's internal purposes.  Do not utilize them.

[NAS]

Good work.

 

If we are capturing suggestions I still maintain every field should be allowed a corresponding description field that can be used to descriptive what the field is.

 

I dont know what the best method of adding this would be though.

[Squid]

Do you mean help text?

[Squid]

I've just added in support within CA for an optional <Project> entry

 

This entry should be a URL to (ideally) the home page for an application.  eg: https://plex.tv or https://couchpota.to/

 

See one of limetech's templates or one of linuxserver's for an example

[NAS]

Do you mean help text?

 

Sorry I missed your reply. Essentially just a description field so that devs can explain what each and every element is for. If you look at some of the current global descriptions they often have per field descriptions bundled together as it t stands. Its i inconsistent and ugly and for the target audience of "non technical app consumers" its not idea.

 

Also perhaps most theis schema to github  to track chnages?

[sparklyballs]

I get all nervy when you start talking about new tags, adding them to 50+ xml's is a pain, lol

[Squid]

I get all nervy when you start talking about new tags, adding them to 50+ xml's is a pain, lol

I'll keep table mode if you add the tags   

 

Seriously though, every single tag I've added has always been optional (even categories were optional).  But, this one will have some benefit to the end user, (and I've even updated table mode to support it, albeit through a pop up)

[NAS]

I get all nervy when you start talking about new tags, adding them to 50+ xml's is a pain, lol

 

Thats a very fair point and anything XML related is always just that bit harder (as in bloody hard) to automate on the command line. I wonder if we could write a version converter. (I pretty much hate XML the amount of time ive wasted trying to manipulate stuff is scary)

 

Content wise though the new description field is exactly the kind of thing normal every day users could do pull requests for which opens the door for a whole new level of contributors which i like.

[Squid]

Thats a very fair point and anything XML related is always just that bit harder (as in bloody hard) to automate on the command line. I wonder if we could write a version converter. (I pretty much hate XML the amount of time ive wasted trying to manipulate stuff is scary)

 

Content wise though the new description field is exactly the kind of thing normal every day users could do pull requests for which opens the door for a whole new level of contributors which i like.

And for that same reason is why I also try and avoid them (or at the very least make sure that they are optional).  Even the categories tag was optional, but so highly recommended and error prone if they had to be manually updated, I had to create a plugin to create the specific line (which btw could also modify the appropriate xml file).

 

Content wise, your description field field fits the fact that it would be optional, and also of a huge benefit.  Realistically, all it requires is a small change to dockerMan to implement.  Unfortunately because the tag must be implemented within a core OS component, it is up to LT to designate and implement (which btw I have received a PM from one of their team members asking what I thought about that very proposal a few months ago) so it is on their radar, but probably at the present time not the biggest priority that they have.

 

A similar item would be some sort of automatic host volume path filling out.  I briefly tried having an experimental feature within CA to accomplish this, but ultimately decided to drop it because it also requires a tag change in order to accomplish it correctly, and ultimately the implementation once again has to be within dockerMan.

 

This snippet of a post from jonp however fills me with confidence:

 

We are also focusing on not only making things better with new features, but also on making things much easier for new users.

 

Since docker is overwhelmingly the favorite new feature of 6.x (according to LT's poll), and arguably has a big learning curve for new users due to missing tags (your description, and I would propose a tag to assist in automatic host volume populating), I wouldn't be surprised if this gets implemented shortly.  It also has the benefit of being IMHO far less labour intensive for LT to implement and test than the current emphasis on VM's.  Especially since docker is being "sold" as turn-key applications to new users, and yet the threads are filled with questions about just getting them installed.

 

 

PS  Also changed the OP to better organize all the optional tags.

[NAS]

Xslt(s) are your friend. It should be cake to write one that adds new tags with default values into xml files based off the old schema.

 

Sounds like a plan then. I think we should take this to github, create a stable branch based on current XML spec then an unstable based on the new spec.

 

I dont know who owns the layout copyright but perhaps they could be asked to make it GPL and pass it into this new project.

[Squid]

Almost forgot also.  Never bothered to actually lookup valid characters in XML, but "&" can't be in there unless its within a CDATA section.  Bit a couple of the template authors, and myself more than once.  Not sure about using &codes, but & by itself and in

<Sample>this & that</Sample>

 

Throws the system for a loop.

[trurl]

Almost forgot also.  Never bothered to actually lookup valid characters in XML, but "&" can't be in there unless its within a CDATA section.  Bit a couple of the template authors, and myself more than once.  Not sure about using &codes, but & by itself and in

<Sample>this & that</Sample>

 

Throws the system for a loop.

&codes are indispensible. Similar to html

"   "
'   '
<   <
>   >
&   &

[Squid]

Almost forgot also.  Never bothered to actually lookup valid characters in XML, but "&" can't be in there unless its within a CDATA section.  Bit a couple of the template authors, and myself more than once.  Not sure about using &codes, but & by itself and in

<Sample>this & that</Sample>

 

Throws the system for a loop.

&codes are indispensible. Similar to html

"   "
'   '
<   <
>   >
&   &

Yeah, except that putting "This & That" within HTML won't cause a fatal error.

[trurl]

Almost forgot also.  Never bothered to actually lookup valid characters in XML, but "&" can't be in there unless its within a CDATA section.  Bit a couple of the template authors, and myself more than once.  Not sure about using &codes, but & by itself and in

<Sample>this & that</Sample>

 

Throws the system for a loop.

&codes are indispensible. Similar to html

"   "
'   '
<   <
>   >
&   &

Yeah, except that putting "This & That" within HTML won't cause a fatal error.

<Whatever>"This & That"</Whatever>

[Squid]

Almost forgot also.  Never bothered to actually lookup valid characters in XML, but "&" can't be in there unless its within a CDATA section.  Bit a couple of the template authors, and myself more than once.  Not sure about using &codes, but & by itself and in

<Sample>this & that</Sample>

 

Throws the system for a loop.

&codes are indispensible. Similar to html

"   "
'   '
<   <
>   >
&   &

Yeah, except that putting "This & That" within HTML won't cause a fatal error.

<Whatever>"This & That"</Whatever>

Understood.  Point being is that its a common mistake that brings the system down.

[Squid]

With an eye towards the future, I've implemented a couple new tags for both docker containers and plugin templates for CA

 

<MinVer> and <MaxVer>

 

These specify the minimum unRaid version and the maximum unRaid version that the container / plugin will work with

 

If these tags are not present in the template, they will default to MinVer of 6.0 for containers (6.1 for plugins) and MaxVer will be whatever the current version of unRaid is.

 

If in the future a template incorporates these tags and the version of unRaid which the user is using lies outside of the specified range, then that particular app will not be allowed to be installed.

 

(Additionally, CA moderators also have the ability to set these values for any particular template if the author goes MIA)

 

Note that currently there is NO reason for any template author to update their templates to include these new tags, as the default values already cover what all current items in CA are capable of, and I'm probably not going to release the update to CA until 6.2 get released Update Released

[gfjardim]

Additionally, there are also some (currently) unofficial entries.

 

<Support> Contains a link to a support thread for the container.  http://lime-technology.com/forum/index.php?topic=39106.msg365627#msg365627

<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

<Beta>, <Category> (Both optional but highly recommended).  These entries are created by this plugin: http://lime-technology.com/forum/index.php?topic=40111.0

<Date> This entry contains the date the container has been created and/or updated http://lime-technology.com/forum/index.php?topic=40111.msg381735#msg381735

<Changes> This entry contains a changelog for the container.  http://lime-technology.com/forum/index.php?topic=40111.msg379576#msg379576

<Project> The entry contains a url to the project page (home page) for the container (eg: https://plex.tv)  http://lime-technology.com/forum/index.php?topic=40299.msg394762#msg394762

<Licence> or <License>  Optionally displays licence information for the app  http://lime-technology.com/forum/index.php?topic=40262.msg444243#msg444243

 

Squid, it's time to add things in Docker Manager. My two cents is that we could ditch <Beta>(add that to <Categories> element), move <Date> to <Version>(YYYY.MM.DD format like it's done in plugins) and adopt <Changes> as a history log. Not sure about <License> or <Project> tho.

 

Please I need enlightenment me about <MinVer> and <MaxVer>. How are they important?

[Squid]

Additionally, there are also some (currently) unofficial entries.

 

<Support> Contains a link to a support thread for the container.  http://lime-technology.com/forum/index.php?topic=39106.msg365627#msg365627

<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

<Beta>, <Category> (Both optional but highly recommended).  These entries are created by this plugin: http://lime-technology.com/forum/index.php?topic=40111.0

<Date> This entry contains the date the container has been created and/or updated http://lime-technology.com/forum/index.php?topic=40111.msg381735#msg381735

<Changes> This entry contains a changelog for the container.  http://lime-technology.com/forum/index.php?topic=40111.msg379576#msg379576

<Project> The entry contains a url to the project page (home page) for the container (eg: https://plex.tv)  http://lime-technology.com/forum/index.php?topic=40299.msg394762#msg394762

<Licence> or <License>  Optionally displays licence information for the app  http://lime-technology.com/forum/index.php?topic=40262.msg444243#msg444243

 

Squid, it's time to add things in Docker Manager. My two cents is that we could ditch <Beta>(add that to <Categories> element), move <Date> to <Version>(YYYY.MM.DD format like it's done in plugins) and adopt <Changes> as a history log. Not sure about <License> or <Project> tho.

 

Please I need enlightenment me about <MinVer> and <MaxVer>. How are they important?

MinVer and MaxVer were both added in conjunction with plugin integration into CA, but they are also usable on containers.

 

Basically all they are is set the minimum unRaid version and maximum unraid version that a particular app (container or plugin) are capable of running on.  Execution is denied by default otherwise.

 

More important to plugins than to containers.

 

<Date> accepts any valid date that can be parsed via strtotime() and does not have a set enforced format.  However, with all containers and authors currently using it, an outright move wouldn't be recommended, rather support of both.  (and even there, but I believe that there is also no set format for <Version> in plugins, but its rather a strict greater than or less than comparison done (ie: I think that I could have <Version>1</Version> and the plugin manager would handle it perfectly.

 

<Beta> I don't think of a particularily a category per se, hence why it's separated

 

[Squid]

Additionally, there are also some (currently) unofficial entries.

 

<Support> Contains a link to a support thread for the container.  http://lime-technology.com/forum/index.php?topic=39106.msg365627#msg365627

<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

<Beta>, <Category> (Both optional but highly recommended).  These entries are created by this plugin: http://lime-technology.com/forum/index.php?topic=40111.0

<Date> This entry contains the date the container has been created and/or updated http://lime-technology.com/forum/index.php?topic=40111.msg381735#msg381735

<Changes> This entry contains a changelog for the container.  http://lime-technology.com/forum/index.php?topic=40111.msg379576#msg379576

<Project> The entry contains a url to the project page (home page) for the container (eg: https://plex.tv)  http://lime-technology.com/forum/index.php?topic=40299.msg394762#msg394762

<Licence> or <License>  Optionally displays licence information for the app  http://lime-technology.com/forum/index.php?topic=40262.msg444243#msg444243

 

Squid, it's time to add things in Docker Manager. My two cents is that we could ditch <Beta>(add that to <Categories> element), move <Date> to <Version>(YYYY.MM.DD format like it's done in plugins) and adopt <Changes> as a history log. Not sure about <License> or <Project> tho.

 

Please I need enlightenment me about <MinVer> and <MaxVer>. How are they important?

I also don't quite understand why you're proposing this anyways?  All of those entries (especially categories and beta) are internal use in CA anyways, and I don't particularily see them being used within dockerMan itself.

[gfjardim]

 

I also don't quite understand why you're proposing this anyways?  All of those entries (especially categories and beta) are internal use in CA anyways, and I don't particularily see them being used within dockerMan itself.

 

Because I want to make things easier for both users and developers. Why force the manual edit of a template if we can make that available from within the webgui? The "Dry Run" will expose the XML, that can be copied/pasted in any text editor directly, so there will be no need to edit by hand lots of code...

 

I'll add a dropdown menu for all those categories you have in place at the Categorizer plugin,and add a Status:Beta|Stable category there.

 

Other thing I'm considering implementing is the ability to update the current user template with the default template on GitHub. It will work like this:

 

I'll add a <Template> element with the template URL. Once you hit Edit, it will download the default template, add any "Config" element that is new and update all attributes like Name, Mode etc... This way, we can keep things in sync between developers and users.

 

What do you think?

[sparklyballs]

 

I also don't quite understand why you're proposing this anyways?  All of those entries (especially categories and beta) are internal use in CA anyways, and I don't particularily see them being used within dockerMan itself.

 

Because I want to make things easier for both users and developers. Why force the manual edit of a template if we can make that available from within the webgui? The "Dry Run" will expose the XML, that can be copied/pasted in any text editor directly, so there will be no need to edit by hand lots of code...

 

I'll add a dropdown menu for all those categories you have in place at the Categorizer plugin,and add a Status:Beta|Stable category there.

 

Other thing I'm considering implementing is the ability to update the current user template with the default template on GitHub. It will work like this:

 

I'll add a <Template> element with the template URL. Once you hit Edit, it will download the default template, add any "Config" element that is new and update all attributes like Name, Mode etc... This way, we can keep things in sync between developers and users.

 

What do you think?

 

we (linuxserver.io) have 50 + containers , i don't even know how many i personally have as well. that's a helluva lot of work to make those kinds of changes via cumbersome webui interaction.

as squidly rightly said, in the real world we are going to be doing manual edits because it's just the easiest way to manage all our templates.

 

[Kode]

Not to mention not all our contributors use unRAID, so wouldn't be able to use "Dry Run" when helping out creating templates

[gfjardim]

 

we (linuxserver.io) have 50 + containers , i don't even know how many i personally have as well. that's a helluva lot of work to make those kinds of changes via cumbersome webui interaction.

as squidly rightly said, in the real world we are going to be doing manual edits because it's just the easiest way to manage all our templates.

 

Yes, I know it's a lot of work, but the current format + CA own elements is a hell to support, to begin with. Plus, they don't survive the Docker Manager edit, so user templates lack a lot of info. A possible future step is to include something like CA into unRAID itself, so we need to make the changes right now to make it future proof.

 

And if you don't want to change your templates you don't have to, the Docker Manager will remain backward-compatible with them, so no muss no fuss there.

 

Not to mention not all our contributors use unRAID, so wouldn't be able to use "Dry Run" when helping out creating templates

 

In a collective of developers like LS, some tasks can always be delegated, if I'm not mistaken.

[sparklyballs]

 

 

 

 

In a collective of developers like LS, some tasks can always be delegated, if I'm not mistaken.

 

only to those with unraid, now it seems.....

[Squid]

 

we (linuxserver.io) have 50 + containers , i don't even know how many i personally have as well. that's a helluva lot of work to make those kinds of changes via cumbersome webui interaction.

as squidly rightly said, in the real world we are going to be doing manual edits because it's just the easiest way to manage all our templates.

 

Yes, I know it's a lot of work, but the current format + CA own elements is a hell to support, to begin with. Plus, they don't survive the Docker Manager edit, so user templates lack a lot of info. A possible future step is to include something like CA into unRAID itself, so we need to make the changes right now to make it future proof.

 

And if you don't want to change your templates you don't have to, the Docker Manager will remain backward-compatible with them, so no muss no fuss there.

 

Not to mention not all our contributors use unRAID, so wouldn't be able to use "Dry Run" when helping out creating templates

 

In a collective of developers like LS, some tasks can always be delegated, if I'm not mistaken.

I can see where integrating the categorizer into dockerMan would have advantages, since every maintainer (plugin or container) has to ultimately use it.

 

I don't believe that you'd integrate the additional tags required for plugin operation, but that's not a big deal.  Those maintainers can still use the categorizer.

 

But, in the case of containers I would personally integrate all of the commonly used unofficial tags (ie: project).  <Changes> you'd probably have a complaint about, since its not markdown, but rather full HTML with syntax changes - (see the link for it).  Changing that formatting would cause nothing but grief since it is VERY commonly used by all the maintainers.

 

Moving Beta into Categories isn't a big deal, and CA would be able to deal with it as necessary.

 

The MinVer and MaxVer were created mainly for plugins, and in the absence of those tags (of which no one uses them with the exception of my own plugins), CA automatically applies MinVer of 6.0 for containers (6.1 for plugins) and MaxVer of the user's unRaid version.  (Additionally, CA's moderation system has the ability to override ANY tag that a maintainer might choose)

 

Since the categorizer is public domain, you can pretty much do anything you want, and legitimizing my unofficial tags is always a plus.

 

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.