diff --git a/README.md b/README.md index c29ce75..dfa190b 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,201 @@ # default-applications-tree -You can add more application sections into applications-tree.json. -You have to specify the application name and version. For example: +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: + +```json +{ + "apps": [ { - "name": "nextcloud", - "version": "latest" + "name": "Nextcloud", + "subtitle": "File Synchronization", + "version": "31.0.8-fpm-alpine", + "icon": "data:image/svg+xml;base64,..." } + ] +} +``` -The name must be the same as the directory name of the application. +### App entry fields -The directory of an application have to contain a template.json file and can contain more json files (service, domain, secret, etc. files). +| 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,...`). | -The mandatory template.json file's structure is the following. - - "name" - the name of the application, must be the same as the directory name - - "fields" - array of used variables by service +--- - { - "name": "vaultwarden", - "fields": [ - ... - ] - } +## Application directory structure -An element of fields can contain the following keys. - - description - label of the field, this text will appear before element - - key - name of variable - - value - default value of variable in the form - - required - if set "true" then fill in of the field is required in the form - - type - if not set then default is text, available field types: text, password, textarea, select - - if type is "select" then options are separated by ",". Option's value and text is separated by ":", but text is not mandatory. For example: +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. - "value": "yes,no" - "value": "1:gmail,2:microsoft outlook/hotmail,3:other", +``` +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 + ... +``` - - generated - the value of the variable is auto generated, so the field will not appear in the form. Generated examples: +--- - "time|md5|8" - generated from time, encoded by md5 and character length is 8 - "random|md5|20" - random generated number, encoded by sha256, length is 20 +## template.json -Field element example: +The `template.json` file defines the application's metadata and the list of configuration fields that are presented in the deployment form. - { - "description": "Please add Nextcloud password:", - "key": "NEXTCLOUD_PASSWORD", - "value": "", - "required": "true", - "type": "password" - }, +### Top-level structure +```json +{ + "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](#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](#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: +```json +{ + "description": "Enable feature", + "key": "FEATURE_ENABLED", + "value": "false,true", + "type": "select" +} +``` + +Options with display labels: +```json +{ + "description": "Email provider", + "key": "MAIL_PROVIDER", + "value": "1:Gmail,2:Microsoft Outlook/Hotmail,3:Other", + "type": "select" +} +``` + +TOTP authentication toggle (advanced): +```json +{ + "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: + +``` +"||" +``` + +| 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 + +```json +{ + "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): +```json +{ + "description": "Postgres password for user", + "key": "POSTGRES_PASSWORD", + "value": "", + "required": "true", + "generated": "random|md5|12" +} +``` + +Advanced optional SMTP field: +```json +{ + "description": "Email sending protocol", + "key": "MAIL_PROTOCOL", + "value": "", + "info": "Options are: empty (for no encryption), ssl, tls", + "advanced": "true" +} +```