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

test: backfill raw/global/computed report triplet coverage across plugins

Browse Source 
The bats coverage for plugin :report keys has been uneven since the raw/global/computed split landed in PR #8640. This commit adds a single combined triplet test per settable property across app-json, builder, builder-dockerfile, builder-herokuish, builder-lambda, builder-nixpacks, builder-pack, builder-railpack, buildpacks, cron (maintenance), git (keep-git-dir, rev-env-var, source-image), logs (vector-sink, vector-global-image, vector-global-networks), network (attach-post-create, attach-post-deploy, initial-network), proxy (per-app type), ps (stop-timeout-seconds), registry (image-repo, push-on-release, push-extra-tags), storage (build/deploy/run mounts), and adds a new tests/unit/scheduler.bats and tests/unit/nginx-vhosts_properties.bats. Brings ps `procfile-path` and `stop-timeout-seconds` global getters in line with the #8640 convention (raw global, default resolved in computed). Documents the read-only and internal properties that surface in `:report` (or are written by Dokku) but cannot be managed by `:set` in a new `## Internal properties` section appended to each affected plugin's docs page.
This commit is contained in:
Jose Diaz-Gonzalez
2026-05-21 23:59:14 -04:00
parent 2bdf7b59c9
commit cdcf1fc669
35 changed files with 1332 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -169,3 +169,11 @@ Available flags:
- `--builds-computed-retention`: the resolved retention applied to this app
`--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
The following properties surface in `builds:report` but are not managed by `builds:set` - they are derived metadata recorded during the build:
| Property | Kind | Description | Source |
|---|---|---|---|
| `--build-id`, `--build-kind`, `--build-status`, `--build-source`, `--build-pid`, `--build-started-at`, `--build-finished-at`, `--build-exit-code` | read-only | Per-build metadata for the most recent deploy | `plugins/builds/functions.go` writes during deploys |

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

@@ -230,3 +230,11 @@ The `docker-options:list` command prints the options stored for a single process
dokku docker-options:list node-js-app --process web --phase deploy
dokku docker-options:list node-js-app --phase deploy
```
## 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 |

8
docs/configuration/environment-variables.md
View File

@@ -129,3 +129,11 @@ The following config variables have special meanings and can be set in a variety
| `DOKKU_TRACE` | none | `dokku trace:on` <br /> `dokku trace:off` <br /> `--trace` flag | Turn on very verbose debugging. |
| `DOKKU_SYSTEM_GROUP` | `dokku` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | System group to chown files as. |
| `DOKKU_SYSTEM_USER` | `dokku` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | System user to chown files as. |
## Internal properties
The following property is recorded internally by the config plugin and is not exposed via `config:report`:
| Property | Kind | Description | Source |
|---|---|---|---|
| `env-migrated` | internal | Migration sentinel that records the per-app or global `DOKKU_*` env-var → property migration completed for 0.38.0 | `plugins/config/triggers.go` writes `"true"` after the upgrade-time pass |

8
docs/configuration/ssl.md
View File

@@ -150,3 +150,11 @@ If an `https:443:*` port mapping already exists when a certificate is installed
### Running behind a proxy (`X-Forwarded-Ssl`, etc.)
See the [running behind another proxy documentation](/docs/networking/proxies/nginx.md#running-behind-another-proxy--configuring-x-forwarded--headers) for more information on how to configure your Nginx config when your server is running behind a proxy (e.g. load balancer, etc.).
## Internal properties
The following properties surface in `certs:report` but are not managed by `certs:set` - they are derived from the on-disk certificate:
| Property | Kind | Description | Source |
|---|---|---|---|
| `--ssl-enabled`, `--ssl-dir`, `--ssl-hostnames`, `--ssl-issuer`, `--ssl-subject`, `--ssl-verified`, `--ssl-expires-at`, `--ssl-starts-at` | read-only | Metadata extracted from the on-disk certificate, if present | `plugins/certs/functions` openssl introspection |

12
docs/deployment/application-management.md
View File

@@ -312,3 +312,15 @@ You can pass flags which will output only the value of the specific information
```shell
dokku apps:report node-js-app --app-dir
```
## Internal properties
The following properties surface in `apps:report` but are not managed by `apps:set` - they are derived metadata recorded by the plugin:
| Property | Kind | Description | Source |
|---|---|---|---|
| `--app-created-at` | read-only | UNIX timestamp of app creation | written when the app directory is created in `plugins/apps/functions.go` |
| `--app-deploy-source` | read-only | Source kind of the last deploy (`git`, `archive`, `docker-image`, `git-sync`) | set via the `deploy-source-set` plugin trigger |
| `--app-deploy-source-metadata` | read-only | Free-form metadata for the deploy source (commit sha, image ref, URL) | set via the `deploy-source-set` plugin trigger |
| `--app-dir` | read-only | Absolute path of the app root on disk | derived from `DOKKU_ROOT` and the app name |
| `--app-locked` | read-only | `true` while a deploy or rebuild holds the app lock | `plugins/apps/functions.go` lock helpers |

8
docs/deployment/builders/builder-management.md
View File

@@ -172,3 +172,11 @@ Custom plugins names _must_ have the prefix `builder-` or builder overriding via
Builders can use any tools available on the system to build the docker image, and may even be used to schedule building off-server. The only current requirement is that the image must exist on the server at the end of the `builder-build` command, though this requirement may be relaxed in a future release.
For a simple example of how to implement this trigger, see `builder-pack`, which utilizes a cli tool - `pack-cli` - to generate an OCI image that is compatible with Docker and can be scheduled by the official scheduling plugins.
## Internal properties
The following properties surface in `builder:report` but are not managed by `builder:set`:
| Property | Kind | Description | Source |
|---|---|---|---|
| `--builder-detected` | read-only | Builder auto-selected for the app when `selected` is unset | `builder-detect` plugin trigger run on demand |

9
docs/deployment/methods/git.md
View File

@@ -318,3 +318,12 @@ dokku git:report node-js-app --format json
```
The `--format` flag cannot be combined with an info flag.
## Internal properties
The following properties surface in `git:report` but are not managed by `git:set` - they are derived from repository state:
| Property | Kind | Description | Source |
|---|---|---|---|
| `--git-sha` | read-only | HEAD commit SHA of the app's git repo | `git rev-parse HEAD` against `$APP_ROOT` |
| `--git-last-updated-at` | read-only | UNIX timestamp of the last write to the deploy branch ref | `stat -c %Y` on `refs/heads/<deploy-branch>` |

9
docs/networking/network.md
View File

@@ -511,3 +511,12 @@ You can pass flags which will output only the value of the specific information
```shell
dokku network:report node-js-app --network-bind-all-interfaces
```
## Internal properties
The following properties surface in `network:report` but are not managed by `network:set` - they are derived from the running app state:
| Property | Kind | Description | Source |
|---|---|---|---|
| `--network-web-listeners` | read-only | Current `web` process listeners (host:port) for the deployed app | derived from running container inspection |
| `--network-static-web-listener` | read-only | Static listener override used when no container is running | derived from app config |

8
docs/networking/port-management.md
View File

@@ -220,3 +220,11 @@ You can pass flags which will output only the value of the specific information
```shell
dokku ports:report node-js-app --ports-map
```
## Internal properties
The following properties surface in `ports:report` but are not managed by `ports:set` - they are derived from the deploy:
| Property | Kind | Description | Source |
|---|---|---|---|
| `--ports-map-detected` | read-only | Port mapping inferred from `EXPOSE` directives or the running container | `builder-dockerfile` detection on deploy |

8
docs/networking/proxies/caddy.md
View File

@@ -265,3 +265,11 @@ You can pass flags which will output only the value of the specific information
```shell
dokku caddy:report node-js-app --caddy-computed-image
```
## Internal properties
The following properties are not managed by `caddy:set` but are recorded internally by the plugin:
| Property | Kind | Description | Source |
|---|---|---|---|
| `proxy-status` | internal | `started`/`stopped` state of the caddy compose project | `cmd-caddy-start`/`cmd-caddy-stop` in `plugins/caddy-vhosts/command-functions` |

8
docs/networking/proxies/haproxy.md
View File

@@ -244,3 +244,11 @@ You can pass flags which will output only the value of the specific information
```shell
dokku haproxy:report node-js-app --haproxy-computed-image
```
## Internal properties
The following properties are not managed by `haproxy:set` but are recorded internally by the plugin:
| Property | Kind | Description | Source |
|---|---|---|---|
| `proxy-status` | internal | `started`/`stopped` state of the haproxy compose project | `cmd-haproxy-start`/`cmd-haproxy-stop` in `plugins/haproxy-vhosts/command-functions` |

10
docs/networking/proxies/nginx.md
View File

@@ -620,3 +620,13 @@ See the [ports documentation](/docs/networking/port-management.md) for more info
### Regenerating nginx config
See the [proxy documentation](/docs/networking/proxy-management.md#regenerating-proxy-config) for more information on how to rebuild the nginx proxy configuration for your app.
## Internal properties
The following properties surface in `nginx:report` but are not managed by `nginx:set`, or are recorded internally by the plugin:
| Property | Kind | Description | Source |
|---|---|---|---|
| `--nginx-last-visited-at` | read-only | UNIX timestamp of the last request served by nginx for the app | log-tailer writes the property on every request batch |
| `proxy-status` | internal | `started`/`stopped` state of the nginx system service | `cmd-nginx-start`/`cmd-nginx-stop` |
| `nginx-conf-sigil-migrated` | internal | Migration sentinel set the first time a v1 template is rewritten to the current schema | `plugins/nginx-vhosts/install` writes `"true"` once the install-time migration runs |

8
docs/networking/proxies/traefik.md
View File

@@ -390,3 +390,11 @@ You can pass flags which will output only the value of the specific information
```shell
dokku traefik:report node-js-app --traefik-computed-api-enabled
```
## Internal properties
The following properties are not managed by `traefik:set` but are recorded internally by the plugin:
| Property | Kind | Description | Source |
|---|---|---|---|
| `proxy-status` | internal | `started`/`stopped` state of the traefik compose project | `cmd-traefik-start`/`cmd-traefik-stop` in `plugins/traefik-vhosts/command-functions` |

8
docs/networking/proxy-management.md
View File

@@ -236,3 +236,11 @@ Proxy implementations may decide to omit some functionality here, or use plugin
Individual proxy implementations _may_ trigger app rebuilds, depending on how proxy metadata is exposed for the proxy implementation.
Finally, proxy implementations _may_ install extra software needed for the proxy itself in whatever manner deemed fit. Proxy software can run on the host itself or within a running Docker container with either exposed ports or host networking.
## Internal properties
The following properties surface in `proxy:report` but are not managed by `proxy:set`:
| Property | Kind | Description | Source |
|---|---|---|---|
| `--proxy-enabled` | read-only | `true` when the app's `disabled` property is not `true` | `plugins/proxy/proxy.go::IsAppProxyEnabled` |

9
docs/processes/process-management.md
View File

@@ -463,3 +463,12 @@ The default value (`true`) may be restored by passing an empty value:
```shell
dokku ps:set node-js-app restore
```
## Internal properties
The following properties surface in `ps:report` but are not managed by `ps:set` - they are derived from the running process state:
| Property | Kind | Description | Source |
|---|---|---|---|
| `--ps-can-scale` | read-only | `false` when the app's procfile or builder forbids horizontal scaling | derived from procfile parse |
| `--deployed`, `--running`, `--processes`, `--status-<proctype>` | read-only | Live process state | `plugins/ps/report.go` inspects running containers |