DockerTemplateSchema

From unRAID
Jump to: navigation, search

Docker Template Schema

(NOTE: The schema as described here is only compatible with unRaid v6.2+ In order to maintain compatibility with unRaid 6.0.x / 6.1.x you should use the schema as described here: http://lime-technology.com/forum/index.php?topic=40299.0 (Note: even under 6.2 there are additional schema entries described in that link that are usable (and in some cases highly recommended) for use by Community Applications)


As many of you know, templates are the preferred way to distribute and deploy Docker containers in unRAID. The language used to write templates for unRAID is XML, a well proven and established markup language that is both extensible and human readable, making it perfect for the task.

Notes for Community Applications (CA) compatibility

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.

Below are the supported elements:

Name

This is the default container's name, and work as a suggestion for the user.

Attributes:

  • Default: this is the default value for this element.
 <?xml version="1.0" encoding="utf-8"?>
 <Container version="2">
   <Name Default="Sync">Sync</Name>
 </Container>

 


Squid's Comment: The attributes do not appear to be implemented by dockerMan. Use instead

<Name>Sync</Name>

Overview

In this element, you can add a small description of the application, like it's features.

 <?xml version="1.0" encoding="utf-8"?>
 <Container version="2">
   <Overview>
    BitTorrent Sync, or simply - Sync - is an application for data synchronization. Its primary goal is to keep designated folder content same on 2 or more devices 
    / computers.As soon as something changes on one computer, change (would it be changed content of a file, file renaming or deletion, etc.) should be 
    propagated to all other computer(s) that want to keep the folder synchronized. Sync is available for a bunch of platforms, both desktop and mobile, which gives 
    a good usage flexibility.
   </Overview>
 </Container>

 

Registry

This element stores the container's respective Docker Registry URL. This is used to retrieve update information.

 <?xml version="1.0" encoding="utf-8"?>
 <Container version="2">
   <Registry>https://registry.hub.docker.com/u/limetech/sync/</Registry>
 </Container>

 

Repository

This element stores the container's repository, and is normally composed by the Docker Registry username and the container's name (user/container), or username, container's name and label (user/container:label).

 <?xml version="1.0" encoding="utf-8"?>
 <Container version="2">
   <Repository>limetech/sync</Repository>
 </Container>

 

Privileged

By default, Docker containers are “unprivileged” and cannot, for example, run a Docker daemon inside a Docker container. This is because by default a container is not allowed to access any devices, but a “privileged” container is given access to all devices. See more at: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities

 <?xml version="1.0" encoding="utf-8"?>
 <Container version="2">
   <Privileged>false</Privileged>
 </Container>

 

Support

This element holds an URL for a forum's support thread.

 <?xml version="1.0" encoding="utf-8"?>
 <Container version="2">
   <Support>http://lime-technology.com/forum/index.php?topic=40654.0</Support>
 </Container>

 

Network

This element holds all the info about container's network.

Values

  • Bridge: this is Docker's default option, where all the network interactions happen behind a NAT layer, which has a performance cost. In bridge mode, only mapped ports will be exposed on unRAID's network address.
  • Host: Explaining text
  • None: Explaining text

Attributes:

  • Default: this is the default value for this element.
 <?xml version="1.0" encoding="utf-8"?>
 <Container version="2">
   <Network Default="host">bridge</Network>
 </Container>

Squid's Edit: The attribute does not appear to be implemented. Use instead

<Network>bridge</Network>

WebUI

The WebUI element holds a mask for the web management interface of the container's main application.
 <?xml version="1.0" encoding="utf-8"?>
 <Container version="2">
   <WebUI>http://[IP]:[PORT:32400]/web/index.html</WebUI>
 </Container>

Icon

The Icon element stores a URL for the icon that is exhibited on Web Interface.
 <?xml version="1.0" encoding="utf-8"?>
 <Container version="2">
   <Icon>http://d2631fvi2jdnb6.cloudfront.net/docker/limetech/plex.png</Icon>
 </Container>

Category

The Category element can be populated with the following categories: and/or categories:subcategories, followed by a blank space:

Backup:, Cloud:, Downloaders:, HomeAutomation:, Productivity:, Tools:, Tools:System, Other:, MediaApp:Video, MediaApp:Music, MediaApp:Books, MediaApp:Photos, MediaApp:Other, MediaServer:Video, MediaServer:Music, MediaServer:Books, MediaServer:Photos, MediaServer:Other, Network:Web, Network:DNS, Network:FTP, Network:Proxy, Network:Voip, Network:Management, Network:Other, Network:Messenger, Status:Stable, Status:Beta
 <?xml version="1.0" encoding="utf-8"?>
 <Container version="2">
   <Category>MediaApp:Music MediaServer:Photos Status:Stable</Category>
 </Container>

Note: The "official" Category entries will always be given by the Application Template Categorizer plugin (http://lime-technology.com/forum/index.php?topic=40111.0) and in the event of any discrepancies between the entry described here, and the entry returned by the plugin, the plugin version will take precedence

Config

The Config element holds all configuration needed to make the inside app work.

Each Config element has several attributes. Some of them have the same role across all types, like Name, Description and , but some has different functions depending of the Type.

Name: The Name attribute consists of a title to that configuration that should summarize the the role of that setting, like WebUI Port, Download Dir etc.

Target: The Target attribute holds the container's side of settings. Example: If you have an App that has a web configuration page on port 8080, you could create a Config element with WebUI Port Name and 8080 as it's Target.


Display: The Display attribute controls how each Config element is presented in the Basic View. You can set a Config as Always (always) and Advanced (advanced). You can also hide the Edit Buttons that appear on the right side of each settings input with always-hide and advanced-hide. Please note that all Display configuration is override on if [Advanced View]] is toggled.

Config Types:


For CA compatibility, do not include any of the extra newlines. All attributes should be on the same line as the element, separated by a space, as per the generated files from dockerMan

There are many config types available to template authors:

 

1) Path

A Path Config element holds information about a Docker volume mapping.

Value:

The value of this element is the path chosen by the user.

Attributes:

  • Name: This is the title shown to the left of the input, like Config Directory, TV Shows, Movies etc...
  • Target: This is the path that will be available from inside the container, e.g., /config, /tvshows, /music, /movies etc...
  • Default: This is the default path for this element.
  • Mode: This attribute value can be rw for read/write permissions, or ro for read-only permissions.
  • Description: This is a small description of this path settings and usage.
  • Display: This attribute will be visible to the user always, advanced view, or if it will be hidden from the user regardless of basic/advanced view mode. Default: always.
  • Required: If this attribute is required, this must be set to true; otherwise, set it to false (default).


 <?xml version="1.0" encoding="utf-8"?>
 <Container version="2">
   <Config 
       Type="Path" 
       Name="Config directory" 
       Target="/config" 
       Default="/mnt/user/appdata/PMS" 
       Mode="rw" 
       Description="This is where PMS will store it's databases and configuration."
       Required="true">/mnt/user/appdata/PMS</Config>
 </Container>
 

2) Variable

A Variable Config element holds information about a Docker environment variable.

Value:

The value of this variable according to user's input.

Attributes:

  • Name: This is the title shown to the left of the input, like Login Name, Login password etc...
  • Target: This is the variable name that will be available inside the container, USERNAME, PASSWORD etc...
  • Default: This is the default value for this element.
  • Description: This is a small description of this path settings and usage. Default: nothing.
  • Display: This attribute will be visible to the user always, advanced view, or if it will be hidden from the user regardless of basic/advanced view mode. Default: always.
  • Required: If this attribute is required, this must be set to true. Default: false.
  • Mask: If set to true, it will mask the user's input. Useful for password input, Default: false.
 <?xml version="1.0" encoding="utf-8"?>
 <Container version="2">
   <Config 
       Type="Variable" 
       Name="Plex Pass Username" 
       Target="PLEXPASS_USERNAME" 
       Default="" 
       Description="Plex Pass Username" 
       Mask="false" 
       Display="advanced" 
       Required="false">Username</Config>
 </Container>

 

3) Port

A Port Config element holds information about a Docker exposed port, and is only relevant when used in conjunction with bridge network mode.

Value:

The host correspondent of this port, according to user's input.

Attributes:

  • Name: This is the title shown to the left of the input, like Web Interface Port, Service Port, HTTPS Port etc...
  • Target: This is the port number that will be exposed from inside the container, like 80, 443, 8080 etc...
  • Default: This is the default value for this element.
  • Mode: This attribute value can be tcp for TCP protocol, or udp for UDP protocol.
  • Description: This is a small description of this port settings and usage. Default: nothing.
  • Display: This attribute will be visible to the user always, advanced view, or if it will be hidden from the user regardless of basic/advanced view mode. Default: always.
  • Required: If this attribute is required, this must be set to true. Default: false.
 <?xml version="1.0" encoding="utf-8"?>
 <Container version="2">
   <Config 
       Type="Port" 
       Name="Plex Web UI" 
       Target="32400" 
       Default="32400" 
       Mode="tcp" 
       Description="This is PMS Web UI Port, and is used to access and configure your media library." 
       Display="always" 
       Required="true">32400</Config>
 </Container>