Templates

Template definitions are written in JSON.

It must consist of an array with every template definition consisting of one element.

Template definition format

A template element must be a valid JSON object.

Example:

{
  "title": "Nginx",
  "description": "High performance web server",
  "logo": "https://cloudinovasi.id/assets/img/logos/nginx.png",
  "image": "nginx:latest",
  "ports": [
    "80/tcp",
    "443/tcp"
  ]
}

It is composed of multiple fields, some mandatory and some optionals.

title

Title of the template.

This field is mandatory.

description

Description of the template.

This field is mandatory.

image

The Docker image associated to the template. The image tag must be included.

This field is mandatory.

registry

The registry where the Docker image is stored. If not specified, Portainer will use the Dockerhub as the default registry.

This field is optional.

command

The command to run in the container. If not specified, the container will use the default command specified in its Dockerfile.

This field is optional.

Example:

{
  "command": "/bin/bash -c \"echo hello\" && exit 777"
}

env

A JSON array describing the environment variables required by the template. Each element in the array must be a valid JSON object.

An input will be generated in the templates view for each element in the array.

Depending on the value in type field, the view will display a different input. For example, when using the value container for the type field, the UI will display a dropdown with all the running containers. The container hostname will then be inserted as a value in the environment variable.

Supported types:

  • container

This field is optional.

Element format:

{
  "name": "the name of the environment variable, as supported in the container image (mandatory)",
  "label": "label for the input in the UI (mandatory)",
  "type": "only container is available at the moment (optional)",
  "set": "pre-defined value for the variable, will not generate an input in the UI (optional)"
}

Example:

{
  "env": [
    {
      "name": "MYSQL_ROOT_PASSWORD",
      "label": "Root password"
    },
    {
      "name": "MYSQL_USER",
      "label": "MySQL user",
      "set": "myuser"
    },
    {
      "name": "MYSQL_PASSWORD",
      "label": "MySQL password",
      "set": "mypassword"
    }
  ]
}

network

A string corresponding to the name of an existing Docker network.

Will auto-select the network (if it exists) in the templates view.

This field is optional.

Example:

{
  "network": "host"
}

volumes

A JSON array describing the associated volumes of the template. Each element in the array must be a valid JSON string.

For each element in the array, a Docker volume will be created and associated when starting the container.

This field is optional.

Example:

{
  "volumes": ["/var/lib/mysql", "/var/log/mysql"]
}

ports

A JSON array describing the ports exposed by template. Each element in the array must be a valid JSON string specifying the port number in the container and the protocol.

Each port will be automatically bound on the host by Docker when starting the container.

This field is optional.

Example:

{
  "ports": ["80/tcp", "443/tcp"]
}

privileged

Should the container be started in privileged mode. Boolean, will default to false if not specified.

This field is optional.

{
  "privileged": true
}

Build and host your own templates

You can build your own container that will use Nginx to serve the templates definitions.

Clone the Portainer templates repository, edit the templates file, build and run the container:

$ git clone https://github.com/portainer/templates.git portainer-templates
$ cd portainer-templates
# Edit the file templates.json
$ docker build -t portainer-templates .
$ docker run -d -p "8080:80" portainer-templates

Now you can access your templates definitions at http://docker-host:8080/templates.json.

You can also mount the templates.json file inside the container, so you can edit the file and see live changes:

$ docker run -d -p "8080:80" -v "${PWD}/templates.json:/usr/share/nginx/html/templates.json" portainer-templates