Have App templates be proper templates

[ericmorand]

Is your feature request related to a problem? Please describe

Currently, App templates are very limited in what they allow template providers to do. Typically, it is not possible to use a variable to construct a label, or a command. This is because variables are basically only environment variables, which make them limited to what Docker / Compose / Swarm are able to do with them - i.e. they are evaluated when the container is created.

Describe the solution you'd like

What I would love is that templates are actual templates - i.e. a set of variables and a string which, when combined, result to the actual manifest that will be used to create the container.

In a nutshell, a template would consist of:

• a title (as of today)
• a type (as of today)
• an image (as of today)
• some variables (as of today's env attribubte, only renamed for clarity)
• a string or a structured object that accepts those variables using mustache syntax

An example:

{
  "templates": [
    {
      "title": "Foo",
      "type": "1",
      "image": "foo:latest",
      "variables": [
        {
          "name": "var1",
          "label": "Variable #1",
          "description": "The first variable"
        },
        {
          "name": "var2",
          "label": "Variable #2",
          "description": "The second value",
          "default": "Whatever we want"
        }
      ],
      "manifest": {
        "environment": {
          "FOO_VAR1": "{{ var1 }}",
          "FOO_SOMETHING_ARBITRARY": "whatever"
        },
        "labels": [
          {
            "name": "variable.2",
            "value": "{{ var2 }}"
          }
        ]
      }
    }
  ]
}

Assuming the name of the deployed container is foo, the picked network id bridge, var1 is set to "ONE", and var2 is set to "TWO", this template would generate the following compose manifest, which would then be used by portainer to deploy the container:

services:
  foo:
    image: foo:latest
    networks:
      - bridge
    environment:
      FOO_VAR1: "ONE"
      FOO_SOMETHING_ARBITRARY: "whatever"
    labels:
      - "variable.2=TWO"

As you can see, there is a difference between the variables, which are template-related, and environment variables, which are manifest-related. The template is used to generate the manifest, which would allow us to provide flexible templates, entirely driven by the input provided when creating a container or a stack.

Describe alternatives you've considered

I didn't find any practical way to overcome the current limitations. But I may have missed something.

Additional context

See next comment for the proof of concept.

[ericmorand]

I did setup a proof of concept, that is capable of supporting such templates:

{
    "version": "3",
    "templates": [
        {
            "type": 1,
            "title": "Debian Slim",
            "description": "A proof of concept of manifest templating",
            "categories": [
                "foo",
                "bar"
            ],
            "platform": "linux",
            "image": "debian:bookworm-slim",
            "env": [
                {
                    "name": "command",
                    "label": "The command to execute",
                    "default": "env"
                },
                {
                    "name": "environmentVariableFromVariable",
                    "label": "Environment variable from variable",
                    "default": "environment variable built at compile time from a variable"
                }
            ],
            "configuration": {
                "command": "{{ command }}",
                "environment": {
                    "ENV_VARIABLE_FROM_MANIFEST": "Hard coded",
                    "ENV_VARIABLE_FROM_VARIABLE": "{{ environmentVariableFromVariable }}"
                }
            }
        }
    ]
}

As you can see, there is an additional optional attribute named configuration which purpose is to hold the configuration that, once built from the env values, will be used to deploy the container. It enables some proper templating support:

• The end-user provides the values of the exposed variables (env)
• The template renders the manifest using mustache and the passed values

It permits such things as:

Here, the command to execute is driven by a variable, just like the content of one of the environment variable - the other one being hard-coded in the JSON file.

The deployed container looks like this, as expected:

For this demo, I only focused on the command and the environment variables, but every single attribute that a manifest consists of is templateable - including labels.

The surface of changes to make this solution works is very small - only a few files as you can see here: https://gitlab.com/eric.morand/portainer/-/compare/develop...actual-template. And there is no breaking change at all: if the optional configuration attribute is missing, the current behaviour applies.

@Nick-Portainer, do you think it is worth exploring this proposal? I have been using a custom version of Portainer for a few hours now, and have demonstrated it to my team, and we all agree that it makes things much easier for us. Typically, having the traefik labels generated from the input data (including the name and hostname) is a godsend.