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

docs: document plugin properties migrated from env vars

Browse Source 
Per-plugin management docs now describe the properties introduced by the env-var-to-property migration in PR #8498, and stale prose and command-output examples that still referenced the old `DOKKU_*` names have been refreshed. The deprecated env vars table moves out of `environment-variables.md` and into the 0.38.0 migration guide, where it functions as a one-time pointer for upgrading users rather than ongoing reference material.
This commit is contained in:
Jose Diaz-Gonzalez
2026-04-30 17:02:39 -04:00
parent 823b37e383
commit cb0f729299
11 changed files with 181 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docs/appendices/0.38.0-migration-guide.md
View File

@@ -27,3 +27,36 @@
### TLS handshake behavior change
With the new catch-all installed, an HTTPS request to a hostname that matches a configured dokku app but where the app has no TLS certificate configured will have its TLS handshake rejected by the catch-all (via `ssl_reject_handshake on`). Previously, nginx fell through to the lexicographically first port-443 server block and presented that block's certificate, producing a cert-mismatch error on the client. The new behavior is a correctness improvement, but operators who deliberately relied on the old fall-through certificate (for monitoring probes, for example) need to either configure a certificate for the target app or remove the catch-all on that host. Existing apps that already have certificates configured are unaffected: nginx selects the right server block via SNI before TLS completion, so the catch-all is never consulted for legitimate requests.
### Environment variables migrated to plugin properties
A number of `DOKKU_*` config environment variables have been replaced with properly-namespaced plugin properties. Existing values are migrated automatically the first time `dokku` runs after the upgrade, and the original config variable is unset. No manual action is required.
Going forward, configure these settings using the property commands listed below. Setting the deprecated env vars via `dokku config:set` will no longer have any effect.
| Deprecated Env Var | Replacement Command |
|---|---|
| `DOKKU_APP_PROXY_TYPE` | `dokku proxy:set <app> type <value>` |
| `DOKKU_APP_RESTORE` | `dokku ps:set <app> restore <true\|false>` |
| `DOKKU_APP_SHELL` | `dokku scheduler:set <app> shell <value>` |
| `DOKKU_CHECKS_DISABLED` | `dokku checks:disable <app> [proctypes]` |
| `DOKKU_CHECKS_ENABLED` | `dokku checks:enable <app> [proctypes]` |
| `DOKKU_CHECKS_SKIPPED` | `dokku checks:skip <app> [proctypes]` |
| `DOKKU_CHECKS_WAIT` | `dokku checks:set <app> wait <value>` |
| `DOKKU_CHECKS_TIMEOUT` | `dokku checks:set <app> timeout <value>` |
| `DOKKU_CHECKS_ATTEMPTS` | `dokku checks:set <app> attempts <value>` |
| `DOKKU_DEFAULT_CHECKS_WAIT` | `dokku checks:set --global default-wait <value>` |
| `DOKKU_DISABLE_APP_AUTOCREATION` | `dokku apps:set --global disable-autocreation <true\|false>` |
| `DOKKU_DISABLE_PROXY` | `dokku proxy:disable <app>` / `dokku proxy:enable <app>` |
| `DOKKU_DOCKERFILE_START_CMD` | `dokku ps:set <app> dockerfile-start-cmd <value>` |
| `DOKKU_PROXY_PORT` | `dokku proxy:set <app> proxy-port <value>` |
| `DOKKU_PROXY_SSL_PORT` | `dokku proxy:set <app> proxy-ssl-port <value>` |
| `DOKKU_SKIP_ALL_CHECKS` | `dokku checks:disable <app>` |
| `DOKKU_SKIP_CLEANUP` | `dokku builder:set <app> skip-cleanup <true\|false>` |
| `DOKKU_SKIP_DEFAULT_CHECKS` | `dokku checks:skip <app>` |
| `DOKKU_SKIP_DEPLOY` | `dokku ps:set <app> skip-deploy <true\|false>` |
| `DOKKU_START_CMD` | `dokku ps:set <app> start-cmd <value>` |
`DOKKU_PARALLEL_ARGUMENTS` is removed entirely; it has no replacement.
`DOKKU_SKIP_CLEANUP` continues to be honored when set in `/etc/environment` or `~dokku/.dokkurc/*` so that bootstrap-time configuration keeps working, but the `builder skip-cleanup` property is the canonical interface and takes precedence when set.

2
docs/configuration/domains.md
View File

@@ -48,7 +48,7 @@ Vhosts can also be disabled for all apps:
dokku domains:disable --all
```
On subsequent deploys, the nginx virtualhost will be discarded. This is useful when deploying internal-facing services that should not be publicly routeable. As of 0.4.0, nginx will still be configured to proxy your app on some random high port. This allows internal services to maintain the same port between deployments. You may change this port by setting `DOKKU_PROXY_PORT` and/or `DOKKU_PROXY_SSL_PORT` (for services configured to use SSL.)
On subsequent deploys, the nginx virtualhost will be discarded. This is useful when deploying internal-facing services that should not be publicly routeable. As of 0.4.0, nginx will still be configured to proxy your app on some random high port. This allows internal services to maintain the same port between deployments. The non-SSL and SSL ports used can be customized via `dokku proxy:set <app> proxy-port <value>` and `dokku proxy:set <app> proxy-ssl-port <value>` - see the [proxy management documentation](/docs/networking/proxy-management.md#setting-proxy-ports) for details.
To re-enable, run the `domains:enable` subcommand:

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

@@ -127,34 +127,5 @@ The following config variables have special meanings and can be set in a variety
| `DOKKU_QUIET_OUTPUT` | none | `--quiet` flag | Silences certain header output for `dokku` commands. |
| `DOKKU_RM_CONTAINER` | none | `dokku config:set` <br /> | Deprecated: Whether to keep `dokku run` containers around or not. |
| `DOKKU_TRACE` | none | `dokku trace:on` <br /> `dokku trace:off` <br /> `--trace` flag | Turn on very verbose debugging. |
| `DOKKU_SKIP_CLEANUP` | | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | When a deploy is triggered, if this is set to a non-empty value, then old docker containers and images will not be removed. Falls back to the `builder:set skip-cleanup` property. |
| `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. |
## Deprecated Environment Variables
The following environment variables have been migrated to plugin properties. Existing values will be automatically migrated on upgrade. Use the corresponding property commands going forward.
| Deprecated Env Var | Replacement Command |
|---|---|
| `DOKKU_APP_PROXY_TYPE` | `dokku proxy:set <app> type <value>` |
| `DOKKU_APP_RESTORE` | `dokku ps:set <app> restore <true\|false>` |
| `DOKKU_APP_SHELL` | `dokku scheduler:set <app> shell <value>` |
| `DOKKU_CHECKS_DISABLED` | `dokku checks:disable <app> [proctypes]` |
| `DOKKU_CHECKS_ENABLED` | `dokku checks:enable <app> [proctypes]` |
| `DOKKU_CHECKS_SKIPPED` | `dokku checks:skip <app> [proctypes]` |
| `DOKKU_CHECKS_WAIT` | `dokku checks:set <app> wait <value>` |
| `DOKKU_CHECKS_TIMEOUT` | `dokku checks:set <app> timeout <value>` |
| `DOKKU_CHECKS_ATTEMPTS` | `dokku checks:set <app> attempts <value>` |
| `DOKKU_DEFAULT_CHECKS_WAIT` | `dokku checks:set --global default-wait <value>` |
| `DOKKU_DISABLE_APP_AUTOCREATION` | `dokku apps:set --global disable-autocreation <true\|false>` |
| `DOKKU_DISABLE_PROXY` | `dokku proxy:disable <app>` / `dokku proxy:enable <app>` |
| `DOKKU_DOCKERFILE_START_CMD` | `dokku ps:set <app> dockerfile-start-cmd <value>` |
| `DOKKU_PARALLEL_ARGUMENTS` | Removed. No longer supported. |
| `DOKKU_PROXY_PORT` | `dokku proxy:set <app> proxy-port <value>` |
| `DOKKU_PROXY_SSL_PORT` | `dokku proxy:set <app> proxy-ssl-port <value>` |
| `DOKKU_SKIP_ALL_CHECKS` | `dokku checks:disable <app>` |
| `DOKKU_SKIP_CLEANUP` | `dokku builder:set <app> skip-cleanup <true\|false>` |
| `DOKKU_SKIP_DEFAULT_CHECKS` | `dokku checks:skip <app>` |
| `DOKKU_SKIP_DEPLOY` | `dokku ps:set <app> skip-deploy <true\|false>` |
| `DOKKU_START_CMD` | `dokku ps:set <app> start-cmd <value>` |

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

@@ -13,6 +13,7 @@ apps:lock <app> # Locks an app for deployment
apps:locked <app> # Checks if an app is locked for deployment
apps:rename <old-app> <new-app> # Rename an app
apps:report [<app>] [<flag>] # Display report about an app
apps:set [--global] <app> <key> (<value>) # Set or clear an apps property for an app
apps:unlock <app> # Unlocks an app for deployment
```
@@ -78,6 +79,20 @@ Once created, you can configure the application as normal, and deploy the applic
- Create and link datastores.
- Set environment variables.
### Disabling automatic app creation
By default, pushing to a git remote for an app that does not yet exist on the Dokku host will cause the app to be created automatically. On shared or production hosts this may be undesirable - operators may prefer that an explicit `apps:create` is required first. The `disable-autocreation` global property controls this behavior:
```shell
dokku apps:set --global disable-autocreation true
```
While set, pushes targeting an app that does not exist will be rejected. The default behavior may be restored by passing an empty value:
```shell
dokku apps:set --global disable-autocreation
```
### Removing a deployed app
In some cases, you may need to destroy an application, whether it is because the application is temporary or because it was misconfigured. In these cases, you can use the `apps:destroy` command. Performing any destructive actions in Dokku requires confirmation, and this command will ask for the name of the application being deleted before doing so.

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

@@ -82,6 +82,28 @@ The default value may be set by passing an empty value for the option.
dokku builder:set --global build-dir
```
#### Skipping container and image cleanup
After a successful deploy, Dokku removes old containers and images that are no longer referenced by the app. On hosts where image rebuilds are expensive or where operators want to retain prior images for manual rollback, this cleanup can be disabled per-app or globally via the `skip-cleanup` property:
```shell
dokku builder:set node-js-app skip-cleanup true
```
The property can also be set globally:
```shell
dokku builder:set --global skip-cleanup true
```
The default behavior (cleanup enabled) may be restored by passing an empty value:
```shell
dokku builder:set node-js-app skip-cleanup
```
For backwards compatibility with bootstrap-time configuration, the `DOKKU_SKIP_CLEANUP` environment variable in `/etc/environment` or `~dokku/.dokkurc/*` is still honored when the `skip-cleanup` property is unset. The property is the canonical interface and takes precedence when set.
### Displaying builder reports for an app
You can get a report about the app's builder status using the `builder:report` command:

10
docs/deployment/builders/dockerfiles.md
View File

@@ -185,7 +185,7 @@ You would adjust the cache directory for whatever application cache you have, e.
### Customizing the run command
By default no arguments are passed to `docker run` when deploying the container and the `CMD` or `ENTRYPOINT` defined in the `Dockerfile` are executed. You can take advantage of docker ability of overriding the `CMD` or passing parameters to your `ENTRYPOINT` setting `$DOKKU_DOCKERFILE_START_CMD`. Let's say for example you are deploying a base Node.js image, with the following `ENTRYPOINT`:
By default no arguments are passed to `docker run` when deploying the container and the `CMD` or `ENTRYPOINT` defined in the `Dockerfile` are executed. You can take advantage of docker's ability to override the `CMD` or pass parameters to your `ENTRYPOINT` by setting the `dockerfile-start-cmd` property on the `ps` plugin. Let's say for example you are deploying a base Node.js image, with the following `ENTRYPOINT`:
```Dockerfile
ENTRYPOINT ["node"]
@@ -194,10 +194,14 @@ ENTRYPOINT ["node"]
You can do:
```shell
dokku config:set node-js-app DOKKU_DOCKERFILE_START_CMD="--harmony server.js"
dokku ps:set node-js-app dockerfile-start-cmd "--harmony server.js"
```
To tell Docker what to run.
To tell Docker what to run. Pass an empty value to clear the override:
```shell
dokku ps:set node-js-app dockerfile-start-cmd
```
### Procfiles and multiple processes

20
docs/deployment/schedulers/scheduler-management.md
View File

@@ -45,6 +45,26 @@ The default value may be set by passing an empty value for the option.
dokku scheduler:set --global selected
```
### Setting the app shell
The shell used for `dokku run` and `dokku enter` invocations against an app can be customized via the `shell` property. This is useful for images that ship with a non-default shell - for example, alpine-based images that only have `/bin/sh`.
```shell
dokku scheduler:set node-js-app shell sh
```
The `shell` property can also be set globally:
```shell
dokku scheduler:set --global shell sh
```
The default value (an empty string, which lets the scheduler pick its own default) may be restored by passing an empty value:
```shell
dokku scheduler:set node-js-app shell
```
### Displaying scheduler reports for an app
You can get a report about the app's scheduler status using the `scheduler:report` command:

8
docs/deployment/zero-downtime-deploys.md
View File

@@ -67,10 +67,6 @@ dokku checks:skip node-js-app worker,web
```
-----> Skipping zero downtime for app's (node-js-app) proctypes (worker,web)
-----> Unsetting node-js-app
-----> Unsetting DOKKU_CHECKS_DISABLED
-----> Setting config vars
DOKKU_CHECKS_SKIPPED: worker,web
```
Zero downtime checks can also be disabled completely. This will stop old containers *before* new ones start, which may result in broken connections and downtime if your application fails to boot properly.
@@ -81,10 +77,6 @@ dokku checks:disable node-js-app worker
```
-----> Disabling zero downtime for app's (node-js-app) proctypes (worker)
-----> Setting config vars
DOKKU_CHECKS_DISABLED: worker
-----> Setting config vars
DOKKU_CHECKS_SKIPPED: web
```
### Displaying checks reports for an app

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

@@ -333,8 +333,8 @@ Unsetting this value is the same as enabling custom nginx config usage.
{{ .APP }} Application name
{{ .APP_SSL_PATH }} Path to SSL certificate and key
{{ .DOKKU_ROOT }} Global Dokku root directory (ex: app dir would be `{{ .DOKKU_ROOT }}/{{ .APP }}`)
{{ .PROXY_PORT }} Non-SSL nginx listener port (same as `DOKKU_PROXY_PORT` config var)
{{ .PROXY_SSL_PORT }} SSL nginx listener port (same as `DOKKU_PROXY_SSL_PORT` config var)
{{ .PROXY_PORT }} Non-SSL nginx listener port (same as the `proxy-port` property)
{{ .PROXY_SSL_PORT }} SSL nginx listener port (same as the `proxy-ssl-port` property)
{{ .NOSSL_SERVER_NAME }} List of non-SSL VHOSTS
{{ .PROXY_PORT_MAP }} List of port mappings (same as the `map` ports property)
{{ .PROXY_UPSTREAM_PORTS }} List of configured upstream ports (derived from the `map` ports property)

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

@@ -9,7 +9,7 @@ proxy:clear-config [--all|<app>] # Clears config for given app
proxy:disable [--parallel count] [--all|<app>] # Disable proxy for app
proxy:enable [--parallel count] [--all|<app>] # Enable proxy for app
proxy:report [<app>] [<flag>] # Displays a proxy report for one or more apps
proxy:set [<app>|--global] <proxy-type> # Set proxy type for app
proxy:set [<app>|--global] <key> (<value>) # Set or clear a proxy property for an app
```
In Dokku 0.5.0, port proxying was decoupled from the `nginx-vhosts` plugin into the proxy plugin. Dokku 0.6.0 introduced the ability to map host ports to specific container ports. This allows other proxy software - such as HAProxy or Caddy - to be used in place of nginx.
@@ -25,8 +25,7 @@ dokku proxy:set node-js-app caddy
```
```
-----> Setting config vars
DOKKU_APP_PROXY_TYPE: caddy
=====> Setting type to caddy
```
The proxy may also be set on a global basis. This is usually preferred as running multiple proxy implementations may cause port collision issues.
@@ -36,12 +35,55 @@ dokku proxy:set --global caddy
```
```
-----> Setting config vars
DOKKU_PROXY_TYPE: caddy
=====> Setting type to caddy
```
Changing the proxy does not stop or start any given proxy implementation. Please see the documentation for your proxy implementation for details on how to perform a change.
### Disabling and enabling the proxy
The proxy can be disabled on a per-app basis via the `proxy:disable` command. While disabled, no proxy configuration will be generated for the app and incoming requests will not be routed through the configured proxy.
```shell
dokku proxy:disable node-js-app
```
```
-----> Disabling proxy for app
```
The proxy can be re-enabled with the `proxy:enable` command:
```shell
dokku proxy:enable node-js-app
```
```
-----> Enabling proxy for app
```
### Setting proxy ports
When an app's domains are disabled (see [domains documentation](/docs/configuration/domains.md)), Dokku still exposes the app on a high port so that internal services can reach it at a stable port across deploys. The non-SSL and SSL ports used for this can be configured via the `proxy:set` command:
```shell
dokku proxy:set node-js-app proxy-port 5000
dokku proxy:set node-js-app proxy-ssl-port 5443
```
Either property may also be set globally. Per-app values take precedence over the global value.
```shell
dokku proxy:set --global proxy-port 5000
dokku proxy:set --global proxy-ssl-port 5443
```
The default value for either property may be restored by passing an empty value:
```shell
dokku proxy:set node-js-app proxy-port
```
### Regenerating proxy config
In certain cases, your app proxy configs may drift from the correct config for your app. You may regenerate the config at any point via the `proxy:build-config` command. This command will trigger a rebuild for the configured proxy implementation (default: nginx) for a given app. The command may fail if there are no current web listeners for your app.

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

@@ -315,6 +315,28 @@ Finally, the number of parallel workers may be automatically set to the number o
dokku ps:start --all --parallel -1
```
### Customizing the start command
The command used to start an app's containers can be customized via two `ps` properties, depending on which builder is in use.
For buildpack-built apps (where the start command normally comes from the `Procfile`), set `start-cmd`:
```shell
dokku ps:set node-js-app start-cmd "node server.js"
```
For Dockerfile-built apps, set `dockerfile-start-cmd`. This value is passed as arguments to `docker run` and overrides or supplements the image's `CMD` / `ENTRYPOINT`. See the [Dockerfile builder documentation](/docs/deployment/builders/dockerfiles.md#customizing-the-run-command) for context.
```shell
dokku ps:set node-js-app dockerfile-start-cmd "--harmony server.js"
```
Either property can be cleared by passing an empty value:
```shell
dokku ps:set node-js-app start-cmd
```
### Restart policies
> [!IMPORTANT]
@@ -429,3 +451,15 @@ When a server reboots or Docker is restarted/upgraded, Docker may or may not sta
- If any of the app containers are missing, the entire app will be rebuilt.
During this time, requests may route to the incorrect app if the assigned IPs correspond to those for other apps. While dokku makes all efforts to avoid this, there may be a few minutes where urls may route to the wrong app. To avoid this, either use a custom proxy plugin or wait a few minutes until the restoration process is complete.
Per-app restore behavior can be controlled via the `restore` property. When set to `false`, `ps:restore` will skip the app on reboot:
```shell
dokku ps:set node-js-app restore false
```
The default value (`true`) may be restored by passing an empty value:
```shell
dokku ps:set node-js-app restore
```