github/dokku
0
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: add settable properties tables to plugin docs

Browse Source 
Renames the existing `## Internal properties` umbrella section to `## Properties` across all plugin docs and adds a new `### Settable properties` subsection enumerating every property accepted by each plugin's `:set` command. Each row lists scope, default, the actual `:report` flag shapes that surface the value, and a one-line description. The buildpacks plugin is included even though it uses `:set-property`, with a note in the subsection clarifying the legacy command name. Property lists, scopes, and report flags were verified against plugin source and the live dokku binary.
This commit is contained in:
Jose Diaz-Gonzalez
2026-05-23 22:45:20 -04:00
parent 3d3c95545c
commit 8742f688e3
31 changed files with 466 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/advanced-usage/builds.md
View File

@@ -170,17 +170,25 @@ Available flags:
`--build-status` returns the **display** status, so an abandoned in-flight build shows `abandoned` rather than `running`. The raw on-disk status is only visible by reading the JSON record directly.
## Internal properties
## Properties
The following properties surface in `builds:report` but are not managed by `builds:set` - they are derived metadata recorded during the build:
### Settable properties
| Property | Kind | Description | Source |
|---|---|---|---|
| `--build-id` | read-only | Unique identifier of the most recent build for the app | `plugins/builds/functions.go` writes during deploys |
| `--build-kind` | read-only | Whether the record was a `build` or a `deploy` | `plugins/builds/functions.go` writes during deploys |
| `--build-status` | read-only | Display status (`running`, `succeeded`, `failed`, `canceled`, `abandoned`) | `plugins/builds/functions.go` writes during deploys; status is computed at read time |
| `--build-source` | read-only | Trigger that started the build (e.g. `git-hook`, `ps:rebuild`, `ps:restart`) | `plugins/builds/functions.go` writes during deploys |
| `--build-pid` | read-only | PID of the build process | `plugins/builds/functions.go` writes during deploys |
| `--build-started-at` | read-only | UNIX timestamp the build started | `plugins/builds/functions.go` writes during deploys |
| `--build-finished-at` | read-only | UNIX timestamp the build finished | `plugins/builds/functions.go` writes during deploys |
| `--build-exit-code` | read-only | Exit code of the build process | `plugins/builds/functions.go` writes during deploys |
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| `retention` | app + global | `20` | `--builds-retention`, `--builds-global-retention`, `--builds-computed-retention` | Number of recent build records kept per app; older finalized records are pruned at the end of each deploy |
### Read-only flags
The following flags surface in `builds:report` but are not managed by `builds:set` - they are derived metadata recorded during the build:
| Flag | Description |
|---|---|
| `--build-id` | Unique identifier of the most recent build for the app |
| `--build-kind` | Whether the record was a `build` or a `deploy` |
| `--build-status` | Display status (`running`, `succeeded`, `failed`, `canceled`, `abandoned`); computed at read time |
| `--build-source` | Trigger that started the build (e.g. `git-hook`, `ps:rebuild`, `ps:restart`) |
| `--build-pid` | PID of the build process |
| `--build-started-at` | UNIX timestamp the build started |
| `--build-finished-at` | UNIX timestamp the build finished |
| `--build-exit-code` | Exit code of the build process |

10
docs/advanced-usage/docker-options.md
View File

@@ -231,10 +231,12 @@ dokku docker-options:list node-js-app --process web --phase deploy
dokku docker-options:list node-js-app --phase deploy
```
## Internal properties
## Properties
### Internal properties
The following property is recorded internally by the docker-options plugin and is not exposed via `docker-options:report`:
| Property | Kind | Description | Source |
|---|---|---|---|
| `migrated-from-files` | internal | Global migration sentinel that records that the legacy `DOCKER_OPTIONS_<PHASE>` flat-file store has been drained into plugin properties | `plugins/docker-options/functions.go` writes `"true"` once the install-time migration runs |
| Property | Description | Source |
|---|---|---|
| `migrated-from-files` | Global migration sentinel that records that the legacy `DOCKER_OPTIONS_<PHASE>` flat-file store has been drained into plugin properties | `plugins/docker-options/functions.go` writes `"true"` once the install-time migration runs |

12
docs/advanced-usage/registry-management.md
View File

@@ -208,3 +208,15 @@ dokku registry:set node-js-app push-extra-tags
# globally
dokku registry:set --global push-extra-tags
```
## Properties
### Settable properties
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| `image-repo` | app only | `dokku/<app>` | `--registry-image-repo`, `--registry-computed-image-repo` | Repository name used when pushing the app's image (overrides the global template) |
| `image-repo-template` | global only | `dokku/{{ .AppName }}` | `--registry-global-image-repo-template` | Go template used to compute the per-app image repository when `image-repo` is unset |
| `push-extra-tags` | app + global | none | `--registry-push-extra-tags` | Comma-separated list of additional tags pushed alongside the deploy tag |
| `push-on-release` | app + global | `false` | `--registry-push-on-release`, `--registry-global-push-on-release`, `--registry-computed-push-on-release` | When `true`, pushes the image to the registry on every successful build |
| `server` | app + global | none | `--registry-server`, `--registry-global-server`, `--registry-computed-server` | Registry server host (e.g. `ghcr.io`) used when pushing images |