From cb0f7292999da5fcd1d26c9ae17302a7fb91be8d Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Thu, 30 Apr 2026 17:02:39 -0400 Subject: [PATCH] docs: document plugin properties migrated from env vars 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. --- docs/appendices/0.38.0-migration-guide.md | 33 ++++++++++++ docs/configuration/domains.md | 2 +- docs/configuration/environment-variables.md | 29 ----------- docs/deployment/application-management.md | 15 ++++++ .../deployment/builders/builder-management.md | 22 ++++++++ docs/deployment/builders/dockerfiles.md | 10 ++-- .../schedulers/scheduler-management.md | 20 +++++++ docs/deployment/zero-downtime-deploys.md | 8 --- docs/networking/proxies/nginx.md | 4 +- docs/networking/proxy-management.md | 52 +++++++++++++++++-- docs/processes/process-management.md | 34 ++++++++++++ 11 files changed, 181 insertions(+), 48 deletions(-) diff --git a/docs/appendices/0.38.0-migration-guide.md b/docs/appendices/0.38.0-migration-guide.md index 96f0bfbfd..c67db9a83 100644 --- a/docs/appendices/0.38.0-migration-guide.md +++ b/docs/appendices/0.38.0-migration-guide.md @@ -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 type ` | +| `DOKKU_APP_RESTORE` | `dokku ps:set restore ` | +| `DOKKU_APP_SHELL` | `dokku scheduler:set shell ` | +| `DOKKU_CHECKS_DISABLED` | `dokku checks:disable [proctypes]` | +| `DOKKU_CHECKS_ENABLED` | `dokku checks:enable [proctypes]` | +| `DOKKU_CHECKS_SKIPPED` | `dokku checks:skip [proctypes]` | +| `DOKKU_CHECKS_WAIT` | `dokku checks:set wait ` | +| `DOKKU_CHECKS_TIMEOUT` | `dokku checks:set timeout ` | +| `DOKKU_CHECKS_ATTEMPTS` | `dokku checks:set attempts ` | +| `DOKKU_DEFAULT_CHECKS_WAIT` | `dokku checks:set --global default-wait ` | +| `DOKKU_DISABLE_APP_AUTOCREATION` | `dokku apps:set --global disable-autocreation ` | +| `DOKKU_DISABLE_PROXY` | `dokku proxy:disable ` / `dokku proxy:enable ` | +| `DOKKU_DOCKERFILE_START_CMD` | `dokku ps:set dockerfile-start-cmd ` | +| `DOKKU_PROXY_PORT` | `dokku proxy:set proxy-port ` | +| `DOKKU_PROXY_SSL_PORT` | `dokku proxy:set proxy-ssl-port ` | +| `DOKKU_SKIP_ALL_CHECKS` | `dokku checks:disable ` | +| `DOKKU_SKIP_CLEANUP` | `dokku builder:set skip-cleanup ` | +| `DOKKU_SKIP_DEFAULT_CHECKS` | `dokku checks:skip ` | +| `DOKKU_SKIP_DEPLOY` | `dokku ps:set skip-deploy ` | +| `DOKKU_START_CMD` | `dokku ps:set start-cmd ` | + +`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. diff --git a/docs/configuration/domains.md b/docs/configuration/domains.md index 120157f45..c1944279d 100644 --- a/docs/configuration/domains.md +++ b/docs/configuration/domains.md @@ -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 proxy-port ` and `dokku proxy:set proxy-ssl-port ` - see the [proxy management documentation](/docs/networking/proxy-management.md#setting-proxy-ports) for details. To re-enable, run the `domains:enable` subcommand: diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md index d862ba640..c4f8885ec 100644 --- a/docs/configuration/environment-variables.md +++ b/docs/configuration/environment-variables.md @@ -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`
| Deprecated: Whether to keep `dokku run` containers around or not. | | `DOKKU_TRACE` | none | `dokku trace:on`
`dokku trace:off`
`--trace` flag | Turn on very verbose debugging. | -| `DOKKU_SKIP_CLEANUP` | | `/etc/environment`
`~dokku/.dokkurc`
`~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`
`~dokku/.dokkurc`
`~dokku/.dokkurc/*` | System group to chown files as. | | `DOKKU_SYSTEM_USER` | `dokku` | `/etc/environment`
`~dokku/.dokkurc`
`~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 type ` | -| `DOKKU_APP_RESTORE` | `dokku ps:set restore ` | -| `DOKKU_APP_SHELL` | `dokku scheduler:set shell ` | -| `DOKKU_CHECKS_DISABLED` | `dokku checks:disable [proctypes]` | -| `DOKKU_CHECKS_ENABLED` | `dokku checks:enable [proctypes]` | -| `DOKKU_CHECKS_SKIPPED` | `dokku checks:skip [proctypes]` | -| `DOKKU_CHECKS_WAIT` | `dokku checks:set wait ` | -| `DOKKU_CHECKS_TIMEOUT` | `dokku checks:set timeout ` | -| `DOKKU_CHECKS_ATTEMPTS` | `dokku checks:set attempts ` | -| `DOKKU_DEFAULT_CHECKS_WAIT` | `dokku checks:set --global default-wait ` | -| `DOKKU_DISABLE_APP_AUTOCREATION` | `dokku apps:set --global disable-autocreation ` | -| `DOKKU_DISABLE_PROXY` | `dokku proxy:disable ` / `dokku proxy:enable ` | -| `DOKKU_DOCKERFILE_START_CMD` | `dokku ps:set dockerfile-start-cmd ` | -| `DOKKU_PARALLEL_ARGUMENTS` | Removed. No longer supported. | -| `DOKKU_PROXY_PORT` | `dokku proxy:set proxy-port ` | -| `DOKKU_PROXY_SSL_PORT` | `dokku proxy:set proxy-ssl-port ` | -| `DOKKU_SKIP_ALL_CHECKS` | `dokku checks:disable ` | -| `DOKKU_SKIP_CLEANUP` | `dokku builder:set skip-cleanup ` | -| `DOKKU_SKIP_DEFAULT_CHECKS` | `dokku checks:skip ` | -| `DOKKU_SKIP_DEPLOY` | `dokku ps:set skip-deploy ` | -| `DOKKU_START_CMD` | `dokku ps:set start-cmd ` | diff --git a/docs/deployment/application-management.md b/docs/deployment/application-management.md index ca5743e58..cf1869afd 100644 --- a/docs/deployment/application-management.md +++ b/docs/deployment/application-management.md @@ -13,6 +13,7 @@ apps:lock # Locks an app for deployment apps:locked # Checks if an app is locked for deployment apps:rename # Rename an app apps:report [] [] # Display report about an app +apps:set [--global] () # Set or clear an apps property for an app apps:unlock # 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. diff --git a/docs/deployment/builders/builder-management.md b/docs/deployment/builders/builder-management.md index cc31adb60..600478a22 100644 --- a/docs/deployment/builders/builder-management.md +++ b/docs/deployment/builders/builder-management.md @@ -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: diff --git a/docs/deployment/builders/dockerfiles.md b/docs/deployment/builders/dockerfiles.md index ec1b7b5ee..eb8ac066e 100644 --- a/docs/deployment/builders/dockerfiles.md +++ b/docs/deployment/builders/dockerfiles.md @@ -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 diff --git a/docs/deployment/schedulers/scheduler-management.md b/docs/deployment/schedulers/scheduler-management.md index 4fac3ce0f..27ed1fedc 100644 --- a/docs/deployment/schedulers/scheduler-management.md +++ b/docs/deployment/schedulers/scheduler-management.md @@ -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: diff --git a/docs/deployment/zero-downtime-deploys.md b/docs/deployment/zero-downtime-deploys.md index 56bb1cf23..d321f1ed3 100644 --- a/docs/deployment/zero-downtime-deploys.md +++ b/docs/deployment/zero-downtime-deploys.md @@ -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 diff --git a/docs/networking/proxies/nginx.md b/docs/networking/proxies/nginx.md index 473f7a408..0e5a256bc 100644 --- a/docs/networking/proxies/nginx.md +++ b/docs/networking/proxies/nginx.md @@ -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) diff --git a/docs/networking/proxy-management.md b/docs/networking/proxy-management.md index 173b2e868..260fce91d 100644 --- a/docs/networking/proxy-management.md +++ b/docs/networking/proxy-management.md @@ -9,7 +9,7 @@ proxy:clear-config [--all|] # Clears config for given app proxy:disable [--parallel count] [--all|] # Disable proxy for app proxy:enable [--parallel count] [--all|] # Enable proxy for app proxy:report [] [] # Displays a proxy report for one or more apps -proxy:set [|--global] # Set proxy type for app +proxy:set [|--global] () # 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. diff --git a/docs/processes/process-management.md b/docs/processes/process-management.md index 86b80982e..ca8525aea 100644 --- a/docs/processes/process-management.md +++ b/docs/processes/process-management.md @@ -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 +```