safebox/default-applications-tree
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
gyurix
2026-03-16 12:01:07 +01:00
parent 3a7c888f53
commit b564422754
1 changed files with 185 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+186 -36
View File
@@ -1,51 +1,201 @@
# default-applications-tree # default-applications-tree
You can add more application sections into applications-tree.json. This repository defines the available applications and their configuration templates. Each application lives in its own subdirectory and is registered in `applications-tree.json`.
You have to specify the application name and version. For example:
---
## 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", "name": "Nextcloud",
"version": "latest" "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. ### App entry fields
- 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:
"value": "yes,no" | Field | Required | Description |
"value": "1:gmail,2:microsoft outlook/hotmail,3:other", |------------|----------|-------------|
| `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 ## Application directory structure
"random|md5|20" - random generated number, encoded by sha256, length is 20
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:", nextcloud/
"key": "NEXTCLOUD_PASSWORD", 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": "", "value": "",
"required": "true", "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"
}
```