advanced/app-templates/format.md
App template definitions are written in JSON. Valid templates consist of an array, and every template definition consists of one element.
A container template element must be a valid JSON object, composed of both mandatory and optional data fields. Here's an example of the format:
{
"version": "2",
"templates": [
{
// template1
},
{
// template2
},
...
]
}
1 = container; 2 = Swarm stack; 3 = Compose stack3 is limited to using the version "2" stack format (this is a docker/libcompose limitation).true = available to admins only; false = available to all users{
"administrator-only": true
}
{
"command": "/bin/bash -c \"echo hello\" && exit 777"
}
Array format:
{
"name": "the name of the environment variable, as supported in the container image (mandatory)",
"label": "label for the input in the UI (mandatory unless set is present)",
"description": "a short description for this input, will be available as a tooltip in the UI (optional)",
"default": "default value associated to the variable (optional)",
"preset": "boolean. If set to true, the UI will not generate an input (optional)",
"select": "an array of possible values, will generate a select input (optional)"
}
Example:
{
"env": [
{
"name": "MYSQL_ROOT_PASSWORD",
"label": "Root password",
"description": "Password used by the root user."
},
{
"name": "ENV_VAR_WITH_DEFAULT_VALUE",
"default": "default_value",
"preset": true
},
{
"name": "ENV_VAR_WITH_SELECT_VALUE",
"label": "An environment variable",
"description": "A description for this env var",
"select": [
{
"text": "Yes, I agree",
"value": "Y",
"default": true
},
{
"text": "No, I disagree",
"value": "N"
},
{
"text": "Maybe",
"value": "YN"
}
],
"description": "Some environment variable."
}
]
}
{
"network": "host"
}
bind property is defined, it will be used as the source of a bind mount. If a readonly property is is defined and = true, the volume will be mounted in readonly mode.{
"volumes": [
{
"container": "/etc/nginx"
},
{
"container": "/usr/share/nginx/html",
"bind": "/var/www",
"readonly": true
}
]
}
8080:) to define the port to be mapped on the host. If the host port is not specified, the Docker host will automatically assign it when starting the container.{
"ports": ["8080:80/tcp", "443/tcp"]
}
name: and "<value>").{
"labels": [
{ "name": "com.example.vendor", "value": "Acme" },
{ "name": "com.example.license", "value": "GPL" },
{ "name": "com.example.version", "value": "1.0" }
]
}
privileged mode. Defaults to false if not specified.true = start the container in privileged mode; false = do not start the container in privileged mode{
"privileged": true
}
foreground mode. Defaults to false if not specified.true = start the container in foreground mode; false = do not start the container in foreground mode{
"interactive": true
}
"always" if no value is specified."always" Always restart the container regardless of the exit status."no" Never automatically restart the container."on-failure" Restart the container only if it exits with a non-zero status."unless-stopped" Always restart the container regardless of the exit status (unless the container was manually stopped).{
"restart_policy": "unless-stopped"
}
{
"hostname": "mycontainername"
}
{
"note": "You can use this field to record extra information about a template."
}
"linux"; "windows"{
"platform": "linux"
}
{
"categories": ["webserver", "open-source"]
}
A stack template element must be a valid JSON object, composed of mandatory and optional data fields. Here's an example of the format:
{
"type": 2,
"title": "CockroachDB",
"description": "CockroachDB cluster",
"note": "Deploys an insecure CockroachDB cluster, please refer to CockroachDB documentation for production deployments.",
"categories": ["database"],
"platform": "linux",
"logo": "https://cloudinovasi.id/assets/img/logos/cockroachdb.png",
"repository": {
"url": "https://github.com/portainer/templates",
"stackfile": "stacks/cockroachdb/docker-stack.yml"
}
}
docker stack deploy. A Compose stack will be deployed using the equivalent of docker-compose.1 = container; 2 = Swarm stack; 3 = Compose stack3 is limited to using the version "2" stack format (this is a docker/libcompose limitation).{% hint style="warning" %} This value must reference a Git repository. {% endhint %}
Object format:
{
"url": "URL of the public git repository (mandatory)",
"stackfile": "Path to the Compose file inside the repository (mandatory)",
}
Example:
{
"url": "https://github.com/portainer/templates",
"stackfile": "stacks/cockroachdb/docker-stack.yml"
}
true = available to admins only; false = available to all users{
"administrator_only": true
}
An input will be generated in the templates view for each element in the array. Depending on the object properties, different types of inputs can be generated (text input, select).
Array format:
{
"name": "the name of the environment variable, as supported in the container image (mandatory)",
"label": "label for the input in the UI (mandatory unless set is present)",
"description": "a short description for this input, will be available as a tooltip in the UI (optional)",
"default": "default value associated to the variable (optional)",
"preset": "boolean. If set to true, the UI will not generate an input (optional)",
"select": "an array of possible values, will generate a select input (optional)"
}
Example:
{
"env": [
{
"name": "MYSQL_ROOT_PASSWORD",
"label": "Root password",
"description": "Password used by the root user."
},
{
"name": "ENV_VAR_WITH_DEFAULT_VALUE",
"default": "default_value",
"preset": true
},
{
"name": "ENV_VAR_WITH_SELECT_VALUE",
"label": "An environment variable",
"description": "A description for this env var",
"select": [
{
"text": "Yes, I agree",
"value": "Y",
"default": true
},
{
"text": "No, I disagree",
"value": "N"
},
{
"text": "Maybe",
"value": "YN"
}
],
"description": "Some environment variable."
}
]
}
{
"note": "You can use this field to record extra information about a template."
}
"linux"; "windows"{ "platform": "linux" }
{
"categories": ["webserver", "open-source"]