Update README.md to enhance application configuration documentation and add Nextcloud example
This commit is contained in:
gyurix
@@ -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.
|
||||
|
||||
The directory of an application have to contain a template.json file and can contain more json files (service, domain, secret, etc. files).
|
||||
|
||||
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": [
|
||||
...
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
### App entry fields
|
||||
|
||||
"value": "yes,no"
|
||||
"value": "1:gmail,2:microsoft outlook/hotmail,3:other",
|
||||
| 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,...`). |
|
||||
|
||||
- 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
|
||||
## Application directory structure
|
||||
|
||||
Field element 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.
|
||||
|
||||
{
|
||||
"description": "Please add Nextcloud password:",
|
||||
"key": "NEXTCLOUD_PASSWORD",
|
||||
```
|
||||
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
|
||||
|
||||
```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:
|
||||
|
||||
```
|
||||
"<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
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "Nextcloud admin password",
|
||||
"key": "NEXTCLOUD_ADMIN_PASSWORD",
|
||||
"value": "",
|
||||
"required": "true",
|
||||
"type": "password"
|
||||
},
|
||||
"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"
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user