Jose Diaz-Gonzalez
12
docs/appendices/0.36.0-migration-guide.md
Normal file
12
docs/appendices/0.36.0-migration-guide.md
Normal file
@@ -0,0 +1,12 @@
|
||||
# 0.36.0 Migration Guide
|
||||
|
||||
## Changes
|
||||
|
||||
- Process stop timeouts are now configured via the `ps` property `stop-timeout-seconds`. Existing `DOKKU_DOCKER_STOP_TIMEOUT` environment variables will be automatically migrated to the new value.
|
||||
- Processes now default to a `30` second stop timeout.
|
||||
- The `domains:clear` command no longer runs domain setup after clearing the domains. Use `domains:reset` or run `domains:setup` manually to have the same effect.
|
||||
- The deprecated `DOKKU_DISABLE_ANSI_PREFIX_REMOVAL` setting has been removed. Dokku deploys no longer use shell escape codes to modify output, and thus deploy output may now contain `remote:` as a prefix in each lines output.
|
||||
|
||||
## Deprecations
|
||||
|
||||
Ubuntu 20.04 is now a deprecated installation target. The operating system will be considered EOL by Canonical in April 2025. Users are encouraged to upgrade to Ubuntu 24.04 or consider switching their instllation method to the [Docker-based installation method](/docs/getting-started/install/docker.md) to avoid any disruption in usage.
|
||||
@@ -13,6 +13,7 @@ domains:enable <app> # Enable VHOST support
|
||||
domains:remove <app> <domain> [<domain> ...] # Remove domains from app
|
||||
domains:remove-global <domain> [<domain> ...] # Remove global domain names
|
||||
domains:report [<app>|--global] [<flag>] # Displays a domains report for one or more apps
|
||||
domains:reset <app> # Reset app domains to global-configured domains
|
||||
domains:set <app> <domain> [<domain> ...] # Set domains for app
|
||||
domains:set-global <domain> [<domain> ...] # Set global domain names
|
||||
```
|
||||
@@ -75,6 +76,9 @@ dokku domains:remove node-js-app dokku.me
|
||||
|
||||
# set all custom domains for app
|
||||
dokku domains:set node-js-app dokku.me dokku.org
|
||||
|
||||
# delete all app domains and configure available global domains on it
|
||||
dokku domains:reset node-js-app
|
||||
```
|
||||
|
||||
## Displaying domains reports for an app
|
||||
|
||||
@@ -110,9 +110,7 @@ The following config variables have special meanings and can be set in a variety
|
||||
| `DOKKU_CHECKS_ATTEMPTS` | `5` | `dokku config:set` | Number of retries for to run for a specific check before marking it as a failure
|
||||
| `DOKKU_DEFAULT_CHECKS_WAIT` | `10` | `dokku config:set` | If no user-defined checks are specified - or if the process being checked is not a `web` process - this is the period of time Dokku will wait before checking that a container is still running. |
|
||||
| `DOKKU_DISABLE_PROXY` | none | `dokku proxy:disable` <br /> `dokku proxy:enable` | Disables the proxy in front of your application, resulting in publicly routing the docker container. |
|
||||
| `DOKKU_DISABLE_ANSI_PREFIX_REMOVAL` | none | `dokku config:set` <br /> `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | Disables removal of the ANSI prefix during deploys. Can be used in cases where the client deployer does not understand ansi escape codes. |
|
||||
| `DOKKU_DISABLE_APP_AUTOCREATION` | none | `dokku config:set` | Disables automatic creation of a non-existent app on deploy. |
|
||||
| `DOKKU_DOCKER_STOP_TIMEOUT` | `10` | `dokku config:set` | Configurable grace period given to the `docker stop` command. If a container has not stopped by this time, a `kill -9` signal or equivalent is sent in order to force-terminate the container. Both the `ps:stop` and `apps:destroy` commands _also_ respect this value. If not specified, the docker defaults for the [docker stop command](https://docs.docker.com/engine/reference/commandline/stop/) will be used.|
|
||||
| `DOKKU_DOCKERFILE_CACHE_BUILD` | none | `dokku config:set` | |
|
||||
| `DOKKU_DOCKERFILE_START_CMD` | none | `dokku config:set` | |
|
||||
| `DOKKU_PARALLEL_ARGUMENTS`. | none | `dokku config:set` | Allows passing custom arguments to parallel for `ps:*all` commands |
|
||||
|
||||
@@ -141,6 +141,7 @@ The k3s plugin provides a number of settings that can be used to managed deploym
|
||||
| Name | Description | Global Default |
|
||||
|-----------------------|---------------------------------------------------|--------------------|
|
||||
| `deploy-timeout` | Controls when app deploys will timeout in seconds | `300s` |
|
||||
| `kustomize-root-path` | Controls the folder context from the deployed repository used for Kustomize | `config/kustomize` |
|
||||
| `image-pull-secrets` | Name of a kubernetes secret used to auth against a registry | Contents of `~/.docker/config.json` from Dokku server |
|
||||
| `namespace` | Controls the namespace used for resource creation | `default` |
|
||||
| `rollback-on-failure` | Whether to rollback failed deploys | `false` |
|
||||
@@ -365,7 +366,6 @@ dokku scheduler-k3s:ensure-charts
|
||||
|
||||
Once the chart is configured, an `http` trigger can be specified like so:
|
||||
|
||||
|
||||
```json
|
||||
{
|
||||
"formation": {
|
||||
@@ -461,6 +461,30 @@ dokku scheduler-k3s:autoscaling-auth:report node-js-app --include-metadata
|
||||
Datadog datadogSite: us5.datadoghq.com
|
||||
```
|
||||
|
||||
### Integrating Kustomize
|
||||
|
||||
Dokku supports integration with [Kustomize](https://kustomize.io/) to further customize the generated helm charts for app deployments. For example, a `config/kustomize/kustomization.yaml` file with the following contents will override the scale for each process deployed to `3`:
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
resources:
|
||||
- rendered.yaml
|
||||
patches:
|
||||
- patch: |-
|
||||
- op: replace
|
||||
path: /spec/replicas
|
||||
value: 3
|
||||
target:
|
||||
group: apps
|
||||
version: v1
|
||||
kind: Deployment
|
||||
```
|
||||
|
||||
When using Kustomize with Dokku, all Kustomize-files _must_ be placed in the `config/kustomize` folder, with a `kustomization.yaml` file being the entrypoint to Kustomize. Dokku will render the helm chart to a `rendered.yaml` file, and then execute Kustomize with the `config/kustomize` folder as the context.
|
||||
|
||||
See the [Kustomize](https://kustomize.io/) website for more details on how to use Kustomize.
|
||||
|
||||
### Using kubectl remotely
|
||||
|
||||
> [!WARNING]
|
||||
@@ -515,7 +539,6 @@ dokku scheduler-k3s:set --global chart.cert-manager.version 1.13.3
|
||||
> [!NOTE]
|
||||
> Properties follow dot-notation, and are expanded according to Helm's internal logic. See the [Helm documentation](https://helm.sh/docs/helm/helm_install/#helm-install) for `helm install` for further details.
|
||||
|
||||
|
||||
To unset a chart property, omit the value from the `scheduler-k3s:set` call:
|
||||
|
||||
```shell
|
||||
|
||||
@@ -98,7 +98,7 @@ At this time, the following dokku commands are used to implement a complete sche
|
||||
- `apps:clone`: handles app cloning
|
||||
- triggers: post-app-clone-setup
|
||||
- `cron`: generates cron tasks for the app
|
||||
- triggers: cron-write
|
||||
- triggers: scheduler-cron-write
|
||||
- `deploy`: deploys app proceses and checks the status of a deploy
|
||||
- triggers: scheduler-app-status, scheduler-deploy, scheduler-is-deployed, scheduler-logs-failed
|
||||
- `enter`: enters a running container
|
||||
@@ -112,7 +112,9 @@ At this time, the following dokku commands are used to implement a complete sche
|
||||
- `run:logs`: fetches running container logs
|
||||
- triggers: scheduler-run-logs
|
||||
- `ps:stop`: stops app processes
|
||||
- triggers: scheduler-stop
|
||||
- triggers: scheduler-stop, scheduler-cron-write
|
||||
- `ps:start`: starts app processes
|
||||
- triggers: scheduler-deploy, scheduler-cron-write
|
||||
- `ps:inspect`: outputs inspect output for processes in an app
|
||||
- triggers: scheduler-inspect
|
||||
|
||||
|
||||
@@ -36,12 +36,15 @@ dokku checks:set node-js-app wait-to-retire 30
|
||||
|
||||
Defaults to `60`.
|
||||
|
||||
## Setting stop grace period
|
||||
|
||||
You can set the `stop-timeout-seconds` property on the `ps` plugin to change this value (default: `30`). See the [process management documentation](/docs/processes/process-management.md#changing-process-management-settings) for more information.
|
||||
|
||||
## Configuring check settings using the `config` plugin
|
||||
|
||||
There are certain settings that can be configured via environment variables:
|
||||
|
||||
- `DOKKU_DEFAULT_CHECKS_WAIT`: (default: `10`) If no user-defined checks are specified - or if the process being checked is not a `web` process - this is the period of time Dokku will wait before checking that a container is still running.
|
||||
- `DOKKU_DOCKER_STOP_TIMEOUT`: (default: `10`) Configurable grace period given to the `docker stop` command. If a container has not stopped by this time, a `kill -9` signal or equivalent is sent in order to force-terminate the container. Both the `ps:stop` and `apps:destroy` commands *also* respect this value. If not specified, the Docker defaults for the [`docker stop` command](https://docs.docker.com/engine/reference/commandline/stop/) will be used.
|
||||
|
||||
The following settings may also be specified in the `app.json` file, though are available as environment variables in order to ease application reuse.
|
||||
|
||||
|
||||
@@ -119,6 +119,21 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
|
||||
# TODO
|
||||
```
|
||||
|
||||
### `app-json-is-valid`
|
||||
|
||||
- Description: Checks to see if the provided app.json file is valid
|
||||
- Invoked by: Appjson extraction during deployment
|
||||
- Arguments: `$APP $APP_JSON_PATH`
|
||||
- Example:
|
||||
|
||||
```shell
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
|
||||
|
||||
# TODO
|
||||
```
|
||||
|
||||
### `app-maybe-create`
|
||||
|
||||
- Description: Creates an app (gated by whether this is globally enabled or not)
|
||||
@@ -583,22 +598,6 @@ DOKKU_SCHEDULER="$1"
|
||||
# TODO
|
||||
```
|
||||
|
||||
### `cron-write`
|
||||
|
||||
- Description: Force triggers writing out cron entries
|
||||
- Invoked by:
|
||||
- Arguments:
|
||||
- Example:
|
||||
|
||||
```shell
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
|
||||
source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
|
||||
|
||||
# TODO
|
||||
```
|
||||
|
||||
### `dependencies`
|
||||
|
||||
- Description: Used to install system-level dependencies.
|
||||
@@ -1700,7 +1699,7 @@ curl "http://httpstat.us/200"
|
||||
### `post-domains-update`
|
||||
|
||||
- Description: Allows you to run commands once the domain for an app has been updated. It also sends in the command that has been used. This can be "add", "clear" or "remove". The third argument will be the optional list of domains
|
||||
- Invoked by: `dokku domains:add`, `dokku domains:clear`, `dokku domains:remove`, `dokku domains:set`
|
||||
- Invoked by: `dokku domains:add`, `dokku domains:clear`, `dokku domains:remove`, `dokku domains:reset`, `dokku domains:set`
|
||||
- Arguments: `$APP` `action name` `domains`
|
||||
- Example:
|
||||
|
||||
@@ -2445,6 +2444,26 @@ DOKKU_SCHEDULER="$1"; APP="$2";
|
||||
# TODO
|
||||
```
|
||||
|
||||
### `scheduler-cron-write`
|
||||
|
||||
> [!WARNING]
|
||||
> The scheduler plugin trigger apis are under development and may change
|
||||
> between minor releases until the 1.0 release.
|
||||
|
||||
- Description: Force triggers writing out cron entries. Arguments are optional.
|
||||
- Invoked by: `ps:start`, `ps:stop`, `cron:set`
|
||||
- Arguments: `$DOKKU_SCHEDULER $APP`
|
||||
- Example:
|
||||
|
||||
```shell
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
|
||||
source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
|
||||
|
||||
# TODO
|
||||
```
|
||||
|
||||
### `scheduler-deploy`
|
||||
|
||||
> [!WARNING]
|
||||
|
||||
@@ -13,7 +13,7 @@ All pull requests have tests run against them on [GitHub Actions](https://github
|
||||
|
||||
If you wish to skip tests for a particular commit, e.g. documentation changes, you may add the `[ci skip]` designator to your commit message. Commits that _should_ be tested but have the above designator will not be merged.
|
||||
|
||||
While we do provide official packages for a variety of platforms, as our test suite currently runs on Ubuntu Noble 24.04, we only provide official installation support for that platform and the supported LTS releases of Ubuntu (currently 20.04, 22.04, and 24.04).
|
||||
While we do provide official packages for a variety of platforms, as our test suite currently runs on Ubuntu Noble 24.04, we only provide official installation support for that platform and the supported LTS releases of Ubuntu (currently 22.04, and 24.04).
|
||||
|
||||
## Local Test Execution
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ Dokku is an extensible, open source Platform as a Service that runs on a single
|
||||
To start using Dokku, you'll need a system that meets the following minimum requirements:
|
||||
|
||||
- A fresh installation of any of the following operating systems:
|
||||
- [Ubuntu 20.04/22.04/24.04](https://www.ubuntu.com/download)
|
||||
- [Ubuntu 22.04/24.04](https://www.ubuntu.com/download)
|
||||
- [Debian 11+ x64](https://www.debian.org/distrib/)
|
||||
- A server with one of the following architectures
|
||||
- AMD64 (alternatively known as `x86_64`), commonly used for Intel cloud servers
|
||||
|
||||
@@ -117,6 +117,16 @@ dokku caddy:set --global log-level DEBUG
|
||||
|
||||
After modifying, the Caddy container will need to be restarted.
|
||||
|
||||
### Changing the label key for the app
|
||||
|
||||
The default label key for the app is `caddy`. This can be changed by setting the `label-key` property:
|
||||
|
||||
```shell
|
||||
dokku caddy:set node-js-app label-key caddy_0
|
||||
```
|
||||
|
||||
This will update the app's label key to `caddy_0`. The label key is used to identify the app in the Caddy configuration. If you change the label key, you will need to restart or rebuild the app to apply the updates.
|
||||
|
||||
### SSL Configuration
|
||||
|
||||
The caddy plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the `certs` plugin are ignored.
|
||||
|
||||
@@ -332,6 +332,7 @@ Changing these value globally or on a per-app basis will require rebuilding the
|
||||
| keepalive-timeout | `75s` | string | Timeout (with units) during which a keep-alive client connection will stay open on the server side |
|
||||
| lingering-timeout | `5s` | string | Timeout (with units) is the maximum waiting time for more client data to arrive |
|
||||
| nginx-conf-sigil-path | `nginx.conf.sigil` | string | Path in the repository to the `nginx.conf.sigil` file |
|
||||
| nginx-service-command | | string | Full path to an executable script or binary to invoke instead of the system's init process when interacting with nginx |
|
||||
| proxy-buffer-size | `8k` (# is os pagesize) | string | Size of the buffer used for reading the first part of proxied server response |
|
||||
| proxy-buffering | `on` | string | Enables or disables buffering of responses from the proxied server |
|
||||
| proxy-buffers | `8 8k` | string | Number and size of the buffers used for reading the proxied server response, for a single connection |
|
||||
|
||||
@@ -158,6 +158,8 @@ At this time, the following dokku commands are used to interact with a complete
|
||||
- triggers: `pre-enable-vhost`
|
||||
- `domains:remove`: Removes a domain from an app.
|
||||
- triggers: `post-domains-update`
|
||||
- `domains:reset`: Reset app domains to global-configured domains.
|
||||
- triggers: `post-domains-update`
|
||||
- `domains:set`: Sets all domains for a given app.
|
||||
- triggers: `post-domains-update`
|
||||
- `proxy:build-config`: Builds - or rebuilds - external proxy configuration.
|
||||
|
||||
@@ -107,6 +107,38 @@ proctype: qty
|
||||
web: 1
|
||||
```
|
||||
|
||||
### Changing process management settings
|
||||
|
||||
The `ps` plugin provides a number of settings that can be used to managed deployments on a per-app basis. The following table outlines ones not covered elsewhere:
|
||||
|
||||
| Name | Description | Global Default |
|
||||
|-----------------------|---------------------------------------------------|--------------------|
|
||||
| `stop-timeout` | Configurable grace period given to the `docker stop` command. If a container has not stopped by this time, a `kill -9` signal or equivalent is sent in order to force-terminate the container. Both the `ps:stop` and `apps:destroy` commands *also* respect this value. If not specified, the Docker defaults for the [`docker stop` command](https://docs.docker.com/engine/reference/commandline/stop/) will be used. | `30` |
|
||||
|
||||
All settings can be set via the `ps:set` command. Using `stop-timeout` as an example:
|
||||
|
||||
```shell
|
||||
dokku ps:set node-js-app stop-timeout 60
|
||||
```
|
||||
|
||||
The default value may be set by passing an empty value for the option in question:
|
||||
|
||||
```shell
|
||||
dokku ps:set node-js-app stop-timeout
|
||||
```
|
||||
|
||||
Properties can also be set globally. If not set for an app, the global value will apply.
|
||||
|
||||
```shell
|
||||
dokku ps:set --global stop-timeout 60
|
||||
```
|
||||
|
||||
The global default value may be set by passing an empty value for the option.
|
||||
|
||||
```shell
|
||||
dokku ps:set --global stop-timeout
|
||||
```
|
||||
|
||||
### Defining Processes
|
||||
|
||||
#### Procfile
|
||||
|
||||
@@ -53,39 +53,39 @@ When running scheduled cron tasks, there are a few items to be aware of:
|
||||
- Scheduled cron tasks are supported on a per-scheduler basis, and are currently only implemented by the `docker-local` scheduler.
|
||||
- Tasks for _all_ apps managed by the `docker-local` scheduler are written to a single crontab file owned by the `dokku` user. The `dokku` user's crontab should be considered reserved for this purpose.
|
||||
|
||||
#### Specifying a MAILFROM value
|
||||
|
||||
> [!IMPORTANT]
|
||||
> New as of 0.35.14
|
||||
### Changing cron management settings
|
||||
|
||||
Users can specify a value for `MAILFROM` via the global `mailfrom` cron property by using the `cron:set` command.
|
||||
The `cron` plugin provides a number of settings that can be used to managed deployments on a per-app basis. The following table outlines ones not covered elsewhere:
|
||||
|
||||
| Name | Description | Level | Global Default |
|
||||
|-----------------------|----------------------------------------------------------------|-------------|----------------|
|
||||
| `mailfrom` | Sets the `MAILFROM` variable in a cron file for cron reporting | Global-only | empty string |
|
||||
| `maintenance` | Whether to have cron running for the app or not. | App-only | `false` |
|
||||
| `mailto` | Sets the `MAILTO` variable in a cron file for cron reporting | Global-only | empty string |
|
||||
|
||||
All settings can be set via the `cron:set` command. Using `maintenance` as an example:
|
||||
|
||||
```shell
|
||||
dokku cron:set --global mailfrom example@example.com
|
||||
dokku cron:set node-js-app maintenance true
|
||||
```
|
||||
|
||||
All output for individual cron runs will be sent from the specified email.
|
||||
|
||||
Cron emails can be reset to use the system email by running the `cron:set` command for the global `mailfrom` property with no value.
|
||||
The default value may be set by passing an empty value for the option in question:
|
||||
|
||||
```shell
|
||||
dokku cron:set --global mailfrom
|
||||
dokku cron:set node-js-app maintenance
|
||||
```
|
||||
|
||||
#### Specifying a MAILTO value
|
||||
|
||||
By default, cron tasks complete and do not perform any reporting. Users can specify a value for `MAILTO` via the global `mailto` cron property by using the `cron:set` command.
|
||||
If a property can be set globally - such as `mailto`, use the `--global` flag. If not set for an app, the global value will apply if it exists.
|
||||
|
||||
```shell
|
||||
dokku cron:set --global mailto example@example.com
|
||||
dokku cron:set --global maintenance true
|
||||
```
|
||||
|
||||
All output for individual cron runs will be sent to the specified email.
|
||||
|
||||
Cron emails can be disabled by running the `cron:set` command for the global `mailto` property with no value.
|
||||
The global default value may be set by passing an empty value for the option.
|
||||
|
||||
```shell
|
||||
dokku cron:set --global mailto
|
||||
dokku cron:set --global maintenance
|
||||
```
|
||||
|
||||
#### Listing Cron tasks
|
||||
|
||||
Reference in New Issue
Block a user