Portainer Tools: Merge and Host App Template definitions

Portainer App Templates can be used to easily deploy Docker containers with predefined settings. At the moment it is not possible to add more than one App Template definition URL to Portainer. Merging App Template definitions has to be done by hand.

This application allows you to add your own App Template definitions, merge them with existing ones and host them on your own server. You can set the Portainer App Templates URL from within the application to easily switch App Template definitions.

Prerequisites

• A server with Docker installed
• Portainer v2 installed

The application does not recognize the Portainer v1 App Template definition format.

Installation

Application setup

In the next section you will create the Docker container for the application. After the application is created, in your browser go to http://SERVER_URL:<port on host> to start the application (e.g. http://192.168.0.113:9999).

If you want to be able to set the App Templates URL in Portainer from within the application, you need to provide the PORTAINER_URL, PORTAINER_USERNAME and PORTAINER_PASSWORD environment variables.

Don’t forget to set the PUID and PGID if you use volume host directories (-v parameter) and don’t want permission issues. See below for details. Make sure you create the volume host directories upfront and assign the correct permissions.

Create the application

Here are some examples to help you get started creating the container for the application.

Docker compose

Create the docker-compose.yaml file as below, change the necessary parameters (see below for details) and start the application with docker-compose up -d. More information here.

---
version: '3.3'
services:
    portainer-tools:
        container_name: portainer-tools
        environment:
            - PUID=<puid>
            - PGID=<pgid>
            - SERVER_URL=<application url>
            - PORTAINER_URL=<portainer url>
            - PORTAINER_USERNAME=<portainer username>
            - PORTAINER_PASSWORD=<portainer password>
        ports:
            - <port on host>:9999
        volumes:
            - <path to config on host>:/config
        restart: unless-stopped
        image: technorabilia/portainer-toolsCode language: HTML, XML (xml)

Docker CLI

You can also use docker run to start the application. More information here.

Don’t forget to change the necessary parameters before running the command. See below for details.

docker run -d \
  --name portainer-tools \
  -e PUID=<puid> \
  -e PGID=<pgid> \
  -e SERVER_URL=<application url> \
  -e PORTAINER_URL=<portainer url> \
  -e PORTAINER_USERNAME=<portainer username> \
  -e PORTAINER_PASSWORD=<portainer password> \
  -p <port on host>:9999 \
  -v <path to config on host>:/config \
  --restart unless-stopped \
  technorabilia/portainer-toolsCode language: HTML, XML (xml)

Parameters

Container images are configured using parameters passed at runtime (such as those above). These parameters are separated by a colon and indicate <external>:<internal> respectively. For example, -p 8888:9999 would expose port 9999 from inside the container to be accessible from the host’s IP-address on port 8888 outside the container.

Parameter	Description
-e PUID <puid>	Process User ID. See below for details.
-e PGID <pgid>	Process Group ID. See below for details.
-e SERVER_URL=<application url>	The URL your application will be accessed on (e.g. http://192.168.0.113).
-e PORTAINER_URL=<portainer url>	The URL for Portainer (e.g. http://192.168.0.114:9000). This will default to SERVER_URL:9000 if not provided (e.g. http://192.168.0.113:9000).
-e PORTAINER_USERNAME=<portainer username>	Portainer username.
-e PORTAINER_PASSWORD=<portainer password>	Portainer password.
-p <port on host>:9999	Map port 9999 in the container to the specified port on the Docker host.
-v <path to config on host>:/config \	Store database and templates on the Docker host (e.g. /path/to/portainer-tools/config).

User/Group identifiers

If you use volume host directories (-v parameter), there can be permission issues between the host and the container.

To make sure that there are no permission issues, you can specify the PUID and PGID of the user that owns the volume directory on the host.

To find the values for PUID and PGID, you can use the id [USER] command as follows.

$ id youruser
uid=1024(youruser) gid=128(youruser) groups=128(youruser)Code language: Markdown (markdown)

In this example PUID is 1024 and PGID is 128.

Using the application

When you start the application for the first time, you will see the following on your screen (click to enlarge).

The following App Template definitions are already created at startup.

• Custom – An example App Template definition that you can use to add your own definitions. More info here.
• LinuxServer.io – An App Template definition that holds all applications provided by LinuxServer.io (daily updated!).
• Portainer – This is the default App Template definition provided by Portainer.

A possible scenario can be as follows.

• Create your own App Template definition file based on the Custom or other definitions.
• Upload your own definition file.
• Merge your own definition with other definitions (hosted on your server or elsewhere).
• Select the merged definition and set the App Template definition URL in Portainer.

Although the functionality of the application is pretty self-explanatory, below is a brief explanation of the buttons and its function.

Button	Description
Merge	Merge the selected App Template definitions. Definitions will be merged from top to bottom. If needed, you can change the sort order on the Name/URL column for the desired order. A new definition will be created with the name “Merged” and filename “merged.json”. If a definition already exists with the name “Merged” or filename “merged.json”, that definition will be reused / overwritten.
Upload	Upload your own App Template definition file. This definition file will be hosted on your server.
Add	Add a new App Template definition that is hosted elsewhere.
View	View the App Template definition in the browser.
Set	Set the App Template definition URL in Portainer.
Update	Update the App Template definition. Here you can change the name or the URL of the definition.
Delete	Delete the App Template definition.

Report issues

If you find a problem, you can submit it on GitHub. I will then look at it as soon as possible.

Credits

The use of PUID and PGID was inspired by LinuxServer.io.