Merge pull request #9227 from dokku/datastore-plugin

Ship every datastore as a core datastore plugin
This commit is contained in:
Jose Diaz-Gonzalez authored and GitHub committed 2026-10-30 17:56:11 -04:00
commit a3c31275a2
47 files changed
+736 -43

No files matched your search

+1
View File
@@ -97,6 +97,7 @@ This documentation covers the installation, configuration, and usage of Dokku -
- [Registry Management](advanced-usage/registry-management.md) - Docker registry integration
- [Repository Management](advanced-usage/repository-management.md) - Git repository settings
- [Build Tracking](advanced-usage/builds.md) - Inspect, cancel, and manage builds
- [Datastore Management](advanced-usage/datastore-management.md) - Create and link datastore services
- [Deployment Tasks](advanced-usage/deployment-tasks.md) - Pre/post deploy hooks
- [Event Logs](advanced-usage/event-logs.md) - Dokku event history
- [Backup and Recovery](advanced-usage/backup-recovery.md) - Data backup strategies
+1 -1
View File
@@ -190,7 +190,7 @@ Available 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 |
+127
View File
@@ -0,0 +1,127 @@
# Datastore Management
```
datastore:app-links <datastore-type> [<app>] # list all datastore service links for a given app
datastore:backup <datastore-type> <service> <bucket-name> [--id <id>]... # create a backup of the datastore service to an existing s3 bucket
datastore:backup-auth <datastore-type> <service> <aws-access-key-id> <aws-secret-access-key>... # set up authentication for backups on the datastore service
datastore:backup-deauth <datastore-type> <service> [--id <id>] # remove backup authentication for the datastore service
datastore:backup-logs <datastore-type> <service> [-t|--tail [<tail-num>]] # print the most recent output of the scheduled backups of the service
datastore:backup-schedule <datastore-type> <service> <schedule> <bucket-name>... # schedule a backup of the datastore service
datastore:backup-schedule-cat <datastore-type> <service> [--id <id>] # cat the crontab line of a scheduled backup for the service
datastore:backup-set-encryption <datastore-type> <service> <passphrase> [--id <id>] # set encryption for all future backups of datastore service
datastore:backup-set-public-key-encryption <datastore-type> <service> <public-key-id> [--id <id>] # set GPG Public Key encryption for all future backups of datastore service
datastore:backup-unschedule <datastore-type> <service> [--id <id>|--all] # unschedule the backup of the datastore service
datastore:backup-unset-encryption <datastore-type> <service> [--id <id>] # unset encryption for future backups of the datastore service
datastore:backup-unset-public-key-encryption <datastore-type> <service> [--id <id>] # unset GPG Public Key encryption for future backups of the datastore service
datastore:clone <datastore-type> <service> <new-service> [--clone-flags...] # create container <new-name> then copy data from <name> into <new-name>
datastore:connect <datastore-type> <service> # connect to the service via the <datastore-type> connection tool
datastore:create <datastore-type> <service> [--create-flags...] # create a datastore service
datastore:create-database <datastore-type> <service> <database> # create a database in the datastore service
datastore:create-user <datastore-type> <service> <user> [<password>] # create a user in the datastore service
datastore:destroy <datastore-type> <service> [-f|--force] # delete the datastore service/data/container if there are no links left
datastore:destroy-database <datastore-type> <service> <database> [-f|--force] # destroy a database created in the datastore service
datastore:destroy-user <datastore-type> <service> <user> [-f|--force] # destroy a user created in the datastore service
datastore:enter <datastore-type> <service> # enter or run a command in a running datastore service container
datastore:exists <datastore-type> <service> # check if the datastore service exists
datastore:export <datastore-type> <service> [-f|--file <path>] [--force] # export a dump of the datastore service database
datastore:expose <datastore-type> <service> <ports...> # expose a datastore service on custom host:port if provided (random port on the 0.0.0.0 interface if otherwise unspecified)
datastore:help [<datastore-type> [<command>]] # print the help for every datastore, one datastore or one of its commands
datastore:import <datastore-type> <service> [-f|--file <path>] # import a dump into the datastore service database
datastore:info <datastore-type> [<service>] [--info-flags...] # print the service information
datastore:label <datastore-type> <service> <key=value>... # add docker labels to the service container
datastore:link <datastore-type> <service> [<app>] [--link-flags...] # link the datastore service to the app
datastore:linked <datastore-type> <service> [<app>] # check if the datastore service is linked to an app
datastore:links <datastore-type> <service> # list all apps linked to the datastore service
datastore:list <datastore-type> # list all datastore services
datastore:logs <datastore-type> <service> [-t|--tail [<tail-num>]] # print the most recent log(s) for this service
datastore:mount <datastore-type> [--replace] <service> <source:container-dir[:options]>... # mount a host path or docker volume into the service container
datastore:pause <datastore-type> <service> # pause a running datastore service
datastore:promote <datastore-type> <service> [<app>] # promote service <service> as DATABASE_URL in <app>
datastore:reexpose <datastore-type> <service> # reexpose a datastore service, applying its expose settings
datastore:reset <datastore-type> <service> [-f|--force] # delete all data in the datastore service, keeping the service and its links
datastore:restart <datastore-type> <service> # graceful shutdown and restart of the datastore service container
datastore:set <datastore-type> <service> <key> [<value>]... # set or clear a property for a service
datastore:set-user-password <datastore-type> <service> <user> [<password>]... # change the password of a user created in the datastore service
datastore:start <datastore-type> <service> # start a previously stopped datastore service
datastore:stop <datastore-type> <service> # stop a running datastore service
datastore:unexpose <datastore-type> <service> # unexpose a previously exposed datastore service
datastore:unlabel <datastore-type> [--all] <service> [<key>...] # remove one or all docker labels from the service container
datastore:unlink <datastore-type> <service> [<app>] [-n|--no-restart] # unlink the datastore service from the app
datastore:unmount <datastore-type> [--all] <service> [<source:container-dir>...] # remove one or all mounts from the service container
datastore:upgrade <datastore-type> <service> [--upgrade-flags...] # upgrade service <service> to the specified versions
datastore:version # print the version of dokku-datastore the plugin runs
```
The `datastore` plugin manages datastore services such as postgres, mysql and redis, and links them to apps. Every command takes the datastore type as its first argument, and the datastores it serves are the ones the [official datastore plugins](/docs/community/plugins.md#official-plugins) provide: clickhouse, couchdb, elasticsearch, graphite, mariadb, meilisearch, memcached, mongo, mysql, nats, omnisci, postgres, pushpin, rabbitmq, redis, rethinkdb, solr and typesense.
The plugin is built from [dokku-datastore](https://github.com/dokku/dokku-datastore), which the official datastore plugins also run, and keeps its services in the same place they do, under `/var/lib/dokku/services`.
## Usage
### Creating and linking a service
A service is created with `datastore:create` and linked to an app with `datastore:link`, which sets the variable the app connects with, such as `DATABASE_URL` for postgres or `REDIS_URL` for redis, and restarts the app.
```shell
dokku datastore:create postgres lollipop
dokku datastore:link postgres lollipop node-js-app
```
`datastore:unlink` removes the link, and `datastore:destroy` removes a service once nothing is linked to it.
```shell
dokku datastore:unlink postgres lollipop node-js-app
dokku datastore:destroy postgres lollipop
```
Deleting an app unlinks it from every service it is linked to.
### Getting help
`datastore:help` lists the datastore types and the commands they share. Not every datastore implements every command, so the help for one datastore lists only the commands it implements, including ones only it has, such as `connect-admin` for mongo. The help for one of a datastore's commands describes its flags and shows examples.
```shell
dokku datastore:help
dokku datastore:help postgres
dokku datastore:help postgres create
```
### Scheduled backups
A backup scheduled with `datastore:backup-schedule` is added to the dokku crontab as a `dokku datastore:backup` command, and is managed with the [cron plugin](/docs/processes/scheduled-cron-tasks.md) like any other scheduled task.
```shell
dokku datastore:backup-auth postgres lollipop AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY
dokku datastore:backup-schedule postgres lollipop "0 3 * * *" my-s3-bucket
```
### Images
Installing dokku does not pull the image of every datastore. A datastore's images are pulled the first time a command needs them, and on later installs and upgrades once the datastore has a service.
### Official datastore plugins
The official datastore plugins, such as [dokku-postgres](https://github.com/dokku/dokku-postgres), may be installed alongside the `datastore` plugin. While one is enabled, the `datastore` plugin leaves that datastore to it when dokku runs plugin triggers, such as unlinking an app that is being deleted or writing scheduled backups into the crontab. Commands for that datastore should be run through the official plugin until it is removed.
The `datastore` plugin does not read the datastore definitions an official plugin ships, so a host running a modified official plugin should keep using it.
#### Migrating from an official datastore plugin
Moving a datastore from its official plugin to the `datastore` plugin leaves its services, containers, data, settings and links where they are, and does not stop running services or the apps linked to them. Using postgres as an example:
1. Check that `dokku datastore:version` is at least the version dokku-postgres runs, which is printed by `/var/lib/dokku/data/postgres/dokku-datastore version`. If the official plugin runs a newer version, wait for a dokku release that ships it.
2. Uninstall the official plugin.
```shell
dokku plugin:uninstall postgres
```
3. Run every plugin's install trigger, which sets the host up for postgres, brings its services up to date and rewrites the crontab so scheduled backups run through `dokku datastore:backup`.
```shell
dokku plugin:install
```
4. Change anything that runs `dokku postgres:<command> <service>` to run `dokku datastore:<command> postgres <service>`.
To move back, install the official plugin again from a release running at least the version `dokku datastore:version` prints.
+1 -1
View File
@@ -142,7 +142,7 @@ app2.json
#### `app.json` deployment tasks
Dokku provides limited support for the `app.json` manifest from Heroku (documentation available [here](https://devcenter.heroku.com/articles/app-json-schema)). The keys available for use with Deployment Tasks are:
Dokku provides limited support for the `app.json` manifest from Heroku (see the [app.json schema documentation](https://devcenter.heroku.com/articles/app-json-schema)). The keys available for use with Deployment Tasks are:
- `scripts.dokku.predeploy`: This is run _after_ an app's docker image is built, but _before_ any containers are scheduled. Changes made to your image are committed at this phase.
- `scripts.dokku.postdeploy`: This is run _after_ an app's containers are scheduled. Changes made to your image are _not_ committed at this phase.
+2 -2
View File
@@ -34,7 +34,7 @@ Adding or removing docker-options will not apply to any running containers, and
#### Supported Docker Options
More information on supported Docker options can be found [here](https://docs.docker.com/engine/reference/commandline/run/).
More information on supported Docker options can be found in the [docker run reference](https://docs.docker.com/engine/reference/commandline/run/).
Container options configured via the `docker-options` plugin are not used to modify the process a container runs. Container options are the `[OPTIONS]` portion of the following, where `[CONTAINER_COMMAND]` and `[ARG]` are the process and the arguments passed to it that are launched in the created container: `docker run [OPTIONS] [CONTAINER_COMMAND] [ARG...]`. Please see the documentation for [customizing the run command](/docs/deployment/builders/dockerfiles.md#customizing-the-run-command) or use a [Procfile](/docs/deployment/builders/dockerfiles.md#procfiles-and-multiple-processes) to modify the command used by a Dockerfile-based container.
@@ -288,7 +288,7 @@ dokku docker-options:list node-js-app --phase deploy
The following properties are recorded internally by the docker-options plugin and are not exposed via `docker-options:report`:
| Property | Scope | Description | Source |
|---|---|---|---|
| --- | --- | --- | --- |
| `migrated-from-files` | global | 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 |
| `migrated-build` | per-app | Per-app marker recording that the app's legacy `DOCKER_OPTIONS_BUILD` file was drained into the `_default_.build` property list. Only set when the legacy file contained non-empty content | `plugins/docker-options/functions.go` writes `"true"` after the per-phase drain |
| `migrated-deploy` | per-app | Per-app marker recording that the app's legacy `DOCKER_OPTIONS_DEPLOY` file was drained into the `_default_.deploy` property list. Only set when the legacy file contained non-empty content | `plugins/docker-options/functions.go` writes `"true"` after the per-phase drain |
+2 -2
View File
@@ -172,7 +172,7 @@ dokku storage:set node-js-data chown
The following properties can be set:
| Property | Description | Unsetting it means |
|---|---|---|
| --- | --- | --- |
| `chown` | Ownership preset or numeric uid for the host directory | no chown is performed |
| `mode` | Octal permissions for the host directory | permissions are left alone |
| `namespace` | Namespace holding the PVC (k3s) | the `default` namespace |
@@ -324,7 +324,7 @@ dokku storage:mount --replace node-js-app \
```
| Token | Meaning |
|---|---|
| --- | --- |
| `ro` | Mount the volume read-only |
| `rw` | Mount it read-write, the explicit opposite of `ro` and the default |
| `volume-subpath=<path>` | Subpath within the entry |
+2 -2
View File
@@ -283,7 +283,7 @@ dokku registry:set --global push-extra-tags
> The `Report flags` column lists the CLI argument names accepted by `registry:report`. The JSON keys emitted by `registry:report --format json` are the same names with the leading `--registry-` stripped (e.g. `image-repo`, `global-server`, `computed-push-on-release`). Legacy keys with the `registry-` prefix (e.g. `registry-image-repo`) are also emitted during the 0.38.x deprecation window and will be removed in a future major release.
| 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` | app + global | none | `--registry-image-repo-template`, `--registry-global-image-repo-template`, `--registry-computed-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`, `--registry-global-push-extra-tags`, `--registry-computed-push-extra-tags` | Comma-separated list of additional tags pushed alongside the deploy tag |
@@ -298,7 +298,7 @@ dokku registry:set --global push-extra-tags
The following `registry:report` fields describe credentials created by `registry:login` and are not settable via `registry:set`.
| Report flag | Scope | Description |
|---|---|---|
| --- | --- | --- |
| `--registry-auth-servers` | app only | Comma-separated list of servers the app has its own credentials for |
| `--registry-global-auth-servers` | app + global | Comma-separated list of servers the global credentials cover |
| `--registry-computed-auth-servers` | app + global | Comma-separated list of servers whose credentials would be used for the app |
+1 -1
View File
@@ -45,7 +45,7 @@ A number of `DOKKU_*` config environment variables have been replaced with prope
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>` |
+2 -2
View File
@@ -5,11 +5,11 @@
- The nginx-vhosts template language is now [sigil](https://github.com/gliderlabs/sigil)
- No need to escape literal `$` characters (or other "bash-isms")
- Template variables are represented as {{ .VARIABLE_NAME }}
- A detailed list of template variables can be found [here](/docs/networking/proxies/nginx.md#available-template-variables)
- A detailed list of template variables can be found in the [available template variables documentation](/docs/networking/proxies/nginx.md#available-template-variables)
- A custom nginx-vhosts template must be named `nginx.conf.sigil`
- The default path for this custom template is the root of your repo (i.e. `/app` in the container or `WORKDIR` if defined in a dockerfile app)
- Dokku no longer looks for this file in `/home/dokku/node-js-app` on the Dokku server
- Check out an example template [here](/docs/networking/proxies/nginx.md)
- Check out an [example template](/docs/networking/proxies/nginx.md)
- Support for server-wide SSL certs have been dropped in favor of using the `certs` plugin
- `dokku certs:add node-js-app < certs.tar`
- All domains for an SSL-enabled app will be redirected to https by default
@@ -1,6 +1,6 @@
# nginx.conf.sigil
The `nginx.conf.sigil` file is used to configure the nginx server for an application. The default template can be found [here](https://github.com/dokku/dokku/blob/master/plugins/nginx-vhosts/templates/nginx.conf.sigil). Dokku uses a tool named [sigil](https://github.com/gliderlabs/sigil) to generate the nginx configuration based on the template provided.
The `nginx.conf.sigil` file is used to configure the nginx server for an application. The [default template](https://github.com/dokku/dokku/blob/master/plugins/nginx-vhosts/templates/nginx.conf.sigil) is in the nginx-vhosts plugin. Dokku uses a tool named [sigil](https://github.com/gliderlabs/sigil) to generate the nginx configuration based on the template provided.
## Validation
+3 -1
View File
@@ -22,6 +22,8 @@ Let's take a quick look at the current Dokku nginx plugin that's shipped with Do
The following plugins are available and provided by Dokku maintainers. Please file issues against their respective issue trackers.
Every datastore below is also served by the `datastore` plugin Dokku ships, as in `dokku datastore:create postgres lollipop`. See the [datastore management documentation](/docs/advanced-usage/datastore-management.md) for more information.
| Plugin | Author | Compatibility |
| ------------------------------------------------------------------------------------------------- | --------------------- | --------------------- |
| [Clickhouse](https://github.com/dokku/dokku-clickhouse) | [dokku][] | 0.4.0+ |
@@ -231,7 +233,7 @@ The following plugins are no longer maintained by their developers.
| [CouchDB (multi containers)](https://github.com/Flink/dokku-couchdb-multi-containers) | [flink][] | 0.4.0+ |
| [CouchDB](https://github.com/racehub/dokku-couchdb-plugin) | [raceHub][] | Compatible with 0.2.0 |
| [Dokku Copy App Config Files](https://github.com/alexkruegger/dokku-app-configfiles) | [alexkruegger][] | Compatible with 0.3.17+ |
| [Dokku Registry](https://github.com/agco-adm/dokku-registry) | [agco-adm][] | 0.4.0+
| [Dokku Registry](https://github.com/agco-adm/dokku-registry) | [agco-adm][] | 0.4.0+ |
| [Elasticsearch](https://github.com/robv/dokku-elasticsearch) | [robv][] | Not compatible with >= 0.3.0 (still uses /home/git) |
| [Elasticsearch](https://github.com/blag/dokku-elasticsearch-plugin)<sup>1</sup> | [blag][] | Compatible with 0.2.0 |
| [Graphite/statsd](https://github.com/jlachowski/dokku-graphite-plugin) | [jlachowski][] | < 0.4.0 |
+1 -1
View File
@@ -164,7 +164,7 @@ See the [running behind another proxy documentation](/docs/networking/proxies/ng
The following flags surface in `certs:report` but are not managed by `certs:set` - they are derived from the on-disk certificate:
| Flag | Description |
|---|---|
| --- | --- |
| `--ssl-enabled` | `true` when an SSL certificate is installed for the app |
| `--ssl-dir` | Absolute path to the per-app certificate directory |
| `--ssl-hostnames` | Hostnames the certificate covers (CN plus Subject Alternative Names) |
+1 -1
View File
@@ -347,7 +347,7 @@ dokku apps:report node-js-app --app-dir
The following flags surface in `apps:report` but are not managed by `apps:set`:
| Flag | Description |
|---|---|
| --- | --- |
| `--app-created-at` | UNIX timestamp of app creation |
| `--app-deploy-source` | Source kind of the last deploy (`git`, `archive`, `docker-image`, `git-sync`) |
| `--app-deploy-source-metadata` | Free-form metadata for the deploy source (commit sha, image ref, URL) |
@@ -183,7 +183,7 @@ For a simple example of how to implement this trigger, see `builder-pack`, which
> The `Report flags` column lists the CLI argument names accepted by `builder:report`. The JSON keys emitted by `builder:report --format json` are the same names with the leading `--builder-` stripped (e.g. `selected`, `global-selected`, `computed-selected`). Legacy keys with the `builder-` prefix are also emitted during the 0.38.x deprecation window and will be removed in a future major release.
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `build-dir` | app + global | none | `--builder-build-dir`, `--builder-global-build-dir`, `--builder-computed-build-dir` | Subdirectory within the repository to use as the build context |
| `selected` | app + global | none | `--builder-selected`, `--builder-global-selected`, `--builder-computed-selected` | Builder plugin to use; overrides automatic detection |
| `skip-cleanup` | app + global | `false` | `--builder-skip-cleanup`, `--builder-global-skip-cleanup`, `--builder-computed-skip-cleanup` | When `true`, leaves intermediate build artifacts in place after the build |
+2 -2
View File
@@ -316,7 +316,7 @@ dokku logs:set --global vector-cron-sink "console://?encoding[codec]=text"
Setting a cron sink **moves** cron task output rather than copying it. Vector routes each log line to exactly one of the two sinks:
| Configuration | Where cron output goes | Where all other output goes |
|---|---|---|
| --- | --- | --- |
| `vector-sink` only | `vector-sink` | `vector-sink` |
| `vector-cron-sink` only | `vector-cron-sink` | nowhere |
| both | `vector-cron-sink` | `vector-sink` |
@@ -398,7 +398,7 @@ The alias only changes the shipped event. Containers are always discovered by th
> The `Report flags` column lists the CLI argument names accepted by `logs:report`. The JSON keys emitted by `logs:report --format json` are the same names with the leading `--logs-` stripped (e.g. `max-size`, `global-max-size`, `computed-max-size`). Legacy keys with the `logs-` prefix are also emitted during the 0.38.x deprecation window and will be removed in a future major release.
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `app-label-alias` | app + global | `com.dokku.app-name` | `--logs-app-label-alias`, `--logs-global-app-label-alias`, `--logs-computed-app-label-alias` | Field name the app name is shipped under, renamed from `com.dokku.app-name` on the event |
| `max-size` | app + global | `10m` | `--logs-max-size`, `--logs-global-max-size`, `--logs-computed-max-size` | Maximum size of an individual log file before rotation |
| `vector-image` | global only | _parsed from `plugins/logs/Dockerfile`_ | `--logs-global-vector-image`, `--logs-computed-vector-image` | Docker image used to run the vector log-shipper container |
+2 -2
View File
@@ -339,7 +339,7 @@ The `--format` flag cannot be combined with an info flag.
### Settable properties
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `archive-max-files` | app + global | none | `--git-global-archive-max-files`, `--git-computed-archive-max-files` | Maximum number of files allowed in an uploaded archive deploy |
| `archive-max-size` | app + global | none | `--git-global-archive-max-size`, `--git-computed-archive-max-size` | Maximum total size of an uploaded archive deploy |
| `deploy-branch` | app + global | `master` | `--git-deploy-branch`, `--git-global-deploy-branch`, `--git-computed-deploy-branch` | Branch name pushed by the git remote that triggers a deploy |
@@ -352,6 +352,6 @@ The `--format` flag cannot be combined with an info flag.
The following flags surface in `git:report` but are not managed by `git:set` - they are derived from repository state:
| Flag | Description |
|---|---|
| --- | --- |
| `--git-sha` | HEAD commit SHA of the app's git repo |
| `--git-last-updated-at` | UNIX timestamp of the last write to the deploy branch ref |
+1 -1
View File
@@ -222,6 +222,6 @@ The `docker-local` scheduler supports a minimal list of resource _limits_ and _r
### Settable properties
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `init-process` | app + global | `true` | `--scheduler-docker-local-init-process`, `--scheduler-docker-local-global-init-process`, `--scheduler-docker-local-computed-init-process` | When `true`, runs containers with Docker's `--init` flag (reaping zombie processes) |
| `parallel-schedule-count` | app + global | `1` | `--scheduler-docker-local-parallel-schedule-count`, `--scheduler-docker-local-global-parallel-schedule-count`, `--scheduler-docker-local-computed-parallel-schedule-count` | Maximum number of containers scheduled in parallel during a deploy |
+1 -1
View File
@@ -1341,7 +1341,7 @@ If unspecified for any task, the default reservation will be `.1` CPU and `128Mi
> The `Report flags` column lists the CLI argument names accepted by `scheduler-k3s:report`. The JSON keys emitted by `scheduler-k3s:report --format json` are the same names with the leading `--scheduler-k3s-` stripped (e.g. `deploy-timeout`, `global-deploy-timeout`, `computed-deploy-timeout`). Legacy keys with the `scheduler-k3s-` prefix are also emitted during the 0.38.x deprecation window and will be removed in a future major release.
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `cert-issuer-kind` | app + global | `ClusterIssuer` | `--scheduler-k3s-cert-issuer-kind`, `--scheduler-k3s-global-cert-issuer-kind`, `--scheduler-k3s-computed-cert-issuer-kind` | Kind of the manually managed cert-manager issuer referenced by `cert-issuer-name`, either `Issuer` or `ClusterIssuer` |
| `cert-issuer-name` | app + global | none | `--scheduler-k3s-cert-issuer-name`, `--scheduler-k3s-global-cert-issuer-name`, `--scheduler-k3s-computed-cert-issuer-name` | Name of a manually managed cert-manager issuer to request certificates from, taking precedence over the letsencrypt integration. Set to `false` to opt an app out of a global value |
| `deploy-timeout` | app + global | `300s` | `--scheduler-k3s-deploy-timeout`, `--scheduler-k3s-global-deploy-timeout`, `--scheduler-k3s-computed-deploy-timeout` | Timeout for a single helm install/upgrade cycle |
@@ -156,6 +156,6 @@ Deployment tasks are currently executed directly on the primary Dokku server.
> The `Report flags` column lists the CLI argument names accepted by `scheduler:report`. The JSON keys emitted by `scheduler:report --format json` are the same names with the leading `--scheduler-` stripped (e.g. `selected`, `global-selected`, `computed-selected`). Legacy keys with the `scheduler-` prefix are also emitted during the 0.38.x deprecation window and will be removed in a future major release.
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `selected` | app + global | `docker-local` | `--scheduler-selected`, `--scheduler-global-selected`, `--scheduler-computed-selected` | Scheduler plugin used to deploy this app (`docker-local`, `k3s`, etc.) |
| `shell` | app + global | none | `--scheduler-shell`, `--scheduler-global-shell`, `--scheduler-computed-shell` | Shell used by `enter`/`run` commands when entering a container |
+2 -2
View File
@@ -141,7 +141,7 @@ Plugins communicate through the **trigger system** powered by [plugn](https://gi
**Key trigger categories:**
| Category | Examples | Purpose |
|----------|----------|---------|
| ---------- | ---------- | --------- |
| App lifecycle | `post-create`, `pre-delete`, `post-deploy` | React to app events |
| Build | `builder-detect`, `pre-build`, `builder-build` | Control build process |
| Deploy | `scheduler-deploy`, `check-deploy` | Manage deployments |
@@ -333,7 +333,7 @@ Global settings can be configured via:
## Key Design Decisions
| Decision | Rationale |
|----------|-----------|
| ---------- | ----------- |
| **Plugin-based architecture** | Enables extensibility without modifying core code. Community plugins can add databases, caching, and other services. |
| **Bash + Go hybrid** | Bash for orchestration and simple commands; Go for performance-critical operations and complex logic. |
| **Trigger system** | Loose coupling between plugins. Plugins don't need to know about each other; they just fire and respond to events. |
+1 -1
View File
@@ -534,7 +534,7 @@ dokku network:report node-js-app --network-bind-all-interfaces
> The `Report flags` column lists the CLI argument names accepted by `network:report`. The JSON keys emitted by `network:report --format json` are the same names with the leading `--network-` stripped (e.g. `attach-post-create`, `global-attach-post-create`, `computed-attach-post-create`). Legacy keys with the `network-` prefix (e.g. `network-attach-post-create`) are also emitted during the 0.38.x deprecation window and will be removed in a future major release.
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `attach-post-create` | app + global | none | `--network-attach-post-create`, `--network-global-attach-post-create`, `--network-computed-attach-post-create` | Networks attached to a container immediately after creation, before the deploy phase |
| `attach-post-deploy` | app + global | none | `--network-attach-post-deploy`, `--network-global-attach-post-deploy`, `--network-computed-attach-post-deploy` | Networks attached to a container after it passes healthchecks |
| `bind-all-interfaces` | app + global | `false` | `--network-bind-all-interfaces`, `--network-global-bind-all-interfaces`, `--network-computed-bind-all-interfaces` | When `true`, binds containers to `0.0.0.0` instead of the default Docker network address |
+2 -2
View File
@@ -272,7 +272,7 @@ dokku ports:report node-js-app --ports-map-detected-json | jq '.[0].container_po
The following flags surface configured port mappings managed by `ports:set` / `ports:add` / `ports:remove` / `ports:clear`:
| Flag | Description |
|---|---|
| --- | --- |
| `--ports-map` | Configured port mappings as space-separated `scheme:host-port:container-port` values |
| `--ports-map-json` | Configured port mappings as a JSON array of `{scheme, host_port, container_port}` objects |
@@ -281,6 +281,6 @@ The following flags surface configured port mappings managed by `ports:set` / `p
The following flags surface in `ports:report` but are not managed by `ports:set` - they are derived from the deploy:
| Flag | Description |
|---|---|
| --- | --- |
| `--ports-map-detected` | Port mapping inferred from `EXPOSE` directives or the running container |
| `--ports-map-detected-json` | Detected port mappings as a JSON array of `{scheme, host_port, container_port}` objects |
+1 -1
View File
@@ -271,7 +271,7 @@ dokku caddy:report node-js-app --caddy-computed-image
### Settable properties
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `image` | global only | _parsed from `plugins/caddy-vhosts/Dockerfile`_ | `--caddy-global-image`, `--caddy-computed-image` | Docker image used to run the Caddy container |
| `letsencrypt-email` | global only | none | `--caddy-global-letsencrypt-email`, `--caddy-computed-letsencrypt-email` | Contact email enabling letsencrypt; empty disables https issuance |
| `letsencrypt-server` | global only | `https://acme-v02.api.letsencrypt.org/directory` | `--caddy-global-letsencrypt-server`, `--caddy-computed-letsencrypt-server` | ACME directory used when requesting certificates |
+1 -1
View File
@@ -254,7 +254,7 @@ dokku haproxy:report node-js-app --haproxy-computed-image
All haproxy properties are global only. Set with `haproxy:set --global <property> <value>`.
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `image` | global only | _parsed from `plugins/haproxy-vhosts/Dockerfile`_ | `--haproxy-global-image`, `--haproxy-computed-image` | Docker image used to run the Haproxy container |
| `letsencrypt-email` | global only | none | `--haproxy-global-letsencrypt-email`, `--haproxy-computed-letsencrypt-email` | Contact email enabling letsencrypt; empty disables https issuance |
| `letsencrypt-server` | global only | `https://acme-v02.api.letsencrypt.org/directory` | `--haproxy-global-letsencrypt-server`, `--haproxy-computed-letsencrypt-server` | ACME directory used when requesting certificates |
+2 -2
View File
@@ -634,7 +634,7 @@ See the [proxy documentation](/docs/networking/proxy-management.md#regenerating-
All nginx-vhosts properties are settable at both the app and global scope.
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `access-log-format` | app + global | none | `--nginx-access-log-format`, `--nginx-global-access-log-format`, `--nginx-computed-access-log-format` | Custom nginx `log_format` directive used for the access log |
| `access-log-path` | app + global | _`{nginx-log-root}/{app}-access.log`_ | `--nginx-access-log-path`, `--nginx-global-access-log-path`, `--nginx-computed-access-log-path` | Path inside the nginx container where access logs are written |
| `bind-address-ipv4` | app + global | none | `--nginx-bind-address-ipv4`, `--nginx-global-bind-address-ipv4`, `--nginx-computed-bind-address-ipv4` | IPv4 address the nginx server block binds to |
@@ -681,6 +681,6 @@ The following flag surfaces in `nginx:report` but is not managed by `nginx:set`:
The following properties are recorded internally by the plugin and are not exposed via `nginx:report`:
| Property | Description | Source |
|---|---|---|
| --- | --- | --- |
| `proxy-status` | `started`/`stopped` state of the nginx system service | `cmd-nginx-start`/`cmd-nginx-stop` |
| `nginx-conf-sigil-migrated` | 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 |
+1 -1
View File
@@ -291,7 +291,7 @@ Global-only properties expose two report flags: `--openresty-global-<property>`
App-or-global properties expose three report flags: `--openresty-<property>` returns the raw per-app value (empty when unset), `--openresty-global-<property>` returns the raw global value (empty when unset), and `--openresty-computed-<property>` returns the effective value, resolving the per-app value first, then the global value, then the built-in default.
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `access-log-format` | app or global | none | `--openresty-access-log-format`, `--openresty-global-access-log-format`, `--openresty-computed-access-log-format` | Custom nginx `log_format` directive used for the access log |
| `access-log-path` | app or global | _`/var/log/nginx/{app}-access.log`_ | `--openresty-access-log-path`, `--openresty-global-access-log-path`, `--openresty-computed-access-log-path` | Path inside the openresty container where access logs are written |
| `allowed-letsencrypt-domains-func-base64` | global only | _allow-all stub_ | `--openresty-global-allowed-letsencrypt-domains-func-base64`, `--openresty-computed-allowed-letsencrypt-domains-func-base64` | Base64-encoded Lua function deciding which domains may request a letsencrypt certificate |
+1 -1
View File
@@ -408,7 +408,7 @@ dokku traefik:report node-js-app --traefik-computed-api-enabled
All traefik properties are global only. Set with `traefik:set --global <property> <value>`.
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `api-enabled` | global only | `false` | `--traefik-global-api-enabled`, `--traefik-computed-api-enabled` | When `true`, enables the Traefik HTTP API |
| `api-entry-point` | global only | none | `--traefik-global-api-entry-point`, `--traefik-computed-api-entry-point` | Name of the entry point used by the Traefik API |
| `api-entry-point-address` | global only | none | `--traefik-global-api-entry-point-address`, `--traefik-computed-api-entry-point-address` | Address (`host:port`) the Traefik API listens on |
+1 -1
View File
@@ -245,7 +245,7 @@ Finally, proxy implementations _may_ install extra software needed for the proxy
> The `Report flags` column lists the CLI argument names accepted by `proxy:report`. The JSON keys emitted by `proxy:report --format json` are the same names with the leading `--proxy-` stripped (e.g. `type`, `global-type`, `computed-type`). Legacy keys with the `proxy-` prefix (e.g. `proxy-type`) are also emitted during the 0.38.x deprecation window and will be removed in a future major release.
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `disabled` | app only | `false` | `--proxy-disabled`, `--proxy-computed-disabled` (also exposed inverted as `--proxy-enabled`) | When `true`, disables proxy integration for this app (`proxy:enable`/`proxy:disable` write this) |
| `proxy-port` | app + global | none | `--proxy-proxy-port`, `--proxy-global-proxy-port`, `--proxy-computed-proxy-port` | Override port used for the HTTP listener in the generated proxy config |
| `proxy-ssl-port` | app + global | none | `--proxy-proxy-ssl-port`, `--proxy-global-proxy-ssl-port`, `--proxy-computed-proxy-ssl-port` | Override port used for the HTTPS listener in the generated proxy config |
+2 -2
View File
@@ -566,7 +566,7 @@ dokku ps:set node-js-app restore
> The `Report flags` column lists the CLI argument names accepted by `ps:report`. The JSON keys emitted by `ps:report --format json` are the same names with the leading `--ps-` stripped (e.g. `procfile-path`, `global-procfile-path`, `computed-procfile-path`). Legacy keys with the `ps-` prefix (e.g. `ps-procfile-path`) are also emitted during the 0.38.x deprecation window and will be removed in a future major release.
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `dockerfile-start-cmd` | app only | none | `--ps-dockerfile-start-cmd`, `--ps-computed-dockerfile-start-cmd` | Override `CMD` for Dockerfile-based apps |
| `procfile-path` | app + global | `Procfile` | `--ps-procfile-path`, `--ps-global-procfile-path`, `--ps-computed-procfile-path` | Path to the app's Procfile, relative to the build root |
| `restart-policy` | app + global | `on-failure:10` | `--ps-restart-policy`, `--ps-global-restart-policy`, `--ps-computed-restart-policy` | Docker restart policy applied to deployed containers (`no`, `always`, `unless-stopped`, `on-failure[:max-retries]`) |
@@ -580,7 +580,7 @@ dokku ps:set node-js-app restore
The following flags surface in `ps:report` but are not managed by `ps:set` - they are derived from the running process state:
| Flag | Description |
|---|---|
| --- | --- |
| `--ps-can-scale` | `false` when the app's procfile or builder forbids horizontal scaling |
| `--deployed` | `true` after the first successful deploy |
| `--running` | `true` while any container for the app is running |
+1 -1
View File
@@ -338,7 +338,7 @@ SHELL=/bin/bash
> The `Report flags` column lists the CLI argument names accepted by `cron:report`. The JSON keys emitted by `cron:report --format json` are the same names with the leading `--cron-` stripped (e.g. `global-mailto`, `computed-mailto`, `maintenance`). Legacy keys with the `cron-` prefix (e.g. `cron-global-mailto`) are also emitted during the 0.38.x deprecation window and will be removed in a future major release.
| Property | Scope | Default | Report flags | Description |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `mailfrom` | global only | none | `--cron-global-mailfrom`, `--cron-computed-mailfrom` | `From:` address used in cron failure emails |
| `mailto` | global only | none | `--cron-global-mailto`, `--cron-computed-mailto` | Recipient address for cron failure emails; empty disables email |
| `maintenance` | app + global | `false` | `--cron-maintenance`, `--cron-global-maintenance`, `--cron-computed-maintenance` | When `true`, suspends all cron tasks for the app (or globally) |
+1
View File
@@ -190,6 +190,7 @@
<a href="/{{NAME}}/advanced-usage/backup-recovery/" class="list-group-item">Backup and Recovery</a>
<a href="/{{NAME}}/advanced-usage/builds/" class="list-group-item">Build Tracking</a>
<a href="/{{NAME}}/advanced-usage/datastore-management/" class="list-group-item">Datastore Management</a>
<a href="/{{NAME}}/advanced-usage/deployment-tasks/" class="list-group-item">Deployment Tasks</a>
<a href="/{{NAME}}/advanced-usage/docker-options/" class="list-group-item">Docker Container Options</a>
<a href="/{{NAME}}/advanced-usage/registry-management/" class="list-group-item">Docker Registry Management</a>