From d61d91cf87fbc7fa8643a4e64325ba8490641370 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sat, 19 Aug 2023 14:24:12 -0400 Subject: [PATCH] docs: use github admonitions These still need to be properly parsed. --- HISTORY.md | 3 +- docs/advanced-usage/backup-recovery.md | 3 +- docs/advanced-usage/deployment-tasks.md | 9 ++- docs/advanced-usage/docker-options.md | 5 +- docs/advanced-usage/event-logs.md | 1 + docs/advanced-usage/persistent-storage.md | 13 +++- docs/advanced-usage/plugin-management.md | 7 +- docs/advanced-usage/registry-management.md | 1 + docs/advanced-usage/repository-management.md | 1 + docs/advanced-usage/resource-management.md | 4 +- docs/community/plugins.md | 3 +- docs/configuration/domains.md | 2 + docs/configuration/environment-variables.md | 6 +- docs/configuration/ssl.md | 8 +- docs/deployment/application-deployment.md | 15 ++-- docs/deployment/application-management.md | 14 +++- .../deployment/builders/builder-management.md | 4 +- .../builders/cloud-native-buildpacks.md | 6 +- docs/deployment/builders/dockerfiles.md | 3 + .../builders/herokuish-buildpacks.md | 7 +- docs/deployment/builders/lambda.md | 1 + docs/deployment/builders/null.md | 1 + docs/deployment/logs.md | 7 +- docs/deployment/methods/git.md | 13 +++- docs/deployment/schedulers/docker-local.md | 4 + docs/deployment/schedulers/kubernetes.md | 3 +- docs/deployment/schedulers/nomad.md | 6 +- docs/deployment/schedulers/null.md | 1 + .../schedulers/scheduler-management.md | 1 + docs/deployment/user-management.md | 3 + docs/deployment/zero-downtime-deploys.md | 6 +- docs/development/plugin-creation.md | 4 + docs/development/plugin-triggers.md | 78 ++++++++++++------- docs/getting-started/troubleshooting.md | 1 + docs/networking/dns.md | 3 +- docs/networking/network.md | 13 +++- docs/networking/port-management.md | 10 ++- docs/networking/proxies/caddy.md | 4 +- docs/networking/proxies/haproxy.md | 4 +- docs/networking/proxies/nginx.md | 54 +++++++++---- docs/networking/proxies/openresty.md | 4 +- docs/networking/proxies/traefik.md | 10 ++- docs/networking/proxy-management.md | 3 + docs/processes/entering-containers.md | 1 + docs/processes/one-off-tasks.md | 5 ++ docs/processes/process-management.md | 7 +- docs/processes/scheduled-cron-tasks.md | 4 +- 47 files changed, 277 insertions(+), 89 deletions(-) diff --git a/HISTORY.md b/HISTORY.md index 1cb8993a2..82bfe5595 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -2869,7 +2869,8 @@ sudo DOKKU_TAG=v0.21.1 bash bootstrap.sh ## 0.21.0 -> Warning: Release is broken and will be pulled from upstream. Please use a newer version. +> [!WARNING] +> Release is broken and will be pulled from upstream. Please use a newer version. ### Bug Fixes diff --git a/docs/advanced-usage/backup-recovery.md b/docs/advanced-usage/backup-recovery.md index df487834b..13b2cc84d 100644 --- a/docs/advanced-usage/backup-recovery.md +++ b/docs/advanced-usage/backup-recovery.md @@ -6,7 +6,8 @@ The best plan for disaster recovery is to always keep multiple (remote) copies o ## TLDR -> Warning: This method has many caveats. Please read this entire document before assuming these backups work as expected, and test your backups on a regular basis. +> [!WARNING] +> This method has many caveats. Please read this entire document before assuming these backups work as expected, and test your backups on a regular basis. ### Creating a backup diff --git a/docs/advanced-usage/deployment-tasks.md b/docs/advanced-usage/deployment-tasks.md index c93b7c456..ee62d4f70 100644 --- a/docs/advanced-usage/deployment-tasks.md +++ b/docs/advanced-usage/deployment-tasks.md @@ -1,5 +1,6 @@ # Deployment Tasks +> [!IMPORTANT] > New as of 0.5.0 ## Usage @@ -83,6 +84,7 @@ dokku app-json:set --global appjson-path ### Displaying app-json reports for an app +> [!IMPORTANT] > New as of 0.25.0 You can get a report about the app's storage status using the `app-json:report` command: @@ -139,7 +141,8 @@ Dokku provides limited support for the `app.json` manifest from Heroku (document - `scripts.dokku.postdeploy`: This is run _after_ an app's containers are scheduled. Changes made to your image are _not_ committed at this phase. - `scripts.postdeploy`: This is run _after_ an app's containers are scheduled. Changes made to your image are _not_ committed at this phase. -> Warning: Any failed `app.json` deployment task will fail the deploy. In the case of either phase, a failure will not affect any running containers. +> [!WARNING] +> Any failed `app.json` deployment task will fail the deploy. In the case of either phase, a failure will not affect any running containers. The following is an example `app.json` file. Please note that only the `scripts.dokku.predeploy` and `scripts.dokku.postdeploy` tasks are supported by Dokku at this time. All other fields will be ignored and can be omitted. @@ -157,6 +160,7 @@ The following is an example `app.json` file. Please note that only the `scripts. #### Procfile Release command +> [!IMPORTANT] > New as of 0.14.0 The `Procfile` also supports a special `release` command which acts in a similar way to the [Heroku Release Phase](https://devcenter.heroku.com/articles/release-phase). This command is executed _after_ an app's docker image is built, but _before_ any containers are scheduled. This is also run _after_ any command executed by `scripts.dokku.predeploy`. @@ -169,4 +173,5 @@ release: curl https://some.external.api.service.com/deployment?state=built Unlike the `scripts.dokku.predeploy` command, changes made during by the `release` command are _not_ persisted to disk. -> Warning: scaling the release command up will likely result in unspecified issues within your deployment, and is highly discouraged. +> [!WARNING] +> scaling the release command up will likely result in unspecified issues within your deployment, and is highly discouraged. diff --git a/docs/advanced-usage/docker-options.md b/docs/advanced-usage/docker-options.md index 153e499cd..b9ef3f55f 100644 --- a/docs/advanced-usage/docker-options.md +++ b/docs/advanced-usage/docker-options.md @@ -1,5 +1,6 @@ # Docker Container Options +> [!IMPORTANT] > New as of 0.3.17 Pass [container options](https://docs.docker.com/engine/reference/run/) to the `docker run` command during Dokku's `build`, `deploy` and `run` phases @@ -43,7 +44,8 @@ dokku docker-options:add node-js-app deploy "-v /var/log/node-js-app:/app/logs" dokku docker-options:add node-js-app run "-v /var/log/node-js-app:/app/logs" ``` -> Note: When [mounting a host directory](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems) in a Dokku app you should first create that directory as user `dokku` and then mount the directory under `/app` in the container using `docker-options` as above. Otherwise the app will lack write permission in the directory. +> [!NOTE] +> When [mounting a host directory](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems) in a Dokku app you should first create that directory as user `dokku` and then mount the directory under `/app` in the container using `docker-options` as above. Otherwise the app will lack write permission in the directory. ### Remove a Docker option @@ -84,6 +86,7 @@ dokku docker-options:clear node-js-app build,run ### Displaying docker-options reports for an app +> [!IMPORTANT] > New as of 0.8.1 You can get a report about the app's docker-options status using the `docker-options:report` command: diff --git a/docs/advanced-usage/event-logs.md b/docs/advanced-usage/event-logs.md index fc05b869a..68b8336a5 100644 --- a/docs/advanced-usage/event-logs.md +++ b/docs/advanced-usage/event-logs.md @@ -1,5 +1,6 @@ # Dokku Event Logs +> [!IMPORTANT] > New as of 0.3.21 Docker provides an _events_ command to show system's real time events. Likewise, Dokku can record events as syslog entries and also provides a plugin to display the last ones. diff --git a/docs/advanced-usage/persistent-storage.md b/docs/advanced-usage/persistent-storage.md index 580764bfa..646519310 100644 --- a/docs/advanced-usage/persistent-storage.md +++ b/docs/advanced-usage/persistent-storage.md @@ -1,5 +1,6 @@ # Persistent Storage +> [!IMPORTANT] > New as of 0.5.0 The preferred method to mount external containers to a Dokku managed container, is to use the Dokku storage plugin. @@ -52,6 +53,7 @@ dokku storage:list node-js-app --format json ### Creating storage directories +> [!IMPORTANT] > New as of 0.25.5 A storage directory can be created with the `storage:ensure-directory` command. This command will create a subdirectory in the recommended `/var/lib/dokku/data/storage` path - created during Dokku installation - and prepare it for use with an app. @@ -78,7 +80,8 @@ By default, permissions are set for usage with Herokuish buildpacks. These permi Users deploying via Dockerfile will want to specify `--chown false` and manually `chown` the created directory if the user and/or group id of the runnning process in the deployed container do not correspond to any of the above options. -> Warning: Failing to set the correct directory ownership may result in issues in persisting files written to the mounted storage directory. +> [!WARNING] +> Failing to set the correct directory ownership may result in issues in persisting files written to the mounted storage directory. ### Mounting storage into apps @@ -124,6 +127,7 @@ dokku ps:restart app-name ### Displaying storage reports for an app +> [!IMPORTANT] > New as of 0.8.1 You can get a report about the app's storage status using the `storage:report` command: @@ -194,14 +198,17 @@ dokku docker-options:add node-js-app build "-v /tmp/python-test:/opt/test" You cannot use mounted volumes during the build phase of a Dockerfile deploy. This is because Docker does not support volumes when executing `docker build`. -> Warning: **This can cause data loss** if you bind a mount under `/app` in buildpack apps as herokuish will attempt to remove the original app path during the build phase. +> [!WARNING] +> **This can cause data loss** if you bind a mount under `/app` in buildpack apps as herokuish will attempt to remove the original app path during the build phase. ## App User and Persistent Storage file ownership (buildpack apps only) +> [!IMPORTANT] > New as of 0.7.1 By default, Dokku will execute your buildpack app processes as the `herokuishuser` user. You may override this by setting the `DOKKU_APP_USER` config variable. -> NOTE: this user must exist in your herokuish image. +> [!NOTE] +> this user must exist in your herokuish image. Additionally, the default `docker-local` scheduler that comes with Dokku will ensure your storage mounts are owned by either `herokuishuser` or the overridden value you have set in `DOKKU_APP_USER`. See the [docker-local scheduler documentation](/docs/deployment/schedulers/docker-local.md#disabling-chown-of-persistent-storage) docs for more information. diff --git a/docs/advanced-usage/plugin-management.md b/docs/advanced-usage/plugin-management.md index a3b861411..6caa10c7c 100644 --- a/docs/advanced-usage/plugin-management.md +++ b/docs/advanced-usage/plugin-management.md @@ -1,5 +1,6 @@ # Plugin Management +> [!IMPORTANT] > New as of 0.4.0 ``` @@ -66,7 +67,8 @@ plugn: dev trace 0.31.0 enabled dokku core trace plugin ``` -> Warning: All plugin commands other than `plugin:list` and `plugin:help` require sudo access and must be run directly from the Dokku server. +> [!WARNING] +> All plugin commands other than `plugin:list` and `plugin:help` require sudo access and must be run directly from the Dokku server. ### Checking if a plugin is installed @@ -78,7 +80,8 @@ dokku plugin:installed postgres ### Installing a plugin -> Note: Plugins installed in this method within a [docker-based installation](/docs/getting-started/install/docker.md) of Dokku do not persist across installs. Please see the [plugin installation section](/docs/getting-started/install/docker.md#plugin-installation) of the docker-based installation docs for further details. +> [!NOTE] +> Plugins installed in this method within a [docker-based installation](/docs/getting-started/install/docker.md) of Dokku do not persist across installs. Please see the [plugin installation section](/docs/getting-started/install/docker.md#plugin-installation) of the docker-based installation docs for further details. Installing a plugin is easy as well using the `plugin:install` command. This command will also trigger the `install` pluginhook on all existing plugins. diff --git a/docs/advanced-usage/registry-management.md b/docs/advanced-usage/registry-management.md index 4b956a586..9ffd07896 100644 --- a/docs/advanced-usage/registry-management.md +++ b/docs/advanced-usage/registry-management.md @@ -1,5 +1,6 @@ # Registry Management +> [!IMPORTANT] > New as of 0.25.0 ``` diff --git a/docs/advanced-usage/repository-management.md b/docs/advanced-usage/repository-management.md index e8235f863..5e1c67ccf 100644 --- a/docs/advanced-usage/repository-management.md +++ b/docs/advanced-usage/repository-management.md @@ -1,5 +1,6 @@ # Repository Management +> [!IMPORTANT] > New as of 0.6.0 ``` diff --git a/docs/advanced-usage/resource-management.md b/docs/advanced-usage/resource-management.md index bcbe07a91..e24b56b32 100644 --- a/docs/advanced-usage/resource-management.md +++ b/docs/advanced-usage/resource-management.md @@ -1,5 +1,6 @@ # Resource Management +> [!IMPORTANT] > New as of 0.15.0 ``` @@ -16,7 +17,8 @@ The resource plugin is meant to allow users to limit or reserve resources for a By default, Dokku allows unlimited resource access to apps deployed on a server. In some cases, it may be desirable to limit this on a per-app or per-process-type basis. The `resource` plugin allows management of both resource "limits" and resource "reservations", where each resource request type has specific meaning to the scheduler in use for a given app. -> Warning: The meaning of a values and it's units are specific to the scheduler in use for a given app. If a value is incorrect for a scheduler, this may result in containers failing to start correctly. If a scheduler does not support a given resource type combination, it will be ignored. All resource commands require an app rebuild or deploy in order to take effect. +> [!WARNING] +> The meaning of a values and it's units are specific to the scheduler in use for a given app. If a value is incorrect for a scheduler, this may result in containers failing to start correctly. If a scheduler does not support a given resource type combination, it will be ignored. All resource commands require an app rebuild or deploy in order to take effect. Valid resource options include: diff --git a/docs/community/plugins.md b/docs/community/plugins.md index da144aeab..a2344c929 100644 --- a/docs/community/plugins.md +++ b/docs/community/plugins.md @@ -46,7 +46,8 @@ The following plugins are available and provided by Dokku maintainers. Please f ## Community plugins -> Warning: The following plugins have been supplied by our community and may not have been tested by Dokku maintainers. +> [!WARNING] +> The following plugins have been supplied by our community and may not have been tested by Dokku maintainers. ### Datastores diff --git a/docs/configuration/domains.md b/docs/configuration/domains.md index 28057375a..ef815b620 100644 --- a/docs/configuration/domains.md +++ b/docs/configuration/domains.md @@ -1,5 +1,6 @@ # Domain Configuration +> [!IMPORTANT] > New as of 0.3.10 ``` @@ -65,6 +66,7 @@ dokku domains:set node-js-app dokku.me dokku.org ## Displaying domains reports for an app +> [!IMPORTANT] > New as of 0.8.1 You can get a report about the app's domains status using the `domains:report` command: diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md index cdcb804cd..508a649cf 100644 --- a/docs/configuration/environment-variables.md +++ b/docs/configuration/environment-variables.md @@ -21,7 +21,8 @@ Environment variables are available both at run time and during the application For buildpack deploys, Dokku will create a `/app/.env` file that can be used for legacy buildpacks. Note that this is _not_ updated when `config:set` or `config:unset` is called, and is only written during a `deploy` or `ps:rebuild`. Developers are encouraged to instead read from the application environment directly, as the proper values will be available then. -> Note: Global `ENV` files are sourced before app-specific `ENV` files. This means that app-specific variables will take precedence over global variables. Configuring your global `ENV` file is manual, and should be considered potentially dangerous as configuration applies to all applications. +> [!NOTE] +> Global `ENV` files are sourced before app-specific `ENV` files. This means that app-specific variables will take precedence over global variables. Configuring your global `ENV` file is manual, and should be considered potentially dangerous as configuration applies to all applications. You can set multiple environment variables at once: @@ -74,7 +75,8 @@ dokku config:export --format shell node-js-app The following config variables have special meanings and can be set in a variety of ways. Unless specified via global app config, the values may not be passed into applications. Usage of these values within applications should be considered unsafe, as they are an internal configuration values that may be moved to the internal properties system in the future. -> Warning: This list is not exhaustive, and may vary from version to version. +> [!WARNING] +> This list is not exhaustive, and may vary from version to version. | Name | Default | How to modify | Description | | ------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | diff --git a/docs/configuration/ssl.md b/docs/configuration/ssl.md index abb0f9f62..7581acea8 100644 --- a/docs/configuration/ssl.md +++ b/docs/configuration/ssl.md @@ -1,5 +1,6 @@ # SSL Configuration +> [!IMPORTANT] > New as of 0.4.0 Dokku supports SSL/TLS certificate inspection and CSR/Self-signed certificate generation via the `certs` plugin. Note that whenever SSL/TLS support is enabled SPDY is also enabled. @@ -33,7 +34,8 @@ tar cvf cert-key.tar server.crt server.key dokku certs:add node-js-app < cert-key.tar ``` -> Note: If your `.crt` file came alongside a `.ca-bundle`, you'll want to concatenate those into a single `.crt` file before adding it to the `.tar`. +> [!NOTE] +> If your `.crt` file came alongside a `.ca-bundle`, you'll want to concatenate those into a single `.crt` file before adding it to the `.tar`. ```shell cat yourdomain_com.crt yourdomain_com.ca-bundle > server.crt @@ -47,7 +49,8 @@ Note that with the default nginx template, requests will be redirected to the `h ### Certificate generation -> Note: Using this method will create a self-signed certificate, which is only recommended for development or staging use, not production environments. +> [!NOTE] +> Using this method will create a self-signed certificate, which is only recommended for development or staging use, not production environments. The `certs:generate` command will walk you through the correct `openssl` commands to create a key, csr and a self-signed cert for a given app/domain. We automatically put the self-signed cert in place as well as add the specified domain to the application configuration. @@ -69,6 +72,7 @@ dokku certs:show node-js-app key > server.key ### Displaying certificate reports for an app +> [!IMPORTANT] > New as of 0.8.1 You can get a report about the apps ssl status using the `certs:report` command: diff --git a/docs/deployment/application-deployment.md b/docs/deployment/application-deployment.md index 66522eb46..3c61a2c90 100644 --- a/docs/deployment/application-deployment.md +++ b/docs/deployment/application-deployment.md @@ -1,6 +1,7 @@ # Deploying an Application -> Note: This walkthrough uses the hostname `dokku.me` in commands. When deploying to your own server, you should substitute the domain `dokku.me` for the domain name or IP address associated with your server. Users of the Vagrant VM included with Dokku can use `dokku.me` which points to the IP of the VM. +> [!NOTE] +> This walkthrough uses the hostname `dokku.me` in commands. When deploying to your own server, you should substitute the domain `dokku.me` for the domain name or IP address associated with your server. Users of the Vagrant VM included with Dokku can use `dokku.me` which points to the IP of the VM. ## Deploy tutorial @@ -52,7 +53,8 @@ Dokku supports linking a single service to multiple applications as well as link ### Deploy the app -> Warning: Your app should respect the `PORT` environment variable, otherwise it may not respond to web requests. You can find more information in the [port management documentation](/docs/networking/port-management.md).** +> [!WARNING] +> Your app should respect the `PORT` environment variable, otherwise it may not respond to web requests. You can find more information in the [port management documentation](/docs/networking/port-management.md).** Now you can deploy the `ruby-getting-started` app to your Dokku server. All you have to do is add a remote to name the app. Applications are created on-the-fly on the Dokku server. @@ -64,11 +66,13 @@ git remote add dokku dokku@dokku.me:ruby-getting-started git push dokku main ``` -> Note: Some tools may not support the short-upstream syntax referenced above, and you may need to prefix +> [!NOTE] +> Some tools may not support the short-upstream syntax referenced above, and you may need to prefix > the upstream with the scheme `ssh://` like so: `ssh://dokku@dokku.me:ruby-getting-started` > Please see the [Git](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) documentation for more details. -> Note: Your private key should be registered with `ssh-agent` in your local development environment. If you get a `permission denied` error when pushing, you can register your private key as follows: `ssh-add -k ~/`. +> [!NOTE] +> Your private key should be registered with `ssh-agent` in your local development environment. If you get a `permission denied` error when pushing, you can register your private key as follows: `ssh-add -k ~/`. After running `git push dokku main`, you should have output similar to this in your terminal: @@ -168,7 +172,8 @@ ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts ssh -T git@github.com ``` -> Warning: if the buildpack or Dockerfile build process require SSH key access for other reasons, the above may not always apply. +> [!WARNING] +> if the buildpack or Dockerfile build process require SSH key access for other reasons, the above may not always apply. ## Deploying to subdomains diff --git a/docs/deployment/application-management.md b/docs/deployment/application-management.md index 7f22cb761..ca5743e58 100644 --- a/docs/deployment/application-management.md +++ b/docs/deployment/application-management.md @@ -1,5 +1,6 @@ # Application Management +> [!IMPORTANT] > New as of 0.3.1 ``` @@ -19,6 +20,7 @@ apps:unlock # Unlocks an app for deployment ### Listing applications +> [!IMPORTANT] > New as of 0.8.1. Use the `apps` command for older versions. You can easily list all available applications using the `apps:list` command: @@ -117,6 +119,7 @@ Destroying an application will unlink all linked services and destroy any config ### Renaming a deployed app +> [!IMPORTANT] > New as of 0.4.7 You can rename a deployed app using the `apps:rename` command. Note that the application *must* have been deployed at least once, or the rename will not complete successfully: @@ -158,6 +161,7 @@ git remote set-url dokku dokku@dokku.me:io-js-app ### Cloning an existing app +> [!IMPORTANT] > New as of 0.11.5 You can clone an existing app using the `apps:clone` command. Note that the application *must* have been deployed at least once, or cloning will not complete successfully: @@ -177,7 +181,8 @@ This will copy all of your app's contents into a new app directory with the name - SSL certificates will not be copied to the new app. - Port mappings with the scheme `https` and host-port `443` will be skipped. -> Warning: If you have exposed specific ports via `docker-options` plugin, or performed anything that cannot be done against multiple applications, `apps:clone` may result in errors. +> [!WARNING] +> If you have exposed specific ports via `docker-options` plugin, or performed anything that cannot be done against multiple applications, `apps:clone` may result in errors. By default, Dokku will deploy this new app, though you can skip the deploy by using the `--skip-deploy` flag: @@ -193,6 +198,7 @@ dokku apps:clone --ignore-existing node-js-app io-js-app ### Locking app deploys +> [!IMPORTANT] > New as of 0.11.6 If you wish to disable deploying for a period of time, this can be done via deploy locks. Normally, deploy locks exist only for the duration of a deploy so as to avoid deploys from colliding, but a deploy lock can be created by running the `apps:lock` command. @@ -207,11 +213,13 @@ dokku apps:lock node-js-app ### Unlocking app deploys +> [!IMPORTANT] > New as of 0.11.6 In some cases, it may be necessary to remove an existing deploy lock. This can be performed via the `apps:unlock` command. -> Warning: Removing the deploy lock *will not* stop in progress deploys. At this time, in progress deploys will need to be manually terminated by someone with server access. +> [!WARNING] +> Removing the deploy lock *will not* stop in progress deploys. At this time, in progress deploys will need to be manually terminated by someone with server access. ```shell dokku apps:unlock node-js-app @@ -225,6 +233,7 @@ dokku apps:unlock node-js-app ### Checking lock status +> [!IMPORTANT] > New as of 0.13.0 In some cases, you may wish to inspect the state of an app lock. To do so, you can issue an `apps:lock` command. This will exit non-zero if there is no app lock in place. @@ -239,6 +248,7 @@ Deploy lock does not exist ### Displaying reports for an app +> [!IMPORTANT] > New as of 0.8.1 You can get a report about the deployed apps using the `apps:report` command: diff --git a/docs/deployment/builders/builder-management.md b/docs/deployment/builders/builder-management.md index d05df624d..fc334ed8a 100644 --- a/docs/deployment/builders/builder-management.md +++ b/docs/deployment/builders/builder-management.md @@ -1,5 +1,6 @@ # Builder Management +> [!IMPORTANT] > New as of 0.24.0 ``` @@ -51,7 +52,8 @@ dokku builder:set --global selected #### Changing the build directory -> Warning: Please keep in mind that setting a custom build directory will result in loss of any changes to the top-level directory, such as the `git.keep-git-dir` property. +> [!WARNING] +> Please keep in mind that setting a custom build directory will result in loss of any changes to the top-level directory, such as the `git.keep-git-dir` property. When deploying a monorepo, it may be desirable to specify the specific build directory to use for a given app. This can be done via the `builder:set` command. If a value is specified and that directory does not exist within the repository, the build will fail. diff --git a/docs/deployment/builders/cloud-native-buildpacks.md b/docs/deployment/builders/cloud-native-buildpacks.md index 718909a58..1a30cf704 100644 --- a/docs/deployment/builders/cloud-native-buildpacks.md +++ b/docs/deployment/builders/cloud-native-buildpacks.md @@ -1,5 +1,6 @@ # Cloud Native Buildpacks +> [!IMPORTANT] > New as of 0.22.0 ``` @@ -13,7 +14,8 @@ buildpacks:set-property [--global|] # Set or clear a buildpa Cloud Native Buildpacks are an evolution over the Buildpacks technology provided by the Herokuish builder. See the [herokuish buildpacks documentation](/docs/deployment/builders/herokuish-buildpacks.md) for more information on how to clear buildpack build cache for an application. -> Warning: This functionality uses the `pack` cli from the [Cloud Native Buildpacks](https://buildpacks.io) project to build apps. As the integration is experimental in Dokku, it is likely to change over time. +> [!WARNING] +> This functionality uses the `pack` cli from the [Cloud Native Buildpacks](https://buildpacks.io) project to build apps. As the integration is experimental in Dokku, it is likely to change over time. ## Usage @@ -88,6 +90,7 @@ dokku builder-pack:set --global projecttoml-path ### Displaying builder-pack reports for an app +> [!IMPORTANT] > New as of 0.25.0 You can get a report about the app's storage status using the `builder-pack:report` command: @@ -136,6 +139,7 @@ project2.toml ### Customizing the Buildpack stack builder +> [!IMPORTANT] > New as of 0.23.0 The default stack builder in use by CNB buildpacks in Dokku is based on `heroku/builder:22`. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the `buildpacks:set-property` command. diff --git a/docs/deployment/builders/dockerfiles.md b/docs/deployment/builders/dockerfiles.md index 62a1cc590..8b6702c8f 100644 --- a/docs/deployment/builders/dockerfiles.md +++ b/docs/deployment/builders/dockerfiles.md @@ -1,5 +1,6 @@ # Dockerfile Deployment +> [!IMPORTANT] > New as of 0.3.15 ``` @@ -64,6 +65,7 @@ dokku builder-dockerfile:set --global dockerfile-path ### Displaying builder-dockerfile reports for an app +> [!IMPORTANT] > New as of 0.25.0 You can get a report about the app's storage status using the `builder-dockerfile:report` command: @@ -196,6 +198,7 @@ Setting `$DOKKU_DOCKERFILE_CACHE_BUILD` to `true` or `false` will enable or disa ### Procfiles and multiple processes +> [!IMPORTANT] > New as of 0.5.0 See the [Procfile documentation](/docs/processes/process-management.md#procfile) for more information on how to specify different processes for your app. diff --git a/docs/deployment/builders/herokuish-buildpacks.md b/docs/deployment/builders/herokuish-buildpacks.md index b9f07beb6..29974f2f6 100644 --- a/docs/deployment/builders/herokuish-buildpacks.md +++ b/docs/deployment/builders/herokuish-buildpacks.md @@ -1,5 +1,6 @@ # Herokuish Buildpacks +> [!IMPORTANT] > Subcommands new as of 0.15.0 ``` @@ -17,7 +18,8 @@ builder-herokuish:report [] [] # Displays a builder-herokuish repor builder-herokuish:set () # Set or clear a builder-herokuish property for an app ``` -> Warning: If using the `buildpacks` plugin, be sure to unset any `BUILDPACK_URL` and remove any such entries from a committed `.env` file. A specified `BUILDPACK_URL` will always override a `.buildpacks` file or the buildpacks plugin. +> [!WARNING] +> If using the `buildpacks` plugin, be sure to unset any `BUILDPACK_URL` and remove any such entries from a committed `.env` file. A specified `BUILDPACK_URL` will always override a `.buildpacks` file or the buildpacks plugin. Dokku normally defaults to using [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, though this may be overridden by committing a valid `Dockerfile` to the root of your repository and pushing the repository to your Dokku installation. To avoid this automatic `Dockerfile` deployment detection, you may do one of the following: @@ -147,6 +149,7 @@ dokku buildpacks:clear node-js-app ### Customizing the Buildpack stack builder +> [!IMPORTANT] > New as of 0.23.0 The default stack builder in use by Herokuish buildpacks in Dokku is based on `gliderlabs/herokuish:latest`. Typically, this is installed via an OS package which pulls the requisite Docker image. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the `buildpacks:set-property` command. @@ -175,6 +178,7 @@ dokku buildpacks:set-property --global stack ### Allowing herokuish for non-amd64 platforms +> [!IMPORTANT] > New as of 0.29.0 By default, the builder-herokuish plugin is not enabled for non-amd64 platforms, and attempting to use it is blocked. This is because the majority of buildpacks are not cross-platform compatible, and thus building apps will either be considerably slower - due to emulating the amd64 platform - or won't work - due to building amd64 packages on arm/arm64 platforms. @@ -248,6 +252,7 @@ dokku buildpacks:report node-js-app --buildpacks-list ### Displaying builder-herokuish reports for an app +> [!IMPORTANT] > New as of 0.29.0 You can get a report about the app's storage status using the `builder-herokuish:report` command: diff --git a/docs/deployment/builders/lambda.md b/docs/deployment/builders/lambda.md index 692268c07..9df4501c6 100644 --- a/docs/deployment/builders/lambda.md +++ b/docs/deployment/builders/lambda.md @@ -1,5 +1,6 @@ # Lambda Builder +> [!IMPORTANT] > New as of 0.28.0 ``` diff --git a/docs/deployment/builders/null.md b/docs/deployment/builders/null.md index 88a1b2f2d..095f75cdf 100644 --- a/docs/deployment/builders/null.md +++ b/docs/deployment/builders/null.md @@ -1,5 +1,6 @@ # Null Builder +> [!IMPORTANT] > New as of 0.25.0 The `null` builder does nothing, and is useful for routing to services not managed by Dokku. It should not be used in normal operation. Please see the [network documentation](/docs/networking/network.md#routing-an-app-to-a-known-ip:port-combination) for more information on the aforementioned use case. diff --git a/docs/deployment/logs.md b/docs/deployment/logs.md index 8c9531893..178f0131a 100644 --- a/docs/deployment/logs.md +++ b/docs/deployment/logs.md @@ -43,7 +43,8 @@ The above command will show logs continually from the web process. ### Failed deploy logs -> Warning: The default [docker-local scheduler](/docs/deployment/schedulers/docker-local.md) will "store" these until the next deploy or until the old containers are garbage collected - whichever runs first. If you require the logs beyond this point in time, please ship the logs to a centralized log server. +> [!WARNING] +> The default [docker-local scheduler](/docs/deployment/schedulers/docker-local.md) will "store" these until the next deploy or until the old containers are garbage collected - whichever runs first. If you require the logs beyond this point in time, please ship the logs to a centralized log server. In some cases, it may be useful to retrieve the logs from a previously failed deploy. @@ -89,13 +90,15 @@ dokku logs:set --global max-size ### Vector Logging Shipping +> [!IMPORTANT] > New as of 0.22.6 Vector is an open-source, lightweight and ultra-fast tool for building observability pipelines. Dokku integrates with it for shipping container logs for the `docker-local` scheduler. Users may configure log-shipping on a per-app or global basis, neither of which interfere with the `dokku logs` commands. #### Starting the Vector container -> Warning: While the default vector image may be updated over time, this will not impact running vector containers. Users are encouraged to view any Dokku and Vector changelogs to ensure their system will continue running as expected. +> [!WARNING] +> While the default vector image may be updated over time, this will not impact running vector containers. Users are encouraged to view any Dokku and Vector changelogs to ensure their system will continue running as expected. Vector may be started via the `logs:vector-start` command. diff --git a/docs/deployment/methods/git.md b/docs/deployment/methods/git.md index 3088294f1..3d7d79075 100644 --- a/docs/deployment/methods/git.md +++ b/docs/deployment/methods/git.md @@ -1,5 +1,6 @@ # Git Deployment +> [!IMPORTANT] > Subcommands new as of 0.12.0 ``` @@ -25,7 +26,8 @@ Git-based deployment has been the traditional method of deploying applications i ## Usage -> Warning: Pushing from a shallow clone is not currently supported and may have undefined behavior. Please unshallow your local repository before pushing to a Dokku app to avoid potential errors in the deployment process. +> [!WARNING] +> Pushing from a shallow clone is not currently supported and may have undefined behavior. Please unshallow your local repository before pushing to a Dokku app to avoid potential errors in the deployment process. ### Initializing an application @@ -40,7 +42,8 @@ dokku git:initialize node-js-app In order for the above command to succeed, the application _must_ already exist. -> Warning: If the `pre-receive` hook was customized in any way, this will overwrite that hook with the current defaults for Dokku. +> [!WARNING] +> If the `pre-receive` hook was customized in any way, this will overwrite that hook with the current defaults for Dokku. ### Changing the deploy branch @@ -72,6 +75,7 @@ Pushing multiple branches can also be supported by creating a [receive-branch](/ ### Configuring the `GIT_REV` environment variable +> [!IMPORTANT] > New as of 0.12.0 Application deployments will include a special `GIT_REV` environment variable containing the current deployment sha being deployed. For rebuilds, this SHA will remain the same. @@ -123,6 +127,7 @@ Please keep in mind that setting `keep-git-dir` to `true` may result in unstaged ### Initializing an app repository from a docker image +> [!IMPORTANT] > New as of 0.24.0 A Dokku app repository can be initialized or updated from a Docker image via the `git:from-image` command. This command will either initialize the app repository or update it to include the specified Docker image via a `FROM` stanza. This is an excellent way of tracking changes when deploying only a given docker image, especially if deploying an image from a remote CI/CD pipeline. @@ -170,6 +175,7 @@ See the [dockerfile documentation](/docs/deployment/builders/dockerfiles.md) to ### Initializing an app repository from an archive file +> [!IMPORTANT] > New as of 0.24.0 A Dokku app repository can be initialized or updated from the contents of an archive file via the `git:from-archive` command. This is an excellent way of tracking changes when deploying pre-built binary archives, such as java jars or go binaries. This can also be useful when deploying directly from a GitHub repository at a specific commit. @@ -202,6 +208,7 @@ curl -sSL https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke- ### Initializing an app repository from a remote image without a registry +> [!IMPORTANT] > New as of 0.30.0 A Dokku app repository can be initialized or updated from the contents of an image archive tar file via the `git:load-image` command. This method can be used when a Docker Registry is unavailable to act as an intermediary for storing an image, such as when building an image in CI and deploying directly from that image. @@ -245,6 +252,7 @@ See the [dockerfile documentation](/docs/deployment/builders/dockerfiles.md) to ### Initializing an app repository from a remote repository +> [!IMPORTANT] > New as of 0.23.0 A Dokku app repository can be initialized or updated from a remote git repository via the `git:sync` command. This command will either clone or fetch updates from a remote repository and has undefined behavior if the history cannot be fast-fowarded to the referenced repository reference. Any repository that can be cloned by the `dokku` user can be specified. @@ -276,6 +284,7 @@ dokku git:sync --build node-js-app https://github.com/heroku/node-js-getting-sta ### Initializing from private repositories +> [!IMPORTANT] > New as of 0.24.0 Initializing from a private repository requires one of the following: diff --git a/docs/deployment/schedulers/docker-local.md b/docs/deployment/schedulers/docker-local.md index 5da54e1c5..3cec7cd75 100644 --- a/docs/deployment/schedulers/docker-local.md +++ b/docs/deployment/schedulers/docker-local.md @@ -1,5 +1,6 @@ # Docker Local Scheduler +> [!IMPORTANT] > Subcommands new as of 0.12.12 ``` @@ -7,6 +8,7 @@ scheduler-docker-local:report [] [] # Displays a schedul scheduler-docker-local:set () # Set or clear a scheduler-docker-local property for an app ``` +> [!IMPORTANT] > New as of 0.12.0 Dokku natively includes functionality to manage application lifecycles for a single server using the `scheduler-docker-local` plugin. It is the default scheduler, but as with all schedulers, it is set on a per-application basis. The scheduler can currently be overridden by running the following command: @@ -55,6 +57,7 @@ All image containers with the label `org.opencontainers.image.vendor=linuxserver ### Deploying Process Types in Parallel +> [!IMPORTANT] > New as of 0.25.5 By default, Dokku deploys an app's processes one-by-one in order, with the `web` process being deployed first. Deployment parallelism may be achieved by setting the `parallel-schedule-count` property, which defaults to `1`. Increasing this number increases the number of process types that may be deployed in parallel (with the web process being the exception). @@ -78,6 +81,7 @@ Note that increasing the value of `parallel-schedule-count` may significantly im #### Increasing parallelism within a process deploy +> [!IMPORTANT] > New as of 0.26.0 By default, Dokku will deploy one instance of a given process type at a time. This can be increased by customizing the `app.json` `formation` key to include a `max_parallel` key for the given process type. diff --git a/docs/deployment/schedulers/kubernetes.md b/docs/deployment/schedulers/kubernetes.md index 441ebe99e..dcc253f43 100644 --- a/docs/deployment/schedulers/kubernetes.md +++ b/docs/deployment/schedulers/kubernetes.md @@ -1,6 +1,7 @@ # Kubernetes Scheduler -> Warning: This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes. +> [!WARNING] +> This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes. The [Kubernetes Scheduler Plugin](https://github.com/dokku/dokku-scheduler-kubernetes) is available free as an external plugin. Please see the plugin's [issue tracker](https://github.com/dokku/dokku-scheduler-kubernetes/issues) for more information on the status of the plugin. diff --git a/docs/deployment/schedulers/nomad.md b/docs/deployment/schedulers/nomad.md index 287185dd3..95de76e9c 100644 --- a/docs/deployment/schedulers/nomad.md +++ b/docs/deployment/schedulers/nomad.md @@ -1,6 +1,7 @@ # Nomad Scheduler -> Warning: This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes. +> [!WARNING] +> This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes. The [Nomad Scheduler Plugin](https://github.com/dokku/dokku-scheduler-nomad) is available free as an external plugin. Please see the plugin's [issue tracker](https://github.com/dokku/dokku-scheduler-nomad/issues) for more information on the status of the plugin. @@ -20,4 +21,5 @@ This plugin implements various functionality through `plugn` triggers to integra ### Logging support -> Warning: Fetching app logs for the `logs` command is currently not implemented. Please consider using [Vector](https://vector.dev/docs/setup/installation/platforms/kubernetes/) or a similar tool to ship logs to another service or a third-party platform. +> [!WARNING] +> Fetching app logs for the `logs` command is currently not implemented. Please consider using [Vector](https://vector.dev/docs/setup/installation/platforms/kubernetes/) or a similar tool to ship logs to another service or a third-party platform. diff --git a/docs/deployment/schedulers/null.md b/docs/deployment/schedulers/null.md index b17ba5c91..eeb9bb6ab 100644 --- a/docs/deployment/schedulers/null.md +++ b/docs/deployment/schedulers/null.md @@ -1,5 +1,6 @@ # Null Scheduler +> [!IMPORTANT] > New as of 0.25.0 The `null` scheduler does nothing, and is useful for routing to services not managed by Dokku. It should not be used in normal operation. Please see the [network documentation](/docs/networking/network.md#routing-an-app-to-a-known-ip:port-combination) for more information on the aforementioned use case. diff --git a/docs/deployment/schedulers/scheduler-management.md b/docs/deployment/schedulers/scheduler-management.md index 04da2bc81..3b93e614c 100644 --- a/docs/deployment/schedulers/scheduler-management.md +++ b/docs/deployment/schedulers/scheduler-management.md @@ -1,5 +1,6 @@ # Scheduler Management +> [!IMPORTANT] > New as of 0.26.0 ``` diff --git a/docs/deployment/user-management.md b/docs/deployment/user-management.md index 8685bf56c..27922f67c 100644 --- a/docs/deployment/user-management.md +++ b/docs/deployment/user-management.md @@ -1,5 +1,6 @@ # User Management +> [!IMPORTANT] > New as of 0.7.0 ``` @@ -34,6 +35,7 @@ The output contains the following information: - The `KEY_NAME`. - A comma separated list of SSH options under the `SSHCOMMAND_ALLOWED_KEYS` name. +> [!IMPORTANT] > New as of 0.20.2 The keys for a specific user may be listed by specifying a second argument to the `ssh-keys:list` command: @@ -42,6 +44,7 @@ The keys for a specific user may be listed by specifying a second argument to th dokku ssh-keys:list admin ``` +> [!IMPORTANT] > New as of 0.22.3 The output format may be specified via the `--format` flag. Supported values include `json` and `text`. diff --git a/docs/deployment/zero-downtime-deploys.md b/docs/deployment/zero-downtime-deploys.md index 53ca0e444..d37118f03 100644 --- a/docs/deployment/zero-downtime-deploys.md +++ b/docs/deployment/zero-downtime-deploys.md @@ -1,5 +1,6 @@ # Zero Downtime Deploy Checks +> [!IMPORTANT] > New as of 0.5.0 ``` @@ -83,6 +84,7 @@ dokku checks:disable node-js-app worker ### Displaying checks reports for an app +> [!IMPORTANT] > New as of 0.8.1 You can get a report about the app's checks status using the `checks:report` command: @@ -135,6 +137,7 @@ dokku checks:report node-js-app --checks-disabled-list ## Customizing checks +> [!IMPORTANT] > New as of 0.31.0 If your application needs a longer period to boot up - perhaps to load data into memory, or because of slow boot time - you may also use Dokku's `checks` functionality to more precisely check whether an application can serve traffic or not. @@ -171,7 +174,8 @@ A healthcheck entry takes the following properties: - `uptime`: (default: `""` - none): Amount of time the container must be alive before the container is considered healthy. Any restarts will cause this to check to fail, and this check does not respect retries. - `wait`: (default: `5` seconds): Number of seconds to wait between healthcheck attempts. -> Warning: Healthchecks are implemented by specific scheduler plugins, and not all plugins support all options. Please consult the scheduler documentation for further details on what is supported. +> [!WARNING] +> Healthchecks are implemented by specific scheduler plugins, and not all plugins support all options. Please consult the scheduler documentation for further details on what is supported. See the [docker-container-healthchecker](https://github.com/dokku/docker-container-healthchecker) documentation for more details on how healthchecks are interpreted. diff --git a/docs/development/plugin-creation.md b/docs/development/plugin-creation.md index edebfc649..5370b973d 100644 --- a/docs/development/plugin-creation.md +++ b/docs/development/plugin-creation.md @@ -145,6 +145,7 @@ Any functions that must be kept private should reside in the plugin's `trigger/` ### Use helper functions to fetch app images +> [!IMPORTANT] > New as of 0.4.0 Dokku allows image tagging and deployment of tagged images. This means hard-coding the `$IMAGE` as `dokku/$APP` is no longer sufficient. @@ -155,6 +156,7 @@ Plugins should use `get_running_image_tag()` and `get_app_image_name()` as sourc ### Use `$DOCKER_BIN` instead of `docker` directly +> [!IMPORTANT] > New as of 0.17.5 Certain systems may require a wrapper function around the `docker` binary for proper execution. Utilizing the `$DOCKER_BIN` environment variable when calling docker for those functions is preferred. @@ -169,6 +171,7 @@ docker run -d $IMAGE /bin/bash -e -c "$COMMAND" ### Include labels for all temporary containers and images +> [!IMPORTANT] > New as of 0.5.0 As of 0.5.0, labels are used to help cleanup intermediate containers with `dokku cleanup`. Plugins that create containers and images should add the correct labels to the `build`, `commit`, and `run` docker commands. @@ -208,6 +211,7 @@ Files are copied from the `/app` directory - for images built via buildpacks - o ### Avoid calling the `dokku` binary directly +> [!IMPORTANT] > New as of 0.6.0 Plugins should **not** call the `dokku` binary directly from within plugins because clients using the `--app` argument are potentially broken when doing so. diff --git a/docs/development/plugin-triggers.md b/docs/development/plugin-triggers.md index 92e882b35..75a796aef 100644 --- a/docs/development/plugin-triggers.md +++ b/docs/development/plugin-triggers.md @@ -646,7 +646,8 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x ### `docker-args-build` -> Warning: Deprecated, please use `docker-args-process-build` instead +> [!WARNING] +> Deprecated, please use `docker-args-process-build` instead - Description: - Invoked by: `internal function dokku_build() (build phase)` @@ -671,7 +672,8 @@ echo -n "$STDIN$output" ### `docker-args-deploy` -> Warning: Deprecated, please use `docker-args-process-deploy` instead +> [!WARNING] +> Deprecated, please use `docker-args-process-deploy` instead - Description: - Invoked by: `dokku deploy` @@ -742,7 +744,8 @@ APP="$1"; IMAGE_SOURCE_TYPE="$3"; IMAGE_TAG="$2"; IMAGE=$(get_app_image_name $AP ### `docker-args-run` -> Warning: Deprecated, please use `docker-args-process-run` instead +> [!WARNING] +> Deprecated, please use `docker-args-process-run` instead - Description: - Invoked by: `dokku run` @@ -969,7 +972,8 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x # TODO ``` -> Warning: The `git-pre-pull` trigger should _not_ be used for authentication since it does not get called for commands that use `git-upload-archive` such as `git archive`. Instead, use the [`user-auth`](#user-auth) trigger. +> [!WARNING] +> The `git-pre-pull` trigger should _not_ be used for authentication since it does not get called for commands that use `git-upload-archive` such as `git archive`. Instead, use the [`user-auth`](#user-auth) trigger. ### `git-revision` @@ -1224,7 +1228,8 @@ echo "$NEW_SUBDOMAIN.$VHOST" ### `nginx-pre-reload` -> Warning: The arguments INTERNAL_PORT and INTERNAL_IP_ADDRESS are no longer sufficient to retrieve all app listeners. Please run `plugn trigger network-get-listeners APP` within any implementation of `nginx-pre-reload` in order to retrieve all application listeners. +> [!WARNING] +> The arguments INTERNAL_PORT and INTERNAL_IP_ADDRESS are no longer sufficient to retrieve all app listeners. Please run `plugn trigger network-get-listeners APP` within any implementation of `nginx-pre-reload` in order to retrieve all application listeners. - Description: Run before nginx reloads hosts - Invoked by: `dokku proxy:build-config` @@ -1410,7 +1415,8 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x ### `post-build-pack` -> Warning: The pack plugin trigger apis are under development and may change +> [!WARNING] +> The pack plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run commands after the build image is create for a given app. Only applies to apps using pack. @@ -1624,7 +1630,8 @@ haproxy-build-config "$APP" ### `post-release-builder` -> Warning: Image mutation in this trigger may result in an invalid run state, and is heavily discouraged. +> [!WARNING] +> Image mutation in this trigger may result in an invalid run state, and is heavily discouraged. - Description: Invokes a command after the build process is complete. - Invoked by: builder plugins @@ -1676,7 +1683,8 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x ### `pre-build-pack` -> Warning: The pack plugin trigger apis are under development and may change +> [!WARNING] +> The pack plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to apps using pack. @@ -1832,7 +1840,8 @@ docker commit "${DOCKER_COMMIT_LABEL_ARGS[@]}" $CID $IMAGE >/dev/null ### `pre-release-pack` -> Warning: The pack plugin trigger apis are under development and may change +> [!WARNING] +> The pack plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using pack. @@ -1963,7 +1972,8 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x ### `proxy-configure-ports` -> Warning: Deprecated, please use `ports-configure` instead +> [!WARNING] +> Deprecated, please use `ports-configure` instead - Description: Configures the port mapping - Invoked by: `internally triggered by proxy plugins` @@ -2192,7 +2202,8 @@ mail -s "$APP containers on $HOSTNAME failed to retire" ops@dokku.me ### `scheduler-app-status` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Fetch the status of an app @@ -2211,7 +2222,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ### `scheduler-deploy` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when an app is deployed @@ -2230,7 +2242,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; IMAGE_TAG="$3"; ### `scheduler-detect` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to check which scheduler is in use for an app @@ -2249,7 +2262,8 @@ APP="$1" ### `scheduler-enter` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to enter a running container for a given app @@ -2268,7 +2282,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ARGS="$@" ### `scheduler-inspect` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run inspect commands for all containers for a given app @@ -2287,7 +2302,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ### `scheduler-logs` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when retrieving container logs @@ -2306,7 +2322,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; PROCESS_TYPE="$3"; TAIL="$4"; PRETTY_PRINT="$5"; ### `scheduler-logs-failed` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when retrieving failed container logs @@ -2325,7 +2342,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ### `scheduler-pre-restore` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run commands before an app is restored @@ -2344,7 +2362,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ### `scheduler-post-delete` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when an app is deleted @@ -2363,7 +2382,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; IMAGE_TAG="$3"; ### `scheduler-post-run` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands after a `dokku run` invocation is called @@ -2382,7 +2402,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; CONTAINER_ID="$3"; ### `scheduler-register-retired` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows scheduling retiring a local container and any related images @@ -2402,7 +2423,8 @@ CONTAINER_ID="$2"; ### `scheduler-retire` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when containers should be force retired from the system @@ -2421,7 +2443,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ### `scheduler-run` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when a command is executed for your app @@ -2440,7 +2463,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ARGS="${@:3}"; ### `scheduler-run-list` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Lists all run containers for a given app @@ -2459,7 +2483,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; FORMAT="$3"; ### `scheduler-run-logs` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when retrieving one-off container logs @@ -2478,7 +2503,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; CONTAINER="$3"; TAIL="$4"; PRETTY_PRINT="$5"; NU ### `scheduler-stop` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when a tag is destroyed diff --git a/docs/getting-started/troubleshooting.md b/docs/getting-started/troubleshooting.md index bd3f7f8ab..0645869dd 100644 --- a/docs/getting-started/troubleshooting.md +++ b/docs/getting-started/troubleshooting.md @@ -1,5 +1,6 @@ # Troubleshooting +> [!IMPORTANT] > New as of 0.17.0 ``` diff --git a/docs/networking/dns.md b/docs/networking/dns.md index 80c5975b2..d3977018a 100644 --- a/docs/networking/dns.md +++ b/docs/networking/dns.md @@ -1,6 +1,7 @@ # DNS Configuration -> Note: This is a work in progress. +> [!NOTE] +> This is a work in progress. ## DNS Versions diff --git a/docs/networking/network.md b/docs/networking/network.md index 30f898de4..abf3d1989 100644 --- a/docs/networking/network.md +++ b/docs/networking/network.md @@ -1,5 +1,6 @@ # Network Management +> [!IMPORTANT] > New as of 0.11.0, Enhanced in 0.20.0 ``` @@ -20,6 +21,7 @@ The Network plugin allows developers to abstract the concept of container networ ### Listing networks +> [!IMPORTANT] > New as of 0.20.0, Requires Docker 1.21+ You can easily list all available networks using the `network:list` command: @@ -51,6 +53,7 @@ test-network ### Creating a network +> [!IMPORTANT] > New as of 0.20.0, Requires Docker 1.21+ Docker networks can be created via the `network:create` command. Executing this command will create an attachable `bridge` network. This can be used to route requests between containers without going through any public network. @@ -67,6 +70,7 @@ Specifying other additional flags or other types of networks can be created dire ### Destroying a network +> [!IMPORTANT] > New as of 0.20.0, Requires Docker 1.21+ A Docker network without any associated containers may be destroyed via the `network:destroy` command. Docker will refuse to destroy networks that have containers attached. @@ -95,6 +99,7 @@ dokku --force network:destroy test-network ### Checking if a network exists +> [!IMPORTANT] > New as of 0.20.0, Requires Docker 1.21+ For CI/CD pipelines, it may be useful to see if an network exists before creating a new network. You can do so via the `network:exists` command: @@ -111,6 +116,7 @@ The `network:exists` command will return non-zero if the network does not exist, ### Checking network info +> [!IMPORTANT] > New as of 0.20.0, Requires Docker 1.21+ Network information can be retrieved via the `network:info` command. This is a slightly different version of the `docker network` command. @@ -155,6 +161,7 @@ Only a single `$IP:$PORT` combination can be routed to for a given app, and that ### Attaching an app to a network +> [!IMPORTANT] > New as of 0.20.0, Requires Docker 1.21+ Apps will default to being associated with the default `bridge` network or a network specified by the `initial-network` network property. Additionally, an app can be attached to `attachable` networks by changing the `attach-post-create` or `attach-post-deploy` network properties when using the [docker-local scheduler](/docs/deployment/schedulers/docker-local.md). A change in these values will require an app deploy or rebuild. @@ -206,7 +213,8 @@ dokku network:set --global initial-network #### Network Aliases -> Note: This feature is only available when an app has been attached to a network other than the default `bridge` network. +> [!NOTE] +> This feature is only available when an app has been attached to a network other than the default `bridge` network. When a container created for a deployment is being attached to a network - regardless of which network property was used - a network alias of the pattern `APP.PROC_TYPE` will be added to all containers. This can be used to load-balance requests between containers. For an application named `node-js-app` with a process type of web, the network alias - or resolvable DNS record within the network - will be: @@ -292,7 +300,8 @@ Whatever the reason, the semantics of the two network hooks are important and ar - Use case: When another container on the network is already running and needed by this container. - Example: A key-value store exposing itself to all your apps may be on the `initial-network`. -> Warning: If the attachment fails during the `running` container state, this may result in your application failing to respond to proxied requests once older containers are removed. +> [!WARNING] +> If the attachment fails during the `running` container state, this may result in your application failing to respond to proxied requests once older containers are removed. ### Rebuilding network settings diff --git a/docs/networking/port-management.md b/docs/networking/port-management.md index 927f97f8a..5368889a9 100644 --- a/docs/networking/port-management.md +++ b/docs/networking/port-management.md @@ -1,5 +1,6 @@ # Port Management +> [!IMPORTANT] > New as of 0.31.0, replaces the previous `proxy:ports*` commands ``` @@ -12,7 +13,8 @@ ports:set :: [:: Warning: Mapping alternative ports may conflict with the active firewall installed on your server or hosting provider. Such software includes - but is not limited to - AWS Security Groups, iptables, and UFW. Please consult the documentation for those softwares as applicable. +> [!WARNING] +> Mapping alternative ports may conflict with the active firewall installed on your server or hosting provider. Such software includes - but is not limited to - AWS Security Groups, iptables, and UFW. Please consult the documentation for those softwares as applicable. > > Users should also avoid setting the `PORT` environment variable. Dokku will use port mappings to set this value. Overriding this manually may cause issues in application routing. @@ -20,7 +22,8 @@ You can now configure `host -> container` port mappings with the `ports:*` comma By default, buildpack apps and dockerfile apps **without** explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on port `80` (and additionally a listener on 443 if ssl is enabled) that will proxy to the application container on port `5000`. Dockerfile apps **with** explicitly exposed ports will be configured with a listener on each exposed port and will proxy to that same port of the deployed application container. -> Note: This default behavior **will not** be automatically changed on subsequent pushes and must be manipulated with the `ports:*` commands detailed below. +> [!NOTE] +> This default behavior **will not** be automatically changed on subsequent pushes and must be manipulated with the `ports:*` commands detailed below. ### Port Scheme @@ -138,7 +141,8 @@ dokku ports:remove node-js-app http:80 ## Port management by Deployment Method -> Warning: If you set a port map but _do not have a global domain set_, Dokku will reset that map upon first deployment. +> [!WARNING] +> If you set a port map but _do not have a global domain set_, Dokku will reset that map upon first deployment. ### Buildpacks diff --git a/docs/networking/proxies/caddy.md b/docs/networking/proxies/caddy.md index fa1e70112..fe2f6b9c7 100644 --- a/docs/networking/proxies/caddy.md +++ b/docs/networking/proxies/caddy.md @@ -1,5 +1,6 @@ # Caddy Proxy +> [!IMPORTANT] > New as of 0.28.0 Dokku provides integration with the [Caddy](https://caddyserver.com/) proxy service by utilizing the Docker label-based integration implemented by Caddy. @@ -19,7 +20,8 @@ Using the `caddy` plugin integration requires the `docker-compose-plugin` for Do ## Usage -> Warning: As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Caddy. +> [!WARNING] +> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Caddy. The Caddy plugin has specific rules for routing requests: diff --git a/docs/networking/proxies/haproxy.md b/docs/networking/proxies/haproxy.md index 94d57faa7..eda8e27bd 100644 --- a/docs/networking/proxies/haproxy.md +++ b/docs/networking/proxies/haproxy.md @@ -1,5 +1,6 @@ # Haproxy Proxy +> [!IMPORTANT] > New as of 0.28.0 Dokku provides integration with the [Haproxy](http://www.haproxy.org) proxy service by utilizing the Docker label-based integration implemented by [EasyHaproxy](https://github.com/byjg/docker-easy-haproxy). @@ -19,7 +20,8 @@ Using the `haproxy` plugin integration requires the `docker-compose-plugin` for ## Usage -> Warning: As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Haproxy. +> [!WARNING] +> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Haproxy. The Haproxy plugin has specific rules for routing requests: diff --git a/docs/networking/proxies/nginx.md b/docs/networking/proxies/nginx.md index 7fb14c93e..540ae72fd 100644 --- a/docs/networking/proxies/nginx.md +++ b/docs/networking/proxies/nginx.md @@ -15,7 +15,8 @@ nginx:validate-config [] [--clean] # Validates and optionally cleans up in ## Usage -> Warning: As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. +> [!WARNING] +> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. ### Request Proxying @@ -23,10 +24,12 @@ By default, the `web` process is the only process proxied by the nginx proxy imp Nginx will proxy the requests in a [round-robin balancing fashion](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream) to the different deployed (scaled) containers running the `web` proctype. This way, the host's resources can be fully leveraged for single-threaded applications (e.g. `dokku ps:scale node-js-app web=4` on a 4-core machine). -> Note: Due to how the plugin is implemented, if an app successfully starts up `web` containers but fails to deploy some other containers, nginx may eventually stop routing requests. Users should revert their code in these cases, or manually trigger `dokku proxy:build-config $APP` in order to ensure requests route to the new web containers. +> [!NOTE] +> Due to how the plugin is implemented, if an app successfully starts up `web` containers but fails to deploy some other containers, nginx may eventually stop routing requests. Users should revert their code in these cases, or manually trigger `dokku proxy:build-config $APP` in order to ensure requests route to the new web containers. ### Starting nginx +> [!IMPORTANT] > New as of 0.28.0 The nginx server can be started via `nginx:start`. @@ -37,6 +40,7 @@ dokku nginx:start ### Stopping nginx +> [!IMPORTANT] > New as of 0.28.0 The nginx server can be stopped via `nginx:stop`. @@ -47,9 +51,11 @@ dokku nginx:stop ### Binding to specific addresses +> [!IMPORTANT] > New as of 0.19.2 -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. By default, nginx will listen to all interfaces (`[::]` for IPv6, `0.0.0.0` for IPv4) when proxying requests to applications. This may be changed using the `bind-address-ipv4` and `bind-address-ipv6` properties. This is useful in cases where the proxying should be internal to a network or if there are multiple network interfaces that should respond with different content. @@ -65,15 +71,18 @@ dokku nginx:set node-js-app bind-address-ipv4 dokku nginx:set node-js-app bind-address-ipv6 ``` -> Warning: Validation is not performed on either value. +> [!WARNING] +> Validation is not performed on either value. Users with apps that contain a custom `nginx.conf.sigil` file will need to modify the files to respect the new `NGINX_BIND_ADDRESS_IPV4` and `NGINX_BIND_ADDRESS_IPV6` variables. ### HSTS Header +> [!IMPORTANT] > New as of 0.20.0 -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. If SSL certificates are present, HSTS will be automatically enabled. It can be toggled via `nginx:set`: @@ -93,7 +102,8 @@ Beware that if you enable the header and a subsequent deploy of your application #### Globally disabling the HSTS Header -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. HSTS Header can be disabled for all apps by setting the `hsts` property to false after passing the `--global` flag to `nginx:set`. @@ -145,7 +155,8 @@ dokku nginx:set node-js-app x-forwarded-ssl ### Checking access logs -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. You may check nginx access logs via the `nginx:access-logs` command. This assumes that app access logs are being stored in `/var/log/nginx/$APP-access.log`, as is the default in the generated `nginx.conf`. @@ -175,9 +186,11 @@ dokku nginx:error-logs node-js-app -t ### Changing log path +> [!IMPORTANT] > New as of 0.20.1 -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. The path to where log files are stored can be changed by calling the `nginx:set` command with the following options: @@ -202,9 +215,11 @@ In all cases, the nginx config must be regenerated after setting the above value ### Changing log format +> [!IMPORTANT] > New as of 0.22.0 -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. The format of the access log can be changed by calling the `nginx:set` command as follows: @@ -245,9 +260,11 @@ dokku proxy:build-config node-js-app ### Specifying a read timeout +> [!IMPORTANT] > New as of 0.21.0 -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. When proxying requests to your applications, it may be useful to specify a proxy read timeout. This can be done via the `nginx:set` command as follows: @@ -267,9 +284,11 @@ In all cases, the nginx config must be regenerated after setting the above value ### Specifying a custom client_max_body_size +> [!IMPORTANT] > New as of 0.23.0 -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. Users can override the default `client_max_body_size` value - which limits file uploads - via `nginx:set`. Changing this value will only apply to every `server` stanza of the default `nginx.conf.sigil`; users of custom `nginx.conf.sigil` files must update their templates to support the new value. @@ -309,7 +328,8 @@ As app nginx configs are actually executed within a shared context, it is possib The `nginx:validate-config` command also takes an optional `--clean` flag. If specified, invalid nginx configs will be removed. -> Warning: Invalid app nginx config's will be removed _even if_ the config is valid in the global server context. +> [!WARNING] +> Invalid app nginx config's will be removed _even if_ the config is valid in the global server context. ```shell dokku nginx:validate-config --clean @@ -323,6 +343,7 @@ dokku nginx:validate-config node-js-app --clean ### Customizing the nginx configuration +> [!IMPORTANT] > New as of 0.5.0 Dokku uses a templating library by the name of [sigil](https://github.com/gliderlabs/sigil) to generate nginx configuration for each app. This may be overriden by committing the [default configuration template](https://github.com/dokku/dokku/blob/master/plugins/nginx-vhosts/templates/nginx.conf.sigil) to a file named `nginx.conf.sigil` in the root of the app repository. @@ -352,7 +373,8 @@ dokku nginx:set --global nginx-conf-sigil-path #### Disabling custom nginx config -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. While enabled by default, using a custom nginx config can be disabled via `nginx:set`. This may be useful in cases where you do not want to allow users to override any higher-level customization of app nginx config. @@ -383,7 +405,8 @@ Unsetting this value is the same as enabling custom nginx config usage. Finally, each process type has it's network listeners - a list of IP:PORT pairs for the respective app containers - exposed via an `.DOKKU_APP_${PROCESS_TYPE}_LISTENERS` variable - the `PROCESS_TYPE` will be upper-cased with hyphens transformed into underscores. Users can use the new variables to expose non-web processes via the nginx proxy. -> Note: Application environment variables are available for use in custom templates. To do so, use the form of `{{ var "FOO" }}` to access a variable named `FOO`. +> [!NOTE] +> Application environment variables are available for use in custom templates. To do so, use the form of `{{ var "FOO" }}` to access a variable named `FOO`. #### Customizing via configuration files included by the default templates @@ -436,7 +459,8 @@ These are provided as an alternative to the generic Nginx error page, are shared By default, Dokku will route any received request with an unknown HOST header value to the lexicographically first site in the nginx config stack. This means that accessing the dokku server via its IP address or a bogus domain name may return a seemingly random website. -> Warning: some versions of Nginx may create a default site when installed. This site is simply a static page which says "Welcome to Nginx", and if this default site is enabled, Nginx will not route any requests with an unknown HOST header to Dokku. If you want Dokku to receive all requests, run the following commands: +> [!WARNING] +> some versions of Nginx may create a default site when installed. This site is simply a static page which says "Welcome to Nginx", and if this default site is enabled, Nginx will not route any requests with an unknown HOST header to Dokku. If you want Dokku to receive all requests, run the following commands: > > ``` > rm /etc/nginx/sites-enabled/default diff --git a/docs/networking/proxies/openresty.md b/docs/networking/proxies/openresty.md index 65299f462..6a790ab20 100644 --- a/docs/networking/proxies/openresty.md +++ b/docs/networking/proxies/openresty.md @@ -1,5 +1,6 @@ # OpenResty Proxy +> [!IMPORTANT] > New as of 0.31.0 Dokku can provide integration with the [OpenResty](https://openresty.org/) proxy service by utilizing the Docker label-based integration implemented by [openresty-docker-proxy](https://github.com/dokku/openresty-docker-proxy). @@ -19,7 +20,8 @@ Using the `openresty` plugin integration requires the `docker-compose-plugin` fo ## Usage -> Warning: As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to OpenResty. +> [!WARNING] +> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to OpenResty. The OpenResty plugin has specific rules for routing requests: diff --git a/docs/networking/proxies/traefik.md b/docs/networking/proxies/traefik.md index ceff53c77..bf89e9398 100644 --- a/docs/networking/proxies/traefik.md +++ b/docs/networking/proxies/traefik.md @@ -1,5 +1,6 @@ # Traefik Proxy +> [!IMPORTANT] > New as of 0.28.0 Dokku provides integration with the [Traefik](https://traefik.io/) proxy service by utilizing the Docker label-based integration implemented by Traefik. @@ -19,7 +20,8 @@ Using the `traefik` plugin integration requires the `docker-compose-plugin` for ## Usage -> Warning: As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Traefik. +> [!WARNING] +> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Traefik. The Traefik plugin has specific rules for routing requests: @@ -154,7 +156,8 @@ Traefik exposes an API and Dashboard, which Dokku disables by default for securi #### Enabling the api -> Warning: Users enabling the dashboard should also enable api basic auth. +> [!WARNING] +> Users enabling the dashboard should also enable api basic auth. By default, the api is disabled. To enable, set the `api` property with the `--global` flag: @@ -166,7 +169,8 @@ After enabling, the Traefik container will need to be restarted. #### Enabling the dashboard -> Warning: Users enabling the dashboard should also enable api basic auth. +> [!WARNING] +> Users enabling the dashboard should also enable api basic auth. By default, the dashboard is disabled. To enable, set the `dashboard` property with the `--global` flag: diff --git a/docs/networking/proxy-management.md b/docs/networking/proxy-management.md index a07066541..49f58890b 100644 --- a/docs/networking/proxy-management.md +++ b/docs/networking/proxy-management.md @@ -1,5 +1,6 @@ # Proxy Management +> [!IMPORTANT] > New as of 0.5.0, Enhanced in 0.6.0 ``` @@ -43,6 +44,7 @@ dokku proxy:build-config --all --parallel -1 ### Clearing the generated proxy config +> [!IMPORTANT] > New as of 0.27.0 Generated proxy configurations can also be cleared using the `proxy:clear-config` command. @@ -61,6 +63,7 @@ Clearing a proxy configuration has different effects depending on the proxy plug ### Displaying proxy reports for an app +> [!IMPORTANT] > New as of 0.8.1 You can get a report about the app's proxy status using the `proxy:report` command: diff --git a/docs/processes/entering-containers.md b/docs/processes/entering-containers.md index 5fdf90840..4d663155d 100644 --- a/docs/processes/entering-containers.md +++ b/docs/processes/entering-containers.md @@ -1,5 +1,6 @@ # Entering containers +> [!IMPORTANT] > New as of 0.4.0 ``` diff --git a/docs/processes/one-off-tasks.md b/docs/processes/one-off-tasks.md index 60e148db7..11419dc94 100644 --- a/docs/processes/one-off-tasks.md +++ b/docs/processes/one-off-tasks.md @@ -16,6 +16,7 @@ Sometimes it is necessary to run a one-off command under an app. Dokku makes it The `run` command can be used to run a one-off process for a specific command. This will start a new container and run the desired command within that container. The container image will be the same container image as was used to start the currently deployed app. +> [!IMPORTANT] > New as of 0.25.0, this container will be removed after the process exits. ```shell @@ -51,6 +52,7 @@ dokku --label=com.example.test-label=value run node-js-app ls -lah #### Disabling TTY +> [!IMPORTANT] > New as of 0.25.0 One-off containers default to interactive mode where possible. To disable this behavior, specify the `--no-tty` flag: @@ -61,6 +63,7 @@ dokku run --no-tty node-js-app ls -lah ### Running a detached container +> [!IMPORTANT] > New as of 0.25.0 Finally, a container can be run in "detached" mode via the `run:detached` Dokku command. Running a process in detached mode will immediately return a `CONTAINER_ID`. Detached containers are run without a tty and are also removed at the end of process execution. @@ -101,6 +104,7 @@ The above command will show logs continually from the `node-js-app.run.1234` one ### Listing one-off containers +> [!IMPORTANT] > New as of 0.25.0 One-off containers for a given app can be listed via the `run:list` command: @@ -136,6 +140,7 @@ dokku run:list node-js-app --format json ### Stopping a one-off container +> [!IMPORTANT] > New as of 0.29.0 Run containers for an app can be stopped via the `run:stop` command. The output will be the container id. diff --git a/docs/processes/process-management.md b/docs/processes/process-management.md index 8485eb52d..839081734 100644 --- a/docs/processes/process-management.md +++ b/docs/processes/process-management.md @@ -1,5 +1,6 @@ # Process Management +> [!IMPORTANT] > New as of 0.3.14, Enhanced in 0.7.0 ``` @@ -18,6 +19,7 @@ ps:stop [--parallel count] [--all|] # Stop an app ### Inspecting app containers +> [!IMPORTANT] > New as of 0.13.0 A common administrative task to perform is calling `docker inspect` on the containers that are running for an app. This can be an error-prone task to perform, and may also reveal sensitive environment variables if not done correctly. Dokku provides a wrapper around this command via the `ps:inspect` command: @@ -109,7 +111,8 @@ web: 1 #### Procfile -> Note: Dokku supports the Procfile format as defined in [this document](https://github.com/dokku/procfile-util/blob/master/PROCFILE_FORMAT.md) under "Strict Mode" parsing rules. +> [!NOTE] +> Dokku supports the Procfile format as defined in [this document](https://github.com/dokku/procfile-util/blob/master/PROCFILE_FORMAT.md) under "Strict Mode" parsing rules. Apps can define processes to run by using a `Procfile`. A `Procfile` is a simple text file that can be used to specify multiple commands, each of which is subject to process scaling. In the case where the built image sets a default command to run - either through usage of `CMD` for Dockerfile-based builds, a default process for buildpack-based builds, or any other method for the builder in use - the `Procfile` will take precedence. @@ -277,6 +280,7 @@ dokku ps:start --all --parallel -1 ### Restart policies +> [!IMPORTANT] > New as of 0.7.0, Command Changed in 0.22.0 By default, Dokku will automatically restart containers that exit with a non-zero status up to 10 times via the [on-failure Docker restart policy](https://docs.docker.com/engine/reference/run/#restart-policies---restart). @@ -313,6 +317,7 @@ Dokku also runs `dokku-event-listener` in the background via the system's init s ### Displaying reports for an app +> [!IMPORTANT] > New as of 0.12.0 You can get a report about the deployed apps using the `ps:report` command: diff --git a/docs/processes/scheduled-cron-tasks.md b/docs/processes/scheduled-cron-tasks.md index 5dce920ac..1a4212407 100644 --- a/docs/processes/scheduled-cron-tasks.md +++ b/docs/processes/scheduled-cron-tasks.md @@ -1,5 +1,6 @@ # Scheduled Cron Tasks +> [!IMPORTANT] > New as of 0.23.0 ``` @@ -125,7 +126,8 @@ dokku cron:report node-js-app --cron-task-count ### Self Managed Cron -> Warning: Self-managed cron tasks should be considered advanced usage. While the instructions are available, users are highly encouraged to use the built-in scheduled cron task support unless absolutely necessary. +> [!WARNING] +> Self-managed cron tasks should be considered advanced usage. While the instructions are available, users are highly encouraged to use the built-in scheduled cron task support unless absolutely necessary. Some installations may require more fine-grained control over cron usage. The following are advanced instructions for configuring cron.