Files

gyurix b564422754 Update README.md to enhance application configuration documentation and add Nextcloud example

2026-03-16 12:01:07 +01:00

6.7 KiB

Raw Blame History

default-applications-tree

This repository defines the available applications and their configuration templates. Each application lives in its own subdirectory and is registered in applications-tree.json.

applications-tree.json

The root applications-tree.json file lists all available applications. Each entry in the apps array registers one application:

{
    "apps": [
        {
            "name": "Nextcloud",
            "subtitle": "File Synchronization",
            "version": "31.0.8-fpm-alpine",
            "icon": "data:image/svg+xml;base64,..."
        }
    ]
}

App entry fields

Field	Required	Description
`name`	yes	Display name of the application. Must match the directory name (case-insensitive).
`version`	yes	Default version tag used when deploying. Use `"latest"` for the most recent image.
`subtitle`	no	Short tagline shown in the app listing UI.
`icon`	no	Base64-encoded SVG or PNG image used as the app icon in the UI (`data:image/svg+xml;base64,...` or `data:image/png;base64,...`).

Application directory structure

Each application has its own directory (e.g. nextcloud/). The directory name must match the name in applications-tree.json. It must contain a template.json file and can contain additional JSON files for services, domains, secrets, firewall rules, etc.

nextcloud/
    template.json           ← mandatory configuration template
    service-nextcloud.json  ← service definition
    domain-nextcloud.json   ← domain/ingress configuration
    nextcloud-secret.json   ← secrets / environment variables
    firewall-nextcloud.json ← firewall rules
    ...

template.json

The template.json file defines the application's metadata and the list of configuration fields that are presented in the deployment form.

Top-level structure

{
    "name": "Nextcloud",
    "title": "Nextcloud",
    "subtitle": "File Synchronization",
    "description": "Nextcloud is a suite of client-server software...",
    "icon": "data:image/svg+xml;base64,...",
    "fields": [ ... ]
}

Top-level fields

Field	Required	Description
`name`	yes	Must match the directory name. Used as the application identifier.
`title`	no	Human-readable display title shown in the form header (falls back to `name` if omitted).
`subtitle`	no	Short tagline displayed below the title.
`description`	no	Longer description of the application shown in the form or app listing.
`icon`	no	Base64-encoded SVG or PNG icon (`data:image/svg+xml;base64,...`).
`fields`	yes	Array of configuration field definitions (see below).

Field definitions

Each element of the fields array defines one configuration variable. Fields are rendered as form inputs during deployment. Fields with generated set are auto-populated and not shown in the form.

Field properties

Property	Required	Description
`description`	yes	Label text displayed before the input.
`key`	yes	The environment variable name that will hold the value.
`value`	no	Default value pre-filled in the form. For `select` fields this defines the available options (see below).
`required`	no	Set to `"true"` to make the field mandatory. The form will not submit until it is filled.
`type`	no	Input type. Defaults to `"text"`. See Field types.
`info`	no	Additional hint or explanatory text shown alongside or below the field.
`generated`	no	Auto-generation pattern. When set the field is not shown in the form; its value is generated automatically. See Generated values.
`advanced`	no	Set to `"true"` to hide the field from the UI by default. It can be revealed by pressing the `>` button.

Field types

The type property controls how the field is rendered:

Type	Description
`text`	(default) Single-line plain text input.
`password`	The value is hidden from human-readable display wherever it is shown in the UI.
`textarea`	Multi-line text input.
`select`	Dropdown. Options are defined in `value` as a comma-separated list. Each option can be `optionValue` or `displayText:optionValue`.

Select field examples

Simple yes/no toggle:

{
    "description": "Enable feature",
    "key": "FEATURE_ENABLED",
    "value": "false,true",
    "type": "select"
}

Options with display labels:

{
    "description": "Email provider",
    "key": "MAIL_PROVIDER",
    "value": "1:Gmail,2:Microsoft Outlook/Hotmail,3:Other",
    "type": "select"
}

TOTP authentication toggle (advanced):

{
    "description": "TOTP authentication (true/false)",
    "key": "GUACAMOLE_TOTP",
    "value": "false,true",
    "required": "true",
    "type": "select",
    "advanced": "true"
}

Generated values

When generated is set the field value is computed automatically. The format is:

"<source>|<encoding>|<length>"

Part	Options	Description
`source`	`time`, `random`	`time` seeds the hash from the current timestamp; `random` uses a random number.
`encoding`	`md5`, `sha256`	Hash algorithm applied to the source value.
`length`	integer	Number of characters to take from the hash output.

Examples

Pattern	Result
`"time\|md5\|8"`	8-character MD5 hash seeded from the current time.
`"random\|md5\|12"`	12-character MD5 hash seeded from a random number.
`"random\|sha256\|20"`	20-character SHA-256 hash seeded from a random number.
`""`	Auto-generated with default settings (pattern not specified).

Complete field example

{
    "description": "Nextcloud admin password",
    "key": "NEXTCLOUD_ADMIN_PASSWORD",
    "value": "",
    "required": "true",
    "type": "password",
    "info": "Must be at least 8 characters long."
}

Auto-generated database password (not shown in the form):

{
    "description": "Postgres password for user",
    "key": "POSTGRES_PASSWORD",
    "value": "",
    "required": "true",
    "generated": "random|md5|12"
}

Advanced optional SMTP field:

{
    "description": "Email sending protocol",
    "key": "MAIL_PROTOCOL",
    "value": "",
    "info": "Options are: empty (for no encryption), ssl, tls",
    "advanced": "true"
}

6.7 KiB Raw Blame History