How to configure and deploy custom app templates in Container Station 3?

Release date: 2023-03-27

Container Station app templates let you deploy preconfigured containers to your QNAP environment. By default, Container Station provides a collection of QNAP-Verified Templates, but you can add additional custom app templates to meet your specific needs. You can host these custom app templates directly on your QNAP device or on an external web server.

This tutorial explains two methods of hosting custom app templates on your QNAP device, and how to configure Container station to access these custom app templates.

Creating a Custom App Template File

The first step is to create a custom app template file. By default, Container Station provides a list of containers that are verified to work correctly with your QNAP device. You can download and modify QNAP-Verified Templates here, or create a new file yourself.

Note:

You can modify the template file within any text editor.

App Template Format

App template definitions are written in JSON. Valid templates consist of an array, and one or more container template elements. Each container template element is a JSON object that includes any mandatory or optional data fields. The format should be similar to the following example:

{
  "templates": [
    {
      // template1
    },
    {
      // template2
    },
    ...
  ]
}

JSON Element Format

type

Attribute	Description
Description	The type of container (Docker or LXD) for this template.
Importance	Required
Format	Integer
Accepted Values	`1`: Used for Docker containers. `10`: Used for LXD containers.

title

Attribute	Description
Description	The title of the template.
Importance	Required
Format	String
Accepted Values	Any string value

sub_title

Attribute	Description
Description	Information about the template version.
Importance	Required
Format	String
Accepted Values	Any string value

description

Attribute	Description
Description	A description used to provide information about the template.
Importance	Required
Format	String
Accepted Values	Any string value

logo

Attribute	Description
Description	The location of a logo for the template.
Importance	Optional
Format	String
Accepted Values	Any valid URL or path relative to the network domain where the custom app template is hosted.

location

Attribute	Description
Description	The template URL. Could be an introduction webpage for the template.
Importance	Optional
Format	String
Accepted Values	Any valid URL

platform

Attribute	Description
Description	The supported platform. Must contain a valid value.
Importance	Required
Format	String
Accepted Values	`linux`: Every platform `linux/amd64`: 64-bit x86 `linux/arm64`: 64-bit ARM `linux/arm`: 32-bit ARM
Example	`{ "platform": "linux/amd64" }`

image

Attribute	Description
Description	The image associated with a template.
Importance	Required
Format	String
Accepted Values	Any valid image
Example	`{ "image": "nginx:latest" }`

command

Attribute	Description
Description	The command to run in the Docker container. If unspecified, the container uses the default command specified in the Dockerfile.
Importance	Optional
Format	String
Accepted Values	Any string value
Example	`{ "command": "nginx -g 'daemon off;'" }`

entrypoint

Attribute	Description
Description	The entrypoint to start the Docker container. If unspecified, the container uses the default entrypoint specified in the Dockerfile.
Importance	Optional
Format	String
Accepted Values	Any string value
Example	`{ "entrypoint": "/docker-entrypoint.sh" }`

env

Attribute	Description
Description	A JSON array describing the environment variables required by a template. Each element in the array must be a valid JSON object.
Importance	Optional
Format	Array
Accepted Values	A valid JSON array
Array Format	`name`: (Required) The name of the environment variable as supported in the container image. `value`: (Required) The value associated to the variable.
Example	`{ "env": [ { "name": "ENV_VAR1", "value": "" }, { "name": "ENV_VAR2", "value": "value2" } ] }`

labels

Attribute	Description
Description	A JSON array describing the labels associated with a template. Each element in the array must be a valid JSON object.
Importance	Optional
Format	Array
Accepted Values	A valid JSON array
Array Format	`name`: (Required) The name of the label key. `value`: (Required) The value associated to the key.
Example	`{ "labels": [ { "name": "com.example.vendor", "value": "Acme Incorporated" }, { "name": "com.example.label-with-value", "value": "foo" }, { "name": "version", "value": "1.0" } ] }`

volumes

Attribute	Description
Description	A JSON array describing the volumes associated with a template. Each element in the array must be a valid JSON object with a required container property.
Importance	Optional
Format	Array
Accepted Values	A valid JSON array
Array Format	`container`: (Required) The container path. `volume`: (Optional) The name of the Docker volume. `bind`: (Optional for Docker containers, Required for LXD containers) The host path used as the source of a bind mount. `readonly`: (Optional) If set to `true`, the volume is mounted in readonly mode.
Example	`{ "volumes": [ { "container": "/usr/share/nginx/html" }, { "container": "/usr/share/nginx/html" "volume": "nginx-vol" }, { "container": "/usr/share/nginx/html/my-templates.json", "bind": "/Container/my-templates.json ", "readonly": true } ] }`

ports

Attribute	Description
Description	A JSON array describing the ports exposed by a template. Each element in the array must be a valid JSON string specifying the port number in the container, as well as the protocol. This can optionally be prefixed with a port number and colon (for example 8080:) to define the port being mapped on the host. If the host port is not specified, the Docker host automatically assigns a port when the container starts.
Importance	Optional
Format	Array
Accepted Values	A valid JSON array
Example	`{ "ports": ["8080:80/tcp", "443/tcp", "80/udp"] }`

hostname

Attribute	Description
Description	The hostname of the container. Can help to easily identify the container.
Importance	Optional
Format	String
Accepted Values	Any string value
Example	`{ "hostname": "myContainerHostName" }`

restart_policy

Attribute	Description
Description	The restart policy associated with the Docker container. If unspecified, this value defaults to `unless-stopped`.
Importance	Optional
Format	String
Accepted Values	`no`: Do not automatically restart the container. `on-failure`: Restart the container if it exits because of errors, such as a nonzero exit code. `always`: Always restart the container if it stops. If it is manually stopped, it restarts only when Container Station restarts or you manually restart the container. `unless-stopped`: Similar to Always, except that when the container is manually stopped, it does not restart even after Container Station restarts.
Example	`{ "restart_policy": "unless-stopped" }`

auto_start_policy

Attribute	Description
Description	The auto start policy associated with the LXD container. If unspecified, this value defaults to `retain`.
Importance	Optional
Format	String
Accepted Values	`no`: Do not automatically restart the container. `always`: Always restart the container if it stops. If it is manually stopped, it restarts only when Container Station restarts or you manually restart the container. `retain`: Similar to Always, except that when the container is manually stopped, it does not restart even after Container Station restarts.
Example	`{ "auto_start_policy": "retain" }`

interactive

Attribute	Description
Description	Controls whether the Docker container should start in foreground mode. If unspecified, the value defaults to `true`.
Importance	Optional
Format	Boolean
Accepted Values	`true`: Start the Docker container in foreground mode. `false`: Starts the container in detached mode.
Example	`{ "interactive": false }`

tty

Attribute	Description
Description	Controls whether the Docker container should be allocated a pseudo-TTY. If unspecified, defaults to `true`.
Importance	Optional
Format	Boolean
Accepted Values	`true`: Allocates a pseudo-TTY to the Docker container `false`: Doesn't allocate a pseudo-TTY to the Docker container.
Example	`{ "tty": false }`

privileged

Attribute	Description
Description	Controls whether the container should start in privileged mode. If unspecified, defaults to `false`.
Importance	Optional
Format	Boolean
Accepted Values	`true`: Starts the container in Privileged mode. `false`: Doesn't start the container in Privileged mode.
Example	`{ "privileged": true }`

Hosting a Custom App Template in an NGINX Container

Next, you'll need to make the custom app template available to Container Station. This topic explains the process of hosting the template file with an NGINX container also running in Container Station.

Alternatively, you can also host the app template file in the QNAP Web Server. See Hosting a Custom App Template with the QNAP Web Server.

Important:

After you update the custom app templates JSON file, you must restart the NGINX container for the changes to reflect within the container.

Upload the custom app template file.
1. Open File Station.
2. Navigate to a folder on the device.
3. Upload the app template file.
4. Note the location of the template file for later use.
Open Container Station.
In the top panel, click the arrow next to Explore
Select Create Container.

The Create Container window opens.

Select an image.

Setting	Action
Mode	Select Basic Mode.
Registry	Select Docker Hub.
Image	Enter `nginx`.

Click Next.

Optional: Configure the container settings.

Setting	Action
Name	Enter a name for the container. For example: `nginx-my-template`.
Auto start policy	Select Unless Stopped. This option will cause the container to always restart unless it is manually stopped by a user.
Network Configuration	Configure the settings to fit your network environment. In this tutorial, we use the Default network mode and send traffic to the container through port `30080` on the host. Note: If the Host field isn't specified, the published port may change after the container restarts. This may cause the app template to become inaccessible to Container Station.

Setting

Action

Name

Enter a name for the container. For example: nginx-my-template.

Auto start policy

Select Unless Stopped.

This option will cause the container to always restart unless it is manually stopped by a user.

Network Configuration

Configure the settings to fit your network environment.

In this tutorial, we use the Default network mode and send traffic to the container through port 30080 on the host.

Note:

If the Host field isn't specified, the published port may change after the container restarts. This may cause the app template to become inaccessible to Container Station.

Optional: Modify the advanced settings.
1. Click Advanced Settings.
  
  The Advanced Settings window appears.
2. Go to the Storage tab.
3. Click the arrow next to Add Volume.
4. Select Bind Mount Host Path.
  
  A new storage row is added.
5. Click .
  
  The Select Host Path window opens.
6. Locate and select the app template file you uploaded earlier.
7. Click Apply.
8. In the Container field, enter /usr/share/nginx/html/TEMPLATE_FILENAME.
  
  Note:
  Replace TEMPLATE_FILENAME with the name of the your template file. For example: /usr/share/nginx/html/my-templates.json
9. Select RO.
10. Click Apply.
  
  Container Station saves the storage settings.
Click Next.
Review the container settings and then click Finish.

The app template file becomes available for use.

Note:

You can verify that the app template file is accessible by entering http://HOST_IP_ADDRESS:PUBLISHED_HOST_PORT/TEMPLATE_FILENAME in the web browser. For example: http://192.168.1.1:30080/my-templates.json.

Hosting a Custom App Template with the QNAP Web Server

Next, you'll need to make the custom app template available to Container Station. This topic explains the process of hosting the template file with the QNAP Web Server.

Alternatively, you can also host the app template file with an NGINX container directly within Container Station. See Hosting a Custom App Template in an NGINX Container.

Enable the QTS Web Server.
1. Log on to the system as administrator.
2. Go to Control Panel > Applications > Web Server > Web Server.
3. Select Enable Web Server.
4. Optional: Configure the Web Server settings.
5. Click Apply.
  
  The system enables the web server
Upload the custom app template file.
1. Open File Station.
2. Navigate to the Web folder created for the web server.
3. Upload the app template file.

The app template file becomes available for use.

Note:

You can verify that the app template file is accessible by entering http://HOST_IP_ADDRESS:WEB_SERVER_PORT/TEMPLATE_FILENAME in the web browser. For example: http://192.168.1.1:80/my-templates.json.

Adding a Custom App Template to Container Station

The next step is to add the custom app template file to Container Station. This makes the list of applications apps available within Container Station.

Start Container Station.
On the menu, click Preferences.
Go to App Templates.
Select Enable custom template.
Specify the URL to a custom app template.

Note:
Depending on your configuration, the URL may require you to include the IP address and port number of the configured web server. For example: http://192.168.1.1:30080/my-template-file.json.
Click Apply.

Container Station saves the custom app template.

Deploying a Custom App Template

The final step is to deploy a container from the custom app template file you added in the previous step.

On the menu, go to App Templates.
Go to the Custom Templates tab.
Identify a template.
Click Deploy.

The Deploy Container wizard opens. See Creating a Docker Container.

Was this article helpful?

Yes. No.

60% of people think it helps.

Please tell us how this article can be improved:

The article is missing important information
The article's solutions do not work
The article is too complicated
The article contains incorrect information
The article is out-of-date

If you want to provide additional feedback, please include it below.

Tárolás

Hálózati megoldások

Bővítéshez szükséges tartozékok

Felügyelet

NAS

Hálózati megoldások

Felügyelet

Creating a Custom App Template File

App Template Format

JSON Element Format

type

title

sub_title

description

logo

location

platform

image

command

entrypoint

env

labels

volumes