# History
## 0.34.2
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.34.2/bootstrap.sh
sudo DOKKU_TAG=v0.34.2 bash bootstrap.sh
```
### Bug Fixes
- #6779: @josegonzalez Add --global flag to ps:set
- #6778: @josegonzalez Popd out of tmp directory after a git push-based deployment
- #6777: @josegonzalez Use correct function name in openresty:report output
### Documentation
- #6781: @josegonzalez Update builder management docs to warn that globally setting a builder will force all apps to use that builder
- #6780: @josegonzalez Clarify ssh-keys commands to run when adding ssh keys in docker-based installation
### Other
- #6776: @josegonzalez Use a long git sha in the git:report output
The previous method sometimes truncated the sha, depending on how the app was deployed. Using the long sha will ensure that the value is stable, regardless of the deployment method.
Closes#6770
# History
## 0.34.1
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.34.1/bootstrap.sh
sudo DOKKU_TAG=v0.34.1 bash bootstrap.sh
```
### Bug Fixes
- #6775: @josegonzalez Ensure files get created with the correct permissions when building with herokuish
- #6739: @AndrewKvalheim Dereference annotated git tags when deploying via git:sync
- #6743: @testwill Fix typo in app-json output
### New Features
- #6768: @josegonzalez Migrate away from transitional packages
### Documentation
- #6763: @iloveitaly Add docker-compose example to installation docs
- #6757: @josegonzalez Add documentation issue template
- #6742: @josegonzalez Remove trailing whitespace from history doc
### Dependencies
- #6772: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 43.0.1 to 44.0.0
- #6766: @dependabot[bot] chore(deps): bump mkdocs-material from 9.5.14 to 9.5.15 in /docs/_build
- #6744: @dependabot[bot] chore(deps): bump github.com/docker/docker from 24.0.7+incompatible to 24.0.9+incompatible in /plugins/scheduler-k3s
- #6754: @dependabot[bot] chore(deps): bump express from 4.18.3 to 4.19.1 in /tests/apps/dockerfile-app-json-formations
- #6745: @dependabot[bot] chore(deps): bump express from 4.18.3 to 4.19.1 in /tests/apps/nodejs-express
- #6746: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 43.0.0 to 43.0.1
- #6747: @dependabot[bot] chore(deps): bump express from 4.18.3 to 4.19.1 in /tests/apps/.websocket.disabled
- #6748: @dependabot[bot] chore(deps): bump express from 4.18.3 to 4.19.1 in /tests/apps/nodejs-express-noprocfile
- #6749: @dependabot[bot] chore(deps): bump express from 4.18.3 to 4.19.1 in /tests/apps/nodejs-express-noappjson
- #6750: @dependabot[bot] chore(deps): bump express from 4.18.3 to 4.19.1 in /tests/apps/dockerfile-procfile-bad
- #6751: @dependabot[bot] chore(deps): bump importlib-metadata from 7.0.2 to 7.1.0 in /docs/_build
- #6752: @dependabot[bot] chore(deps): bump express from 4.18.3 to 4.19.1 in /tests/apps/dockerfile-procfile
- #6753: @dependabot[bot] chore(deps): bump express from 4.18.3 to 4.19.1 in /tests/apps/gitsubmodules
- #6741: @dependabot[bot] chore(deps): bump github.com/onsi/gomega from 1.31.1 to 1.32.0 in /plugins/common
- #6740: @dependabot[bot] chore(deps): bump github.com/onsi/gomega from 1.31.1 to 1.32.0 in /plugins/config
Several of the packages being installed were actually transitional packages, that is, the package itself is either a complete no-op (since the package is already installed), or else the package only exists to depend on another package of a new name (to support people who are running older operating systems).
For the former, we can drop the dependency entirely, and for the latter we should use the new package name directly.
refs/heads/master cannot be updated to an annotated tag per se; the rev
given must first be resolved to a commit. ^{commit} recursively
dereferences the rev until a commit is found.
Resolves#6737 and test failure:
# bats --filter annotated-tag tests/unit/git_3.bats
git_3.bats
✗ (git) git:sync existing [--no-build annotated-tag]
fatal: update_ref failed for ref 'refs/heads/master': cannot update ref 'refs/heads/master': trying to write non-commit object 6399bed673f513332f3d5d99e777e0262f42404c to branch 'refs/heads/master'
# History
## 0.34.0
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.34.0/bootstrap.sh
sudo DOKKU_TAG=v0.34.0 bash bootstrap.sh
```
See the [0.34.0 migration guide](/docs/appendices/0.34.0-migration-guide.md) for more information on migrating to 0.34.0.
### Bug Fixes
- #6724: @josegonzalez Correctly check if a repository has code or not in git plugin
- #6721: @josegonzalez Correct issue where cron properties cannot be retrieved if global
- #6720: @josegonzalez Add nginx-property binary to gitignore
- #6708: @josegonzalez Correctly handle quoted spaces over ssh
- #6707: @josegonzalez Correct issue where removing by index failed due to incorrect input validation
- #6705: @josegonzalez Ensure we cleanup the data directory on app deletion
- #6703: @josegonzalez Use copytruncate in logrotate commands
### New Features
- #6725: @josegonzalez Warn when publish ports if scaling up or zero downtime is enabled
- #6719: @josegonzalez Add a make target to copy the dokku binary over
- #6717: @josegonzalez Add ability to only build synced repo if there are changes
- #6715: @josegonzalez Add disk utilization to report output
- #6704: @josegonzalez Switch the default k3s routing layer from traefik to nginx
### Removals
- #6700: @josegonzalez Remove priority property from traefik plugin
### Refactors
- #6714: @josegonzalez Use CallPlugnTrigger instead of PlugnTriggerSetup
- #6713: @josegonzalez Use CallPlugnTrigger instead of PlugnTrigger
- #6712: @josegonzalez Use CallPlugnTrigger instead of PlugnTriggerOutput
- #6711: @josegonzalez Use CallPlugnTrigger instead of PlugnTriggerOutputAsString
- #6681: @josegonzalez Migrate to single ingress per app/domain combination when using nginx for k3s proxying
- #6156: @josegonzalez Migrate the app deploy lock to the data directory
### Documentation
- #6738: @josegonzalez Update migration guide for 0.34.x
- #6731: @strugee Clarify alternate proxy support status
### Dependencies
- #6736: @dependabot[bot] chore(deps): bump mkdocs-material from 9.5.13 to 9.5.14 in /docs/_build
- #6729: @dependabot[bot] chore(deps): update markdown requirement from <3.6,>=3.2.1 to >=3.2.1,<3.7 in /docs/_build
- #6728: @dependabot[bot] chore(deps): bump zipp from 3.17.0 to 3.18.1 in /docs/_build
- #6727: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 42.1.0 to 43.0.0
- #6723: @dependabot[bot] chore(deps): bump zipp from 3.17.0 to 3.18.0 in /docs/_build
- #6722: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 42.1.0 to 43.0.0
- #6710: @dependabot[bot] chore(deps): bump google.golang.org/protobuf from 1.32.0 to 1.33.0 in /plugins/scheduler-k3s
- #6709: @dependabot[bot] chore(deps): bump zipp from 3.17.0 to 3.18.0 in /docs/_build
### Other
- #6718: @josegonzalez Write current process id to all acquired lock files
- #6706: @josegonzalez Remove git:unlock command
- #6650: @bastianh Do not expose all containers via traefik by default
- #6632: @josegonzalez Simplify file ownership in the container by setting the process ownership during the build process
- #6630: @josegonzalez Remove unused code for copying cache directories
This allows us to check on what process created a lock.
Additionally, we now always have a DOKKU_PID value, even when running in cron (which does not have access to BASH_PID.
How the output is streamed changed a bit so we need to change the bats test
This will go back to zero if we ever re-implement how the container up starts for the docker-local scheduler.
These two are also still stored in the app repo directory and not copied over as properties, so would be susceptible to not having the code copied over.
The ingress-nginx ingress implementation is the standard ingress in the Kubernetes community, and it doesn't make sense for us to stray from that just to utilize the k3s default.
In the future, we might drop k3s, but this works well for now.
While using create is more correct, logs in Dokku are considered ephemeral, and thus shouldn't be considered subject to the more comprehensive log retention standards one might require out of a logging system.
By switching to copytruncate, we can ensure that logs mounted from within containers do not have that matched the old settings (closes#6633) and cases where the log file is written by a user other than the one specified in the old logrotate settings (closes#4000).
# History
## 0.33.9
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.33.9/bootstrap.sh
sudo DOKKU_TAG=v0.33.9 bash bootstrap.sh
```
### Bug Fixes
- #6695: @josegonzalez Do not attempt to install both k3s and traefik
- #6687: @josegonzalez Correct issue where ClusterTriggerAuthentication objects were filtered based on prefix
- #6686: @josegonzalez Validate input for the autoscaling-auth:set command
- #6678: @josegonzalez Handle case where most builders didn't detect amd64 images on arm64
- #6677: @josegonzalez Handle case where keda isn't installed properly
- #6676: @josegonzalez Drop extra logging call from app-json plugin
- #6674: @josegonzalez Remove systemd reverse dependency by dropping software-properties-common
### New Features
- #6698: @josegonzalez Upgrade ingress-nginx
- #6588: @taraszka Add extra tags to every image dokku push when push-extra-tags are set
- #6680: @josegonzalez Wait until helm charts are installed before marking a deploy as failed or completed
### Documentation
- #6699: @josegonzalez Add a placeholder migration guide for 0.33.0
- #6682: @josegonzalez Fix reference to formation key in autoscaling example
### Tests
- #6696: @josegonzalez Run k3s tests with a specified server ip
- #6679: @josegonzalez Split out k3s tests to speed up ci
### Dependencies
- #6697: @dependabot[bot] chore(deps): bump timberio/vector from 0.36.0-debian to 0.36.1-debian in /plugins/logs
- #6685: @dependabot[bot] chore(deps): bump github.com/go-jose/go-jose/v3 from 3.0.1 to 3.0.3 in /plugins/scheduler-k3s
- #6692: @dependabot[bot] chore(deps): bump packaging from 23.2 to 24.0 in /docs/_build
- #6693: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 42.0.7 to 42.1.0
- #6689: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 42.0.6 to 42.0.7
- #6683: @dependabot[bot] chore(deps): bump importlib-metadata from 7.0.1 to 7.0.2 in /docs/_build
- #6684: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 42.0.5 to 42.0.6
Rather than require a heavy chown operation across various paths, just chown the files already in the built image during the release process. This ensures we can skip not-only the chown process during the container start that herokuish injects, but also the one that Dokku runs which modifies mounted container paths as well during the pre-deploy.
Note that users will need to ensure any mounted volumes don't have permissions reset by other processes or containers won't be able to access them.
Setting a priority appears to cause minor outages in certain cases, so we should just avoid setting it on behalf of users and allow them to set this directly.
Domains cannot be reused across ingress objects, and port maps are a function of a domain, so the inversion here makes most sense (at the cost of some downtime when migrating.
Images would build but then fail to be tagged, causing deployment problems on arm64 architectures for a small number of images.
Also fix a minor issue in the nixpacks builder that caused any pre-release-builder triggers that consumed the image to get an empty string instead.
If keda is not installed, warn the user that it isn't installed and ignore the rest.
Ignoring the error here is fine as it gives the user context but doesn't block a deploy.
# History
## 0.33.8
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.33.8/bootstrap.sh
sudo DOKKU_TAG=v0.33.8 bash bootstrap.sh
```
### Bug Fixes
- #6675: @josegonzalez Remove the need for executing crontab as root
- #6660: @josegonzalez Handle case where systemctl isn't in /usr/bin
- #6659: @josegonzalez Add missing cron:set command
- #6658: @josegonzalez Execute go get/build with mod in readonly mode
- #6642: @josegonzalez Use correct annotations key for the ingress chart
- #6631: @josegonzalez Correctly use cache volume for herokuish builds
- #6629: @josegonzalez Use smaller reference to image pull secrets in secret naming
- #6628: @josegonzalez Ensure non-web processes do not attempt to perform web logic in k3s templates
- #6623: @josegonzalez Do not allow reusing the same scheme:host-port mappings when setting ports
- #6624: @taraszka Install jq in vagrant vm
- #6614: @josegonzalez Correct issue where --force-tty was not properly supported by run:detached calls
### New Features
- #6673: @josegonzalez Add image version as label to built images
- #6640: @josegonzalez Add initial support for injecting keda addons
- #6662: @josegonzalez Allow limiting letsencrypt to certain domains when using openresty as a proxy
- #6643: @josegonzalez Add ability to add extra labels
- #6639: @josegonzalez Add support for setting underscores-in-headers for nginx, openresty, and k3s
- #6634: @josegonzalez feat: install keda addon in k3s cluster
- #6616: @josegonzalez Ensure referenced images get updated by dependabot
- #6613: @josegonzalez Add a helper binary to deploy a test app for local development
### Refactors
- #6644: @josegonzalez Only apply the cluster issuers helm chart when setting letsencrypt properties
- #6641: @josegonzalez Rename image pull secrets to standardize on secret naming pattern
- #6626: @josegonzalez Copy code into initial base image via docker build
### Documentation
- #6656: @holamendi Fix typo in builder management docs
- #6652: @Calyhre Added dokku-mdns to list of community plugins
- #6649: @undercontr Added detach flag to Docker installation documentation
### Dependencies
- #6671: @josegonzalez Update dokku dependencies
- #6672: @dependabot[bot] chore(deps): bump golang from 1.22.0 to 1.22.1 in /tests/apps/go-fail-predeploy
- #6670: @dependabot[bot] chore(deps): bump google.golang.org/grpc from 1.62.0 to 1.62.1 in /tests/apps/gogrpc
- #6669: @dependabot[bot] chore(deps): bump google.golang.org/protobuf from 1.32.0 to 1.33.0 in /tests/apps/gogrpc
- #6668: @dependabot[bot] chore(deps): bump golang from 1.22.0 to 1.22.1 in /tests/apps/zombies-dockerfile-tini
- #6667: @dependabot[bot] chore(deps): bump golang from 1.22.0 to 1.22.1 in /tests/apps/gogrpc
- #6664: @dependabot[bot] chore(deps): bump golang from 1.22.0 to 1.22.1 in /tests/apps/go-fail-postdeploy
- #6666: @dependabot[bot] chore(deps): bump pyparsing from 3.1.1 to 3.1.2 in /docs/_build
- #6665: @dependabot[bot] chore(deps): bump mkdocs-material from 9.5.12 to 9.5.13 in /docs/_build
- #6663: @dependabot[bot] chore(deps): bump golang from 1.22.0 to 1.22.1 in /tests/apps/zombies-dockerfile-no-tini
- #6661: @josegonzalez Bump go modules
- #6654: @dependabot[bot] chore(deps): bump pymdown-extensions from 10.7 to 10.7.1 in /docs/_build
- #6653: @dependabot[bot] chore(deps): bump golang.org/x/crypto from 0.20.0 to 0.21.0 in /plugins/common
- #6651: @dependabot[bot] chore(deps): bump python-dateutil from 2.9.0 to 2.9.0.post0 in /docs/_build
- #6648: @dependabot[bot] chore(deps): bump python-dateutil from 2.8.2 to 2.9.0 in /docs/_build
- #6645: @dependabot[bot] chore(deps): bump rack from 2.2.8 to 2.2.8.1 in /tests/apps/ruby
- #6646: @dependabot[bot] chore(deps): bump mkdocs-material from 9.5.11 to 9.5.12 in /docs/_build
- #6638: @josegonzalez chore: bump go modules
- #6635: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 42.0.4 to 42.0.5
- #6636: @dependabot[bot] chore(deps): bump timberio/vector from 0.36.X-debian to 0.36.0-debian in /plugins/logs
- #6637: @dependabot[bot] chore(deps): bump golang.org/x/crypto from 0.19.0 to 0.20.0 in /plugins/common
- #6619: @dependabot[bot] chore(deps): bump traefik from v2.10 to 2.11 in /plugins/traefik-vhosts
- #6622: @josegonzalez chore(deps): bump timberio/vector from 0.35.X-debian to 0.36.X-debian in /plugins/logs
- #6618: @dependabot[bot] chore(deps): bump mkdocs-material from 9.5.10 to 9.5.11 in /docs/_build
- #6621: @dependabot[bot] chore(deps): bump byjg/easy-haproxy from 4.3.0 to 4.4.0 in /plugins/haproxy-vhosts
- #6610: @dependabot[bot] chore(deps): bump helm.sh/helm/v3 from 3.14.1 to 3.14.2 in /plugins/scheduler-k3s
Through some random machinations, software-properties-common now has a dependency on systemd. This breaks the built docker image as plugins will think systemd is available, so `dokku plugin:install --core` will reference that over sv.
Since we don't manage ppas in Dokku anymore - the only use was for an nginx ppa so we could use a newer Nginx - this can be safely removed.
Also remove some other stuff related to systemd that aren't required anymore.
This was done by design previously - to fix an issue with RHEL not allowing running crontab as the current user - but is no longer necessary with the removal of non-Debian platform support.
The newer version is pulled by something in k3s and somehow is - probably through workspace magic - pulled into the config plugin tests. We pin to the older version since parsing changed at some point, which will cause issues for users.
A future update should move this to the latest version and cause a BC break, but for now lets pin as expected.
In most cases, it should be there, but it appears that system upgrades from Ubuntu 16.04 sometimes do not have usr-merge setup. As such, we need to fallback to the /bin/systemctl path if it exists.
This will avoid issues where a build or test will inadvertently update dependencies, causing drift between what is in code and what is being tested/run.
Rather than try to mount a directory into the container and use a symlink, directly mount the volume in.
Note that this requires deleting the task container prior to continuing in order to ensure the volume isn't still mounted prior to other tasks being executed.
The previous method used an ephemeral container, which was slightly more convoluted and required cleanup. The new method also allows us to set an initial WORKDIR, which is useful for ensuring 'docker exec' works as expected.
This doesn't make sense as a port can't be listened to twice on the same domain, so instead we should just fail immediately if someone attempts to perform this action.
Refs dokku/dokku-letsencrypt#269
Dokku uses a few external images for various bits of functionality, but these must be manually updated every so often due to being referenced in code.
By moving the references to Dockerfiles, we can take advantage of dependabot to issue automatic PRs when they are out of date.
# History
## 0.33.7
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.33.7/bootstrap.sh
sudo DOKKU_TAG=v0.33.7 bash bootstrap.sh
```
### Bug Fixes
- #6608: @josegonzalez Fix issue with setting k3s resource values and lower the initial default values
- #6607: @josegonzalez Call sed in unbuffered form to ensure log output is streamed to stdout
- #6600: @josegonzalez Use correct label key for worker nodes
- #6593: @josegonzalez Remove extra trailing newline to fix govet issue
### New Features
- #6595: @josegonzalez Add ability for users to specify alternative kubeconfig and kubecontext
### Refactors
- #6594: @josegonzalez Remove all calls to common.NewShellCmd
- #6592: @josegonzalez Remove all calls to common.NewShellCmdWithArgs
- #6591: @josegonzalez Always capture stdout/stderr when executing subprocesses
- #6590: @josegonzalez Remove all direct usage of go-sh outside of plugin trigger setup
### Dependencies
- #6609: @dependabot[bot] chore(deps): bump google.golang.org/grpc from 1.61.1 to 1.62.0 in /tests/apps/gogrpc
- #6604: @dependabot[bot] chore(deps): bump mkdocs-material from 9.5.9 to 9.5.10 in /docs/_build
- #6603: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 42.0.2 to 42.0.4
- #6601: @dependabot[bot] chore(deps): bump helm.sh/helm/v3 from 3.13.3 to 3.14.1 in /plugins/scheduler-k3s
- #6596: @dependabot[bot] chore(deps): bump google.golang.org/grpc from 1.61.0 to 1.61.1 in /tests/apps/gogrpc
This will provide the possibility for users to talk to existing kubernetes clusters, thereby removing one of the biggest reasons for having the old scheduler-kubernetes plugin around.
The new exec callers somehow setup the environment differently, causing sed to not properly detect that it should run in unbuffered form. This change forces sed to run in unbuffered mode.
Closes#6602
This is almost certainly the correct default for Dokku. While it's a BC break and might cause an increase in memory usage, the api is mostly internal and therefore this is safe to use.
# History
## 0.33.6
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.33.6/bootstrap.sh
sudo DOKKU_TAG=v0.33.6 bash bootstrap.sh
```
### Bug Fixes
- #6589: @josegonzalez Use image pull secrets instead of registries.yaml to reference private repositories when deploying via k3s
- #6581: @josegonzalez Fix issues in tls handling when deploying via k3s
- #6582: @josegonzalez Correctly handle extra whitespace in scale file contents
- #6390: @renweibo Prefer systemctl over sv when both exist while restarting nginx
- #6579: @josegonzalez Ensure k3s can be installed with taints
### New Features
- #6585: @josegonzalez Add more context to errors in fetching cron entries
- #6583: @josegonzalez Add WithContext functions for all subprocess-related code
### Refactors
- #6584: @josegonzalez Use new CallExecCommand when checking to see how help is being called
### Dependencies
- #6586: @dependabot[bot] chore(deps): bump mvdan.cc/sh/v3 from 3.7.0 to 3.8.0 in /plugins/cron
- #6587: @dependabot[bot] chore(deps): bump mkdocs-material from 9.5.8 to 9.5.9 in /docs/_build
- #6381: @dependabot[bot] chore(deps): bump actions/upload-artifact from 3 to 4
- #6578: @josegonzalez Bump go modules
### Other
- #6576: @Tashows Allow creating a detached container with TTY enabled for attaching remote terminal
While this will now more or less require a local docker login - which can be overridden by setting the image-pull-secrets property - this ensures every deploy has a valid context.
One annoying thing is that the secret is per-app vs global, meaning that if the secret must be rotated, all apps need to be redeployed. A future change can fix that by deploying a global secret, or if folks really desire, this can be done by setting the image-pull-secrets property on the app/globally.
# History
## 0.33.5
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.33.5/bootstrap.sh
sudo DOKKU_TAG=v0.33.5 bash bootstrap.sh
```
### Bug Fixes
- #6574: @josegonzalez Correct indentation when configuring https on a k3s app
### Documentation
- #6575: @josegonzalez Remove reference to web ui from digitalocean install documentation
### Dependencies
- #6573: @dependabot[bot] chore(deps): bump golang from 1.21.6 to 1.22.0 in /tests/apps/go-fail-postdeploy
- #6569: @dependabot[bot] chore(deps): bump golang from 1.21.6 to 1.22.0 in /tests/apps/go-fail-predeploy
- #6570: @dependabot[bot] chore(deps): bump golang.org/x/crypto from 0.18.0 to 0.19.0 in /plugins/common
- #6571: @dependabot[bot] chore(deps): bump golang from 1.21.6 to 1.22.0 in /tests/apps/zombies-dockerfile-tini
- #6572: @dependabot[bot] chore(deps): bump python from 3.12.1-alpine to 3.12.2-alpine in /docs/_build
# History
## 0.33.4
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.33.4/bootstrap.sh
sudo DOKKU_TAG=v0.33.4 bash bootstrap.sh
```
### Bug Fixes
- #6564: @josegonzalez Ignore link and volume flags for nixpacks builds
- #6563: @josegonzalez Wait until initial k3s node is ready before installing manifests
- #6561: @josegonzalez Index the process map to ensure the correct config is pulled
- #6560: @josegonzalez Skip app stop/delete when k3s is not installed
- #6559: @josegonzalez Check errors when writing properties
- #6556: @josegonzalez Respect the release namespace when creating resources for a k3s deploy
### New Features
- #6562: @josegonzalez Add support for specifying annotations on kubernetes resources
- #6555: @josegonzalez Add support for app-specific service accounts when deploying via k3s
- #6546: @josegonzalez Install kubectx and kubens helper binaries when setting up a k3s cluster
### Refactors
- #6558: @josegonzalez Use type-specific functions for writing contents to a file
- #6557: @josegonzalez Consolidate property fetching for nginx plugin into golang codebase
- #6536: @josegonzalez Manage vector container via compose
### Documentation
- #6545: @josegonzalez Migrate markdown doc rewriting into mkdocs hooks
### Tests
- #6554: @josegonzalez Fix issue where CI cannot install docker-buildx-plugin
### Dependencies
- #6568: @dependabot[bot] chore(deps): bump golang from 1.21.6 to 1.22.0 in /tests/apps/gogrpc
- #6567: @dependabot[bot] chore(deps): bump watchdog from 3.0.0 to 4.0.0 in /docs/_build
- #6566: @dependabot[bot] chore(deps): bump mkdocs-material from 9.5.7 to 9.5.8 in /docs/_build
- #6565: @dependabot[bot] chore(deps): bump golang from 1.21.6 to 1.22.0 in /tests/apps/zombies-dockerfile-no-tini
- #6551: @dependabot[bot] chore(deps): bump flask from 3.0.1 to 3.0.2 in /tests/apps/multi
- #6552: @dependabot[bot] chore(deps): bump mkdocs-material from 9.5.6 to 9.5.7 in /docs/_build
- #6553: @dependabot[bot] chore(deps): bump markupsafe from 2.1.4 to 2.1.5 in /docs/_build
- #6550: @dependabot[bot] chore(deps): bump flask from 3.0.1 to 3.0.2 in /tests/apps/python-flask
- #6548: @dependabot[bot] chore(deps): bump org.eclipse.jetty:jetty-servlet from 11.0.19 to 11.0.20 in /tests/apps/java
### Other
- #6547: @josegonzalez Add support for nginx as a k3s ingress implementation
# History
## 0.33.3
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.33.3/bootstrap.sh
sudo DOKKU_TAG=v0.33.3 bash bootstrap.sh
```
### Bug Fixes
- #6542: @josegonzalez Drop -- when calling dokku run for cron-tab templating
### Documentation
- #6543: @josegonzalez Add support for badge shortcodes in documentation
# History
## 0.33.2
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.33.2/bootstrap.sh
sudo DOKKU_TAG=v0.33.2 bash bootstrap.sh
```
### Bug Fixes
- #6535: @josegonzalez Properly fetch default vector image if none is passed
- #6533: @josegonzalez Ensure all k3s traefik middleware resources are scoped to the process
- #6524: @josegonzalez Ensure all copied files always have line endings converted to unix-style
### New Features
- #6537: @josegonzalez Add the dokku logo as the chart icon
- #6527: @josegonzalez Upgrade vector image to 0.35.x
- #6534: @josegonzalez Allow specifying an ingress class via chart value
### Documentation
- #6530: @josegonzalez Fix indentation on letsencrypt sections for k3s scheduler docs
### Tests
- #6532: @josegonzalez Correct issues in tests for vector image log property
### Dependencies
- #6540: @dependabot[bot] chore(deps): bump mkdocs-material from 9.5.5 to 9.5.6 in /docs/_build
- #6538: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 42.0.1 to 42.0.2
- #6528: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 42.0.0 to 42.0.1
- #6529: @dependabot[bot] chore(deps): bump google.golang.org/protobuf from 1.31.0 to 1.32.0 in /tests/apps/gogrpc
### Other
- #6526: @josegonzalez Allow setting the vector image as a global property
Using compose instead of manual docker calls allows folks to customize the vector container by using a custom compose.yml template file. This opens us up to more customizations while aligning container management with how we do other external containers (such as for the proxy plugins).
Refs #5784
# History
## 0.33.0
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.33.0/bootstrap.sh
sudo DOKKU_TAG=v0.33.0 bash bootstrap.sh
```
### Bug Fixes
- #6466: @josegonzalez Use correct key for migrating global scheduler configuration on upgrade
- #6450: @josegonzalez Always set -- on docker run commands internally to avoid parsing flags on specified commands
- #6447: @josegonzalez Propagate arm64 build support for development builds
- #6445: @josegonzalez Do not strip whitespace when displaying a file for debugging purposes
- #6442: @josegonzalez Ignore go.work when bumping modules
- #6427: @josegonzalez Add missing gitignore entry for app-json trigger
### New Features
- #6500: @josegonzalez Add support for custom user namespaces when creating persistent storage directories
- #6492: @josegonzalez Add support for multierror when exiting triggers
- #6491: @josegonzalez Add wrappers for exec and ssh commands
- #6489: @josegonzalez Disable flag parsing for dokku enter
- #6469: @josegonzalez Allow generating an ssh deploy key via the git plugin
- #6468: @josegonzalez Implement global support for setting proxy type
- #6467: @josegonzalez Add ability to customize the registry repo with a template
- #6464: @josegonzalez Create helper function for exposing a docker image's working directory
- #6462: @josegonzalez Ensure ps:stop has a proper cli header
- #6460: @josegonzalez Add a post-registry-login trigger
- #6459: @josegonzalez Alias common registry names to docker.io
- #6457: @josegonzalez Add the ability to specify the output format when listing ports
- #6452: @josegonzalez Add alternative implementation for calling plugin triggers
- #6446: @josegonzalez Add support for global-only environment properties
- #6443: @josegonzalez Add support for exposing healthchecks in the AppJson struct
- #6435: @josegonzalez Implement native k3s scheduler support
- #6433: @josegonzalez Add go.work.sum to gitignore
- #6432: @josegonzalez Upgrade golang to 1.21.6
- #6430: @josegonzalez Reformat devcontainer file
- #6428: @josegonzalez Add ms-azuretools.vscode-docker to devcontainer setup
- #6313: @josegonzalez Set the platform flag in order to run amd64 images on arm64 deploy targets
### Refactors
- #6448: @josegonzalez Return an int32 for scale count
- #6444: @josegonzalez Allow setting a custom mode when writing a slice to a file
### Documentation
- #6517: @josegonzalez Remove k3s tutorial from documentation
- #6516: @josegonzalez Note that the external kubernetes plugin is deprecated
- #6515: @josegonzalez Replace the kubernetes plugin with k3s in the documentation
- #6514: @josegonzalez Add notes on k3s replacement of the scheduler-kubernetes plugin
- #6461: @josegonzalez Add documentation for implementing scheduler-related commands
- #6458: @josegonzalez Add docblocks to appjson structs
- #6420: @aochagavia Fix typo in zero downtime documentation
### Tests
- #6465: @josegonzalez Update haproxy tests so they pass
- #6449: @josegonzalez Run ci on ubuntu 22.04
- #6431: @josegonzalez Add golanglint-ci testing support
### Dependencies
- #6513: @dependabot[bot] chore(deps): bump github.com/containerd/containerd from 1.7.6 to 1.7.11 in /plugins/scheduler-k3s
- #6512: @josegonzalez Update github.com/gonsi/gomega golang dependency
- #6511: @josegonzalez Update crypto and sys golang dependencies
- #6494: @dependabot[bot] chore(deps): bump markupsafe from 2.1.3 to 2.1.4 in /docs/_build
- #6482: @dependabot[bot] chore(deps): bump mkdocs-material from 9.5.3 to 9.5.4 in /docs/_build
- #6478: @dependabot[bot] chore(deps): bump golang from 1.21.5 to 1.21.6 in /tests/apps/zombies-dockerfile-tini
- #6456: @dependabot[bot] chore(deps): bump google.golang.org/grpc from 1.29.1 to 1.60.1 in /tests/apps/gogrpc
- #6454: @dependabot[bot] chore(deps): bump flask from 3.0.0 to 3.0.1 in /tests/apps/python-flask
- #6455: @dependabot[bot] chore(deps): bump flask from 3.0.0 to 3.0.1 in /tests/apps/multi
- #6453: @josegonzalez Remove ignored dependency from dependabot
- #6451: @josegonzalez Update go modules
- #6439: @dependabot[bot] chore(deps): bump github.com/onsi/gomega from 1.30.0 to 1.31.0 in /plugins/config
- #6438: @dependabot[bot] chore(deps): bump github.com/onsi/gomega from 1.30.0 to 1.31.0 in /plugins/common
- #6437: @dependabot[bot] chore(deps): bump beautifulsoup4 from 4.12.2 to 4.12.3 in /docs/_build
- #6436: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 41.1.1 to 42.0.0
- #6425: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 41.0.1 to 41.1.1
- #6424: @dependabot[bot] chore(deps): bump mkdocs-material from 9.5.3 to 9.5.4 in /docs/_build
- #6421: @josegonzalez chore: bump golang.org/x/sync from 0.5.0 to 0.6.0
- #6419: @dependabot[bot] chore(deps): bump jinja2 from 3.1.2 to 3.1.3 in /docs/_build
- #6418: @dependabot[bot] chore(deps): bump jinja2 from 3.1.2 to 3.1.3 in /tests/apps/python-flask
- #6415: @dependabot[bot] chore(deps): bump golang from 1.21.5 to 1.21.6 in /tests/apps/go-fail-postdeploy
- #6414: @dependabot[bot] chore(deps): bump golang from 1.21.5 to 1.21.6 in /tests/apps/gogrpc
- #6413: @dependabot[bot] chore(deps): bump golang from 1.21.5 to 1.21.6 in /tests/apps/go-fail-predeploy
- #6412: @dependabot[bot] chore(deps): bump golang from 1.21.5 to 1.21.6 in /tests/apps/zombies-dockerfile-no-tini
- #6411: @dependabot[bot] chore(deps): bump golang from 1.21.5 to 1.21.6 in /tests/apps/zombies-dockerfile-tini
- #6410: @dependabot[bot] chore(deps): bump golang.org/x/net from 0.19.0 to 0.20.0 in /tests/apps/gogrpc
- #6406: @dependabot[bot] chore(deps): bump golang.org/x/sync from 0.5.0 to 0.6.0 in /plugins/scheduler-docker-local
### Other
- #6463: @josegonzalez Use exported function from appjson module instead of manually parsing
- #6429: @josegonzalez Use go.work for development purposes
The previous mechanism of constructing the helm chart was pretty obnoxious due to needing to have some things in the object and some in template files that were appended afterwards. This change simplifies that by using template files per type with minimal replacements.
The idea here is that only k3s nodes can/should handle certificate requests. While users may wish to force these onto dedicated lb nodes in the future, at least for now, separating app workloads with routing seems like an okay trade-off.
Different options get applied to each depending on what is needed for the role.
This also updates how we initialize the cluster to better support how metrics exposure and cross-server networking.
The cron id is too long to store in the cronjob, so we generate a short identifier and look that up each time on deploy to ensure stability across time.
This utilizes a Kubernetes Job to start a pod in order to take advantage of completed Job cleanup in Kubernetes. It also properly handles interactivity by ensuring the container has a TTY.
Note that there is currently no provision for parsing docker arguments and translating them into their Kubernetes equivalents.
The big feature missing from deployments today is healthchecks, which require extra parsing of the app.json format since the healthchecks there aren't immediately serializable to kubernetes deployment healthchecks.
Other smaller missing functionality from the existing OSS kubernetes scheduler are:
- The ability to set custom pod annotations
- The ability to set custom deployment annotations
- The ability to mount volumes
Exposing these pieces of functionality will come at a later date, if at all.
While this might not seem super intuitive, the key is mostly related to git management, not the ssh-keys we currently use to add/remove access to push to dokku.
# History
## 0.32.4
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.32.4/bootstrap.sh
sudo DOKKU_TAG=v0.32.4 bash bootstrap.sh
```
### Bug Fixes
- #6407: @josegonzalez Upgrade ruby to fix the release process
- #6394: @josegonzalez Scope the delete of symlinked plugins in debian post-install to the plugin folders
### Refactors
- #6388: @Juneezee Replace deprecated `io/ioutil` functions
### Documentation
- #6385: @josegonzalez Fix docblock entries for properties in plugins
- #6384: @josegonzalez Cleanup some markdown in documentation
- #6365: @josegonzalez Split out archive/image deployment docs into their own file
### Tests
- #6408: @josegonzalez Add options to the release workflow
- #6359: @josegonzalez Update buildpack api for test buildpack
### Dependencies
- #6399: @dependabot[bot] chore(deps): bump pymdown-extensions from 10.5 to 10.7 in /docs/_build
- #6398: @dependabot[bot] chore(deps): bump sinatra from 3.1.0 to 3.2.0 in /tests/apps/ruby
- #6395: @dependabot[bot] chore(deps): bump ruby from 3.2.2 to 3.3.0 in /tests/apps/dockerfile-entrypoint
- #6391: @dependabot[bot] chore(deps): bump mkdocs-material from 9.5.2 to 9.5.3 in /docs/_build
- #6392: @dependabot[bot] chore(deps): bump importlib-metadata from 7.0.0 to 7.0.1 in /docs/_build
- #6393: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 40.2.3 to 41.0.1
- #6387: @dependabot[bot] chore(deps): bump org.eclipse.jetty:jetty-servlet from 11.0.18 to 11.0.19 in /tests/apps/java
- #6386: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 40.2.2 to 40.2.3
- #6377: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 40.2.1 to 40.2.2
- #6380: @dependabot[bot] chore(deps): bump github/codeql-action from 2 to 3
- #6379: @dependabot[bot] chore(deps): bump mkdocs-material from 9.5.1 to 9.5.2 in /docs/_build
- #6378: @dependabot[bot] chore(deps): bump python from 3.12.0-alpine to 3.12.1-alpine in /docs/_build
- #6376: @dependabot[bot] chore(deps): bump mkdocs-material from 9.4.14 to 9.5.1 in /docs/_build
- #6371: @dependabot[bot] chore(deps): bump golang from 1.21.4 to 1.21.5 in /tests/apps/gogrpc
- #6369: @dependabot[bot] chore(deps): bump golang from 1.21.4 to 1.21.5 in /tests/apps/zombies-dockerfile-tini
- #6368: @dependabot[bot] chore(deps): bump golang from 1.21.4 to 1.21.5 in /tests/apps/zombies-dockerfile-no-tini
- #6367: @dependabot[bot] chore(deps): bump importlib-metadata from 6.8.0 to 7.0.0 in /docs/_build
- #6366: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 40.2.0 to 40.2.1
- #6370: @dependabot[bot] chore(deps): bump golang from 1.21.4 to 1.21.5 in /tests/apps/go-fail-predeploy
- #6372: @dependabot[bot] chore(deps): bump golang from 1.21.4 to 1.21.5 in /tests/apps/go-fail-postdeploy
- #6373: @dependabot[bot] chore(deps): bump actions/setup-python from 4 to 5
- #6364: @dependabot[bot] chore(deps): bump golang.org/x/net from 0.18.0 to 0.19.0 in /tests/apps/gogrpc
- #6361: @dependabot[bot] chore(deps): bump pymdown-extensions from 10.4 to 10.5 in /docs/_build
- #6362: @dependabot[bot] chore(deps): bump mkdocs-material from 9.4.12 to 9.4.14 in /docs/_build
- #6360: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 40.1.1 to 40.2.0
- #6357: @dependabot[bot] chore(deps): bump mkdocs-material-extensions from 1.3 to 1.3.1 in /docs/_build
- #6355: @dependabot[bot] chore(deps): bump pygments from 2.16.1 to 2.17.2 in /docs/_build
- #6358: @dependabot[bot] chore(deps): bump mkdocs-material from 9.4.8 to 9.4.12 in /docs/_build
- #6348: @dependabot[bot] chore(deps): bump pymdown-extensions from 10.3.1 to 10.4 in /docs/_build
Previously, we would try and traverse the entire dokku lib directory, causing extremely slow updates for installations with lots of data. This would also potentially cause issues for anyone using symlinks in their data directories.
Instead, just remove symlinks in the plugin directories.
The io/ioutil package has been deprecated as of Go 1.16 [1]. This commit
replaces the existing io/ioutil functions with their new definitions in
io and os packages.
[1]: https://golang.org/doc/go1.16#ioutil
Signed-off-by: Eng Zer Jun <engzerjun@gmail.com>
# History
## 0.32.3
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.32.3/bootstrap.sh
sudo DOKKU_TAG=v0.32.3 bash bootstrap.sh
```
### Bug Fixes
- #6345: @josegonzalez Use updated pre-build trigger for builder-herokuish
### New Features
- #6346: @josegonzalez Update all go modules and add a command to bump modules
### Documentation
- #6339: @nschlemm Fixed link to vector sink documentation
- #6314: @josegonzalez Remove reference to DOKKU_SCHEDULER environment variable in favor of scheduler:set
- #6317: @edmorley Replace deprecated builder reference in persistent-storage.md
- #6325: @josegonzalez Add documentation on openresty includes
### Dependencies
- #6343: @dependabot[bot] chore(deps): bump golang.org/x/net from 0.17.0 to 0.18.0 in /tests/apps/gogrpc
- #6338: @dependabot[bot] chore(deps): bump golang from 1.21.3 to 1.21.4 in /tests/apps/go-fail-postdeploy
- #6337: @dependabot[bot] chore(deps): bump golang from 1.21.3 to 1.21.4 in /tests/apps/gogrpc
- #6336: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 40.0.2 to 40.1.1
- #6335: @dependabot[bot] chore(deps): bump golang from 1.21.3 to 1.21.4 in /tests/apps/go-fail-predeploy
- #6334: @dependabot[bot] chore(deps): bump golang from 1.21.3 to 1.21.4 in /tests/apps/zombies-dockerfile-tini
- #6333: @dependabot[bot] chore(deps): bump golang from 1.21.3 to 1.21.4 in /tests/apps/zombies-dockerfile-no-tini
- #6328: @dependabot[bot] chore(deps): bump mkdocs-material from 9.4.7 to 9.4.8 in /docs/_build
- #6320: @dependabot[bot] chore(deps): bump org.eclipse.jetty:jetty-servlet from 11.0.17 to 11.0.18 in /tests/apps/java
- #6318: @dependabot[bot] chore(deps): bump mkdocs-material from 9.4.6 to 9.4.7 in /docs/_build
- #6322: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 40.0.0 to 40.0.2
- #6323: @dependabot[bot] chore(deps): bump django from 4.1.10 to 4.1.13 in /tests/apps/dockerfile-release
### Other
- #6315: @josegonzalez Correct key in dependency file to fix docker-container-healthchecker installs on local arm64 servers
# History
## 0.32.1
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.32.1/bootstrap.sh
sudo DOKKU_TAG=v0.32.1 bash bootstrap.sh
```
### Bug Fixes
- #6286: @josegonzalez Remove trailing quote on openresty letsencrypt email
- #6287: @josegonzalez Recursively delete old custom openresty includes
### New Features
- #6303: @josegonzalez feat: add the ability to specify location-block includes
### Documentation
- #6288: @josegonzalez Add missing link to nixpacks builder
### Dependencies
- #6306: @dependabot[bot] chore(deps): bump org.apache.maven.plugins:maven-dependency-plugin from 3.6.0 to 3.6.1 in /tests/apps/java
- #6301: @dependabot[bot] chore(deps): bump github.com/onsi/gomega from 1.28.0 to 1.28.1 in /plugins/config
- #6304: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 39.2.3 to 39.2.4
- #6305: @dependabot[bot] chore(deps): bump actions/setup-node from 3 to 4
- #6297: @dependabot[bot] chore(deps): bump node from 20-alpine to 21-alpine in /tests/apps/dockerfile-procfile
- #6292: @dependabot[bot] chore(deps): bump node from 20-alpine to 21-alpine in /tests/apps/dockerfile-procfile-bad
- #6293: @dependabot[bot] chore(deps): bump node from 20-alpine to 21-alpine in /tests/apps/dockerfile
- #6294: @dependabot[bot] chore(deps): bump pymdown-extensions from 10.3 to 10.3.1 in /docs/_build
- #6295: @dependabot[bot] chore(deps): bump node from 20-alpine to 21-alpine in /tests/apps/dockerfile-app-json-formations
- #6296: @dependabot[bot] chore(deps): bump node from 20-alpine to 21-alpine in /tests/apps/dockerfile-noexpose
- #6289: @dependabot[bot] chore(deps): bump mkdocs-material-extensions from 1.2 to 1.3 in /docs/_build
- #6290: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 39.2.2 to 39.2.3
# History
## 0.32.0
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.32.0/bootstrap.sh
sudo DOKKU_TAG=v0.32.0 bash bootstrap.sh
```
See the [0.32.0 migration guide](/docs/appendices/0.32.0-migration-guide.md) for more information on migrating to 0.32.0.
### New Features
- #6277: @josegonzalez Run ps:restore in parallel by default
- #6276: @josegonzalez Warn when incorrect interface/port in use for web processes
- #6132: @josegonzalez Add the ability to specify a custom mailto for all cron output
- #6124: @josegonzalez Add a shell function to check if a plugin trigger exists
- #5348: @josegonzalez Add nixpacks builder support
### Removals
- #6283: @josegonzalez Remove deprecated proxy-ports functions and and plugin subcommands
### Deprecations
- #6127: @josegonzalez Deprecate the builder-specific pre-release-* triggers in favor of a global pre-release-builder trigger
- #6126: @josegonzalez Deprecate the builder-specific post-build-* triggers in favor of a global post-build trigger
- #6125: @josegonzalez Deprecate the builder-specific pre-build-* triggers in favor of a global pre-build trigger
### Documentation
- #6284: @josegonzalez Document future removal of deprecated CHECKS file format
- #6123: @josegonzalez Add a migration guide for 0.32.x
### Dependencies
- #6285: @dependabot[bot] chore(deps): bump mkdocs-material from 9.4.5 to 9.4.6 in /docs/_build
- #6281: @josegonzalez Upgrade golang to 1.21
### Other
- #6155: @josegonzalez Remove ARM support
Users that misconfigure their process's listening interface or port will now see an additional healthcheck warning for web deploys. While only a single port is checked, this ensures that users at least have some context as to why their app isn't responding as expected.
Closes#4798
This will speed up restores in cases where app containers disappear on reboot or have new IPs, which primarily impacts the docker-local scheduler in conjunction with nginx.
Closes#4967
Building/testing for ARM does not happen often - the only runtime environment is Raspberry PI, which supports ARM64 - and complicates support for a ton of features. Aside from that, CI runs are much longer for ARM Dokku images, often reaching 15-20 minutes or just timing out completely.
Rather than support an architecture that doesn't have much usage by maintainers and has a lot of maintenance burden, we're removing the platform.
# History
## 0.31.5
Install/update via the bootstrap script:
```shell
wget -NP . https://dokku.com/install/v0.31.5/bootstrap.sh
sudo DOKKU_TAG=v0.31.5 bash bootstrap.sh
```
### Bug Fixes
- #6275: @josegonzalez Update message referencing CHECKS file usage to app.json
- #6273: @josegonzalez Clean up local build images immediately after an image is released
### New Features
- #6274: @josegonzalez Add more version output to dokku report command
- #6255: @josegonzalez Add ci concurrency to linting workflow
- #6253: @josegonzalez Add ci concurrency to doc building
- #6254: @josegonzalez Add ci concurrency to codeql analysis
- #6222: @josegonzalez Install docker-buildx-plugin to silence buildx warnings
### Refactors
- #6257: @josegonzalez Manage Dokku system dependencies in a single file
### Documentation
- #6271: @josegonzalez Update list of official, community, and deprecated plugins
- #6224: @joeyates Correct typo in example app.json for healthchecks
- #6207: @AlejandroAkbal Update port clearing command in Dockerfile deploy documentation
### Tests
- #6278: @josegonzalez Remove pack installation from builder-lambda tests
### Dependencies
- #6269: @dependabot[bot] chore(deps): bump golang.org/x/net from 0.14.0 to 0.17.0 in /plugins/common
- #6270: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 39.2.1 to 39.2.2
- #6262: @dependabot[bot] chore(deps): bump golang from 1.21.2 to 1.21.3 in /tests/apps/zombies-dockerfile-no-tini
- #6263: @dependabot[bot] chore(deps): bump golang.org/x/net from 0.16.0 to 0.17.0 in /tests/apps/gogrpc
- #6264: @dependabot[bot] chore(deps): bump golang from 1.21.2 to 1.21.3 in /tests/apps/zombies-dockerfile-tini
- #6265: @dependabot[bot] chore(deps): bump golang from 1.21.2 to 1.21.3 in /tests/apps/go-fail-predeploy
- #6259: @dependabot[bot] chore(deps): bump org.eclipse.jetty:jetty-servlet from 11.0.16 to 11.0.17 in /tests/apps/java
- #6260: @dependabot[bot] chore(deps): bump mkdocs-material from 9.4.4 to 9.4.5 in /docs/_build
- #6261: @dependabot[bot] chore(deps): bump golang from 1.21.2 to 1.21.3 in /tests/apps/gogrpc
- #6266: @dependabot[bot] chore(deps): bump golang from 1.21.2 to 1.21.3 in /tests/apps/go-fail-postdeploy
- #6258: @dependabot[bot] chore(deps): update markdown requirement from <3.5,>=3.2.1 to >=3.2.1,<3.6 in /docs/_build
- #6256: @josegonzalez chore: bump github.com/otiai10/copy and golang.org/x/sync
- #6241: @dependabot[bot] chore(deps): bump python from 3.11.5-alpine to 3.12.0-alpine in /docs/_build
- #6252: @dependabot[bot] chore(deps): bump mkdocs-material from 9.4.2 to 9.4.4 in /docs/_build
- #6235: @dependabot[bot] chore(deps): bump packaging from 23.1 to 23.2 in /docs/_build
- #6232: @dependabot[bot] chore(deps): bump werkzeug from 2.3.7 to 3.0.0 in /tests/apps/python-flask
- #6231: @dependabot[bot] chore(deps): bump flask from 2.3.3 to 3.0.0 in /tests/apps/python-flask
- #6248: @dependabot[bot] chore(deps): bump golang from 1.21.1 to 1.21.2 in /tests/apps/gogrpc
- #6251: @dependabot[bot] chore(deps): bump golang from 1.21.1 to 1.21.2 in /tests/apps/zombies-dockerfile-tini
- #6250: @dependabot[bot] chore(deps): bump golang.org/x/net from 0.15.0 to 0.16.0 in /tests/apps/gogrpc
- #6249: @dependabot[bot] chore(deps): bump golang from 1.21.1 to 1.21.2 in /tests/apps/go-fail-predeploy
- #6247: @dependabot[bot] chore(deps): bump golang from 1.21.1 to 1.21.2 in /tests/apps/zombies-dockerfile-no-tini
- #6246: @dependabot[bot] chore(deps): bump golang from 1.21.1 to 1.21.2 in /tests/apps/go-fail-postdeploy
- #6245: @dependabot[bot] chore(deps): bump golang.org/x/sync from 0.3.0 to 0.4.0 in /plugins/scheduler-docker-local
- #6233: @dependabot[bot] chore(deps): bump flask from 2.3.3 to 3.0.0 in /tests/apps/multi
- #6239: @dependabot[bot] chore(deps): bump github.com/otiai10/copy from 1.12.0 to 1.14.0 in /plugins/ps
- #6234: @dependabot[bot] chore(deps): bump github.com/otiai10/copy from 1.12.0 to 1.14.0 in /plugins/builder
- #6240: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 39.2.0 to 39.2.1
- #6228: @josegonzalez Update all go modules and ensure all are tracked in dependabot
- #6227: @dependabot[bot] chore(deps): bump github.com/onsi/gomega from 1.27.10 to 1.28.0 in /plugins/common
- #6216: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 39.1.2 to 39.2.0
- #6217: @dependabot[bot] chore(deps): bump mkdocs-material from 9.4.1 to 9.4.2 in /docs/_build
- #6215: @dependabot[bot] chore(deps): bump mkdocs-material from 9.3.1 to 9.4.1 in /docs/_build
- #6214: @dependabot[bot] chore(deps): bump mkdocs-material-extensions from 1.1.1 to 1.2 in /docs/_build
- #6209: @dependabot[bot] chore(deps): bump zipp from 3.16.2 to 3.17.0 in /docs/_build
- #6211: @dependabot[bot] chore(deps): bump mkdocs from 1.5.2 to 1.5.3 in /docs/_build
- #6213: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 39.0.2 to 39.1.2
- #6202: @dependabot[bot] chore(deps): bump docker/setup-buildx-action from 2 to 3
- #6199: @dependabot[bot] chore(deps): bump docker/login-action from 2 to 3
- #6200: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 39.0.0 to 39.0.2
- #6201: @dependabot[bot] chore(deps): bump docker/setup-qemu-action from 2 to 3
- #6203: @dependabot[bot] chore(deps): bump mkdocs-material from 9.2.8 to 9.3.1 in /docs/_build
In some cases, we might hold onto intermediate images until the next deploy. While these images are generally part of newer images - and are therefore cleaned up when the child images are no longer in use - they cruft up the 'docker image ls' output, causing some folks to believe Dokku is not cleaning up images.
Refs #6272
This will allow us to more quickly update a dependency by adding support so that downstream repos can auto-push updates to the main repo when there is a release.
Consider [sponsoring Dokku](https://github.com/sponsors/dokku). Sponsorship goes directly to supporting activities such as fixing bugs and general maintenance.
- type:input
id:docs-link
attributes:
label:Link to the documentation page
description:Which docs page is impacted?
- type:textarea
id:description
attributes:
label:Documentation problem
description:Describe what you think is incorrect, not well documented, or missing from the documentation
validations:
required:true
- type:textarea
id:report-output
attributes:
label:dokku report
description:Please paste the output of the command `dokku report` so we know what systems any issue might apply to
You can then proceed to configure your server domain (via `dokku domains:set-global`) and user access (via `dokku ssh-keys:add`) to complete the installation.
@@ -73,9 +73,11 @@ By default, permissions are set for usage with Herokuish buildpacks. These permi
-`--chown herokuish` (default): Use `32767:32767` as the folder permissions.
- This is used for apps deployed with Buildpacks via Herokuish.
-`--chown heroku`: Use `1000:1000` as the folder permissions.
- This is used for apps deployed with Cloud Native Buildpacks using the `heroku/buildpacks` builder.
- This is used for apps deployed with Cloud Native Buildpacks using the `heroku/builder` builder.
-`--chown packeto`: Use `2000:2000` as the folder permissions.
- This is used for apps deployed with Cloud Native Buildpacks using the `cloudfoundry/cnb` or `packeto` builders.
-`--chown root`: Use `0:0` as the folder permissions.
- This is used for containers that run their processes as root, as is typical for most Dockerfile or Docker image deploys.
-`--chown false`: Skips the `chown` call.
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.
Dokku uses a Golang template and has access to the `AppName` variable as shown above.
### Pushing images on build
To push the image on release, set the `push-on-release` property to `true` via the `registry:set` command. The default value for this property is `false`. Setting the property to `true` will result in the image being tagged with an ID that is incremented with every release. This tag will be what is used for running app code.
To push the image on release with extra tags, set the `push-extra-tags` to a comma-separated list of tags via the `registry:set` command. The default value for this property is empty. Setting the property will result in the image being tagged with extra tags every release.
This property can be set for a single app or globally via the `--global` flag. When set globally, the app-specific value will always overide the global value. The default global value for this property is `false`.
- The following `pre-build-*` plugin triggers have been deprecated and will be removed in the next release. Users should instead trigger the `pre-build` plugin trigger.
- pre-build-buildpack
- pre-build-dockerfile
- pre-build-lambda
- pre-build-pack
- The following `pre-release-*` plugin triggers have been deprecated and will be removed in the next release. Users should instead trigger the `pre-release-builder` plugin trigger.
- pre-release-buildpack
- pre-release-dockerfile
- pre-release-lambda
- pre-release-pack
- The following `post-build-*` plugin triggers have been deprecated and will be removed in the next release. Users should instead trigger the `post-build` plugin trigger.
- post-build-buildpack
- post-build-dockerfile
- post-build-lambda
- post-build-pack
- The `CHECKS` file was deprecated in the previous release in favor of defining healthchecks in the `app.json` file. It's support and auto-migration to healthchecks in the `app.json` file will be removed in the next release. See the [zero-downtime deploy documentation](/docs/deployment/zero-downtime-deploys.md) for more information on how the new zero downtime check format works.
## Removals
- ARM support has been removed. Users of ARM installations on platforms such as the Raspberry PI should consider migrating to ARM64. ARM64 will continue to be supported by Dokku, and there are no plans to remove support for ARM64.
- The following proxy-port related code has been removed. It is replaced by the `ports` plugin and it's related plugin triggers.
- The `disable-chown` property of the `scheduler-docker-local` plugin has been removed. Mounted paths will no longer have file permissions changed during the pre-deploy phase. Files baked into the container image for herokuish builds will always be owned by the correct user.
- The `git:unlock` command has been removed. It was previously used to "unlock" a temporary directory that already existed. The directory the `git:unlock` command used to cleanup is now properly removed on exit of the `git:from-image` command.
- The k3s plugin no longer supports port mappings other than `https:443` and `http:80`. If no matching port map is specified, Dokku will use expose the app on the first port mapping, with priority given to `https` mappings over `http`.
- Golang functions to invoke plugin triggers named `PlugnTrigger*` have been removed in favor of `CallPlugnTrigger`.
## Changes
- The k3s scheduler now creates an Ingress object per domain instead of one per port mapping. This will cause a short amount of downtime during the next app deploy after upgrading to 0.34.0
- App lock files have been removed from the `/home/dokku` directory and moved into the `data/apps` directory.
- Logs are now rotated via `copytruncate` instead of `create` in logrotate.
- The k3s scheduler now defaults to nginx as it's default proxy implementation. The traefik proxy implementation is still available, though users will need to set the global `ingress-class` k3s property to `traefik` via the following command:
<sup>1</sup> Extends app.json support to include creating volumes and creating / linking databases on push
<sup>1</sup> Adds the ability to sync an application repo with a remote GitHub repo (useful for automated rebuilds without needing a git push from an external system
<sup>2</sup> Adds SQLite replication to external object storage via [Litestream](https://litestream.io)
<sup>2</sup> Adds the ability to invoke a post-deploy webhook with the IP, port and app name, all with a single config:set).
<sup>3</sup> Adds the possibility to add SSH deployment keys to receive private hosted packages
<sup>3</sup> Extends app.json support to include creating volumes and creating / linking databases on push
<sup>4</sup> Adds the ability to add custom hosts to the containers known_hosts file to be able to ssh them easily (useful with deployment keys)
<sup>5</sup> Adds the ability to sync an application repo with a remote GitHub repo (useful for automated rebuilds without needing a git push from an external system
<sup>6</sup> Adds the ability to invoke a post-deploy webhook with the IP, port and app name, all with a single config:set).
<sup>4</sup> Adds SQLite replication to external object storage via [Litestream](https://litestream.io)
| [PostgreSQL (single container)](https://github.com/jeffutter/dokku-postgresql-plugin) | [jeffutter][] | This plugin creates a single postgresql container that all your apps can use. Thus only one instance of postgresql running (good for servers without a ton of memory). |
<sup>1</sup> Forked from [jezdez/dokku-elasticsearch-plugin](https://github.com/jezdez/dokku-elasticsearch-plugin): uses Elasticsearch 1.2 (instead of 0.90), doesn't depend on dokku-link, runs as elasticsearch user instead of root, and turns off multicast autodiscovery for use in a VPS environment.
@@ -255,6 +259,7 @@ The following plugins are no longer maintained by their developers.
@@ -27,10 +27,10 @@ Dokku will only select the `dockerfile` builder if both the `herokuish` and `pac
### Switching from buildpack deployments
If an application was previously deployed via buildpacks, the following commands should be run before a Dockerfile deploy will succeed:
If an application was previously deployed via buildpacks and ports were customized, the following commands should be run prior to a deploy to ensure the Dockerfile ports are respected:
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.
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 arm64 platforms.
To force-enable herokuish on non-amd64 platforms, the `allowed` property can be set via `builder-herokuish:set`. The default value depends on the host platform architecture (`true` on amd64, `false` otherwise).
The `nixpacks` builder builds apps via [Nixpacks](https://nixpacks.com/), a buildpack alternative.
## Usage
### Requirements
The `nixpacks` cli tool is not included by default with Dokku or as a dependency. It must also be installed as shown on [this page](https://nixpacks.com/docs/install#debian-(and-derivatives-like-ubuntu)).
Builds will proceed with the `nixpacks` cli for the app from then on.
### Detection
This builder will be auto-detected in the following case:
- A `nixpacks.toml` exists in the root of the app repository.
The builder may also be selected via the `builder:set` command
```shell
dokku builder:set node-js-app selected nixpacks
```
### Supported languages
See the [upstream nixpacks documentation](https://nixpacks.com/docs) for further information on what languages and frameworks are supported.
### Build-time configuration variables
For security reasons - and as per [Docker recommendations](https://github.com/docker/docker/issues/13490) - nixpacks-based deploys have variables available only during runtime.
For users that require customization in the `build` phase, you may use build arguments via the [docker-options plugin](/docs/advanced-usage/docker-options.md). All environment variables set by the `config` plugin are automatically exported within the nixpacks build environment, and thus `--env` only requires setting a key without a value.
When deploying a monorepo, it may be desirable to specify the specific path of the `nixpacks.toml` file to use for a given app. This can be done via the `builder-nixpacks:set` command. If a value is specified and that file does not exist in the app's build directory, then the build will fail.
The `nixpackstoml-path` property can also be set globally. The global default is `nixpacks.toml`, and the global value is used when no app-specific value is set.
The above command will show logs continually from the vector container, with an initial history of 10 log lines
#### Changing the vector image
Dokku integrates with a Vector docker image version that is known to be compatible with the documentation. In some cases, it may be useful to specify an alternative image version. To do so, set the global `vector-image` property.
Once set, the vector container will need to be stopped and then started. Note that specifying the `--vector-image` flag on the `logs:vector-start` will override the setting.
```shell
dokku logs:vector-stop
dokku logs:vector-start
```
Setting this to an empty string will reset the version to the version currently compatible with the Dokku installation.
```shell
dokku logs:set --global vector-image
```
#### Configuring a log sink
Vector uses the concept of log "sinks" to send logs to a given endpoint. Log sinks may be configured globally or on a per-app basis by specifying a `vector-sink` in DSN form with the `logs:set` command. Specifying a sink value will reload any running vector container.
@@ -211,4 +232,4 @@ For some sinks - such as the `http` sink - it may be useful to use special chara
dokku logs:set test vector-sink "http://?uri=https%3A//loggerservice.com%3A1234/%3Ftoken%3Dabc1234%26type%3Dvector"
```
Please read the [sink documentation](https://vector.dev/docs/reference/sinks/) for your sink of choice to configure the sink as desired.
Please read the [sink documentation](https://vector.dev/docs/reference/configuration/sinks/) for your sink of choice to configure the sink as desired.
## 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.
In the above example, Dokku will build the app as if the repository contained the extracted contents of the specified archive file.
Triggering a build with the same archive file multiple times will result in Dokku exiting `0` early as there will be no changes detected.
The `git:from-archive` command can optionally take a git `user.name` and `user.email` argument (in that order) to customize the author. If the arguments are left empty, they will fallback to `Dokku` and `automated@dokku.sh`, respectively.
The default archive type is always set to `.tar`. To use a different archive type, specify the `--archive-type` flag. Failure to do so will result in a failure to extract the archive.
```shell
dokku git:from-archive --archive-type zip node-js-app https://github.com/dokku/smoke-test-app/archive/2.0.0.zip "Camila""camila@example.com"
```
Finally, if the archive url is specified as `--`, the archive will be fetched from stdin.
@@ -8,14 +8,14 @@ git:allow-host <host> # Adds a host to known_hosts
git:auth <host> [<username> <password>] # Configures netrc authentication for a given git server
git:from-archive [--archive-type ARCHIVE_TYPE] <app> <archive-url> [<git-username> <git-email>] # Updates an app's git repository with a given archive file
git:from-image [--build-dir DIRECTORY] <app> <docker-image> [<git-username> <git-email>] # Updates an app's git repository with a given docker image
git:generate-deploy-key # Generates a deploy ssh key
git:load-image [--build-dir DIRECTORY] <app> <docker-image> [<git-username> <git-email>] # Updates an app's git repository with a docker image loaded from stdin
git:sync [--build] <app> <repository> [<git-ref>] # Clone or fetch an app from remote git repo
git:sync [--build|build-if-changes] <app> <repository> [<git-ref>] # Clone or fetch an app from remote git repo
git:initialize <app> # Initialize a git repository for an app
git:public-key # Outputs the dokku public deploy key
git:report [<app>] [<flag>] # Displays a git report for one or more apps
git:set <app> <key> (<value>) # Set or clear a git property for an app
git:status <app> # Show the working tree status for an app
git:unlock <app> [--force] # Removes previous git clone folder for new deployment
```
Git-based deployment has been the traditional method of deploying applications in Dokku. As of v0.12.0, Dokku introduces a few ways to customize the experience of deploying via `git push`. A Git-based deployment currently supports building applications via:
Please keep in mind that setting `keep-git-dir` to `true` may result in unstaged changes shown within the built container due to the build process generating application changes within the built app directory.
### 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.
In the above example, Dokku will build the app as if the repository contained _only_ a `Dockerfile` with the following content:
```Dockerfile
FROMdokku/node-js-getting-started:latest
```
If the specified image already exists on the Dokku host, it will not be pulled again, though this behavior may be changed using [build phase docker-options](/docs/advanced-usage/docker-options.md).
Triggering a build with the same arguments multiple times will result in Dokku exiting `0` early as there will be no changes detected. If the image tag is reused but the underlying image is different, it is recommended to use the image digest instead of the tag. This can be retrieved via the following command:
The `git:from-image` command can optionally take a git `user.name` and `user.email` argument (in that order) to customize the author. If the arguments are left empty, they will fallback to `Dokku` and `automated@dokku.sh`, respectively.
If the image is a private image that requires a docker login to access, the `registry:login` command should be used to log into the registry. See the [registry documentation](/docs/advanced-usage/registry-management.md#logging-into-a-registry) for more details on this process.
Finally, certain images may require a custom build context in order for `ONBUILD ADD` and `ONBUILD COPY` statements to succeed. A custom build context can be specified via the `--build-dir` flag. All files in the specified `build-dir` will be copied into the repository for use within the `docker build` process. The build context _must_ be specified on each deploy, and is not otherwise persisted between builds.
See the [dockerfile documentation](/docs/deployment/builders/dockerfiles.md) to learn about the different ways to configure Dockerfile-based deploys.
### 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.
In the above example, Dokku will build the app as if the repository contained the extracted contents of the specified archive file.
Triggering a build with the same archive file multiple times will result in Dokku exiting `0` early as there will be no changes detected.
The `git:from-archive` command can optionally take a git `user.name` and `user.email` argument (in that order) to customize the author. If the arguments are left empty, they will fallback to `Dokku` and `automated@dokku.sh`, respectively.
The default archive type is always set to `.tar`. To use a different archive type, specify the `--archive-type` flag. Failure to do so will result in a failure to extract the archive.
```shell
dokku git:from-archive --archive-type zip node-js-app https://github.com/dokku/smoke-test-app/archive/2.0.0.zip "Camila""camila@example.com"
```
Finally, if the archive url is specified as `--`, the archive will be fetched from stdin.
### 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.
```shell
docker image save dokku/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app dokku/node-js-getting-started:latest
```
In the above example, we are saving the image to a tar file via `docker image save`, streaming that to the Dokku host, and then running `git:load-image` on the incoming stream. Dokku will build the app as if the repository contained _only_ a `Dockerfile` with the following content:
```Dockerfile
FROMdokku/node-js-getting-started:latest
```
When deploying an app via `git:load-image`, it is highly recommended to use a unique image tag when building the image. Not doing so will result in Dokku exiting `0` early as there will be no changes detected. If the image tag is reused but the underlying image is different, it is recommended to use the image digest instead of the tag. This can be retrieved via the following command:
# for images built locally and not pushed to a registry
# use when the previous command output is empty
docker images --no-trunc --quiet $IMAGE_NAME
```
The resulting `git:load-image` call would then be:
```shell
# where the image sha is: sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673
docker image save dokku/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app dokku/node-js-getting-started@sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673
```
The `git:load-image` command can optionally take a git `user.name` and `user.email` argument (in that order) to customize the author. If the arguments are left empty, they will fallback to `Dokku` and `automated@dokku.sh`, respectively.
Finally, certain images may require a custom build context in order for `ONBUILD ADD` and `ONBUILD COPY` statements to succeed. A custom build context can be specified via the `--build-dir` flag. All files in the specified `build-dir` will be copied into the repository for use within the `docker build` process. The build context _must_ be specified on each deploy, and is not otherwise persisted between builds.
Note that this command is currently not idempotent and may add duplicate entries to the `~dokku/.ssh/known_hosts` file.
### Creating a cloning ssh key pair
> [!IMPORTANT]
> New as of 0.33.0
While most repositories can be authenticated to via the `git:auth` command, some users may prefer to use an ssh key. This can be generated via the `git:generate-deploy-key` command, which generates a passwordless ed25519 key-pair.
```shell
dokku git:generate-deploy-key
```
```
Generating public/private ed25519 key pair.
Your identification has been saved in /home/dokku/.ssh/id_ed25519
Your public key has been saved in /home/dokku/.ssh/id_ed25519.pub
In order to clone a remote repository, the remote server should have the Dokku host's public key configured. This plugin does not currently create this key, but if there is one available, it can be shown via the `git:public-key` command.
In order to clone a remote repository, the remote server should have the Dokku host's public key configured. This plugin does not currently create this key, but if can be shown via the `git:public-key` command.
## 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.
In the above example, Dokku will build the app as if the repository contained _only_ a `Dockerfile` with the following content:
```Dockerfile
FROMmy-registry/node-js-getting-started:latest
```
If the specified image already exists on the Dokku host, it will not be pulled again, though this behavior may be changed using [build phase docker-options](/docs/advanced-usage/docker-options.md).
Triggering a build with the same arguments multiple times will result in Dokku exiting `0` early as there will be no changes detected. If the image tag is reused but the underlying image is different, it is recommended to use the image digest instead of the tag. This can be retrieved via the following command:
The `git:from-image` command can optionally take a git `user.name` and `user.email` argument (in that order) to customize the author. If the arguments are left empty, they will fallback to `Dokku` and `automated@dokku.sh`, respectively.
If the image is a private image that requires a docker login to access, the `registry:login` command should be used to log into the registry. See the [registry documentation](/docs/advanced-usage/registry-management.md#logging-into-a-registry) for more details on this process.
Finally, certain images may require a custom build context in order for `ONBUILD ADD` and `ONBUILD COPY` statements to succeed. A custom build context can be specified via the `--build-dir` flag. All files in the specified `build-dir` will be copied into the repository for use within the `docker build` process. The build context _must_ be specified on each deploy, and is not otherwise persisted between builds.
See the [dockerfile documentation](/docs/deployment/builders/dockerfiles.md) to learn about the different ways to configure Dockerfile-based deploys.
## 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.
```shell
docker image save my-registry/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app my-registry/node-js-getting-started:latest
```
In the above example, we are saving the image to a tar file via `docker image save`, streaming that to the Dokku host, and then running `git:load-image` on the incoming stream. Dokku will build the app as if the repository contained _only_ a `Dockerfile` with the following content:
```Dockerfile
FROMmy-registry/node-js-getting-started:latest
```
When deploying an app via `git:load-image`, it is highly recommended to use a unique image tag when building the image. Not doing so will result in Dokku exiting `0` early as there will be no changes detected. If the image tag is reused but the underlying image is different, it is recommended to use the image digest instead of the tag. This can be retrieved via the following command:
# for images built locally and not pushed to a registry
# use when the previous command output is empty
docker images --no-trunc --quiet $IMAGE_NAME
```
The resulting `git:load-image` call would then be:
```shell
# where the image sha is: sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673
docker image save my-registry/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app my-registry/node-js-getting-started@sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673
```
The `git:load-image` command can optionally take a git `user.name` and `user.email` argument (in that order) to customize the author. If the arguments are left empty, they will fallback to `Dokku` and `automated@dokku.sh`, respectively.
Finally, certain images may require a custom build context in order for `ONBUILD ADD` and `ONBUILD COPY` statements to succeed. A custom build context can be specified via the `--build-dir` flag. All files in the specified `build-dir` will be copied into the repository for use within the `docker build` process. The build context _must_ be specified on each deploy, and is not otherwise persisted between builds.
@@ -14,30 +14,23 @@ scheduler-docker-local:set <app> <key> (<value>) # Set or clear a sch
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:
As it is the default, unsetting the `DOCKER_SCHEDULER` config variable is also a valid way to reset the scheduler.
As it is the default, unsetting the `selected` scheduler property is also a valid way to reset the scheduler.
```shell
dokku config:unset node-js-app DOCKER_SCHEDULER
dokku scheduler:set node-js-app selected
```
## Usage
### Disabling chown of persistent storage
### Deploying amd64 images on arm64
The `scheduler-docker-local` plugin will ensure your storage mounts are owned by either `herokuishuser` or the overridden value you have set in `DOKKU_APP_USER`. You may disable this by running the following `scheduler-docker-local:set` command for your application:
Many builders only produce amd64-compatible images. The docker-local scheduler will automatically detect these and run them via the `--platform=linux/amd64` on arm64 deploy targets.
### Disabling the init process
@@ -101,7 +94,7 @@ The `formation` key should be specified as follows in the `app.json` file:
}
```
Omitting or removing the entry will result in parallelism for that process type to return to 1 entry at a time. This can be combined with the `parallel-schedule-count` property to speed up deployments.
Omitting or removing the entry will result in parallelism for that process type to return to 1 entry at a time. This can be combined with the `parallel-schedule-count` property to speed up deployments.
Note that increasing the value of `max_parallel` may significantly impact CPU utilization on your host as your app containers - and their respective processes - start up. Setting a value higher than the number of available CPUs is discouraged. It is recommended that users carefully set this value so as not to overburden their server.
scheduler-k3s:annotations:set <app|--global> <property> (<value>) [--process-type PROCESS_TYPE] <--resource-type RESOURCE_TYPE>, Set or clear an annotation for a given app/process-type/resource-type combination
scheduler-k3s:autoscaling-auth:set <app|--global> <trigger> [<--metadata key=value>...], Set or clear a scheduler-k3s autoscaling keda trigger authentication resource for an app
scheduler-k3s:autoscaling-auth:report <app|--global> [--format stdout|json] [--include-metadata] # Displays a scheduler-k3s autoscaling auth report for an app
scheduler-k3s:cluster-add [ssh://user@host:port] # Adds a server node to a Dokku-managed cluster
scheduler-k3s:cluster-list # Lists all nodes in a Dokku-managed cluster
scheduler-k3s:cluster-remove [node-id] # Removes client node to a Dokku-managed cluster
scheduler-k3s:initialize # Initializes a cluster
scheduler-k3s:labels:set <app|--global> <property> (<value>) [--process-type PROCESS_TYPE] <--resource-type RESOURCE_TYPE>, Set or clear a label for a given app/process-type/resource-type combination
scheduler-k3s:report [<app>] [<flag>] # Displays a scheduler-k3s report for one or more apps
scheduler-k3s:set [<app>|--global] <key> (<value>) # Set or clear a scheduler-k3s property for an app or the scheduler
scheduler-k3s:show-kubeconfig # Displays the kubeconfig for remote usage
scheduler-k3s:uninstall # Uninstalls k3s from the Dokku server
```
> [!NOTE]
> The k3s plugin replaces the external [scheduler-kubernetes](https://github.com/dokku/dokku-scheduler-kubernetes) plugin. Users can continue to use the external plugin as necessary, but all future development will occur on the official core k3s plugin.
For multi-server support, Dokku provides the ability for users to setup a K3s cluster. As with all schedulers, it is set on a per-app basis. The scheduler can currently be overridden by running the following command:
```shell
dokku scheduler:set node-js-app selected k3s
```
As it is the default, unsetting the `selected` scheduler property is also a valid way to reset the scheduler.
```shell
dokku scheduler:set node-js-app k3s
```
## Usage
### Initializing a cluster
> [!WARNING]
> This command must be run as root
Clusters can be initialized via the `scheduler-k3s:initialize` command. This will start a k3s cluster on the Dokku node itself.
```shell
dokku scheduler-k3s:initialize
```
By default, the k3s installation can run both app and system workloads. For clusters where app workloads are run on distinct worker nodes, initialize the cluster with the `--taint-scheduling` flag, which will allow _only_ Critical cluster components on the k3s control-plane nodes.
```shell
dokku scheduler-k3s:initialize --taint-scheduling
```
By default, Dokku will attempt to auto-detect the IP address of the server. In cases where the auto-detected IP address is incorrect, an override may be specified via the `--server-ip` flag:
Dokku's k3s integration natively uses `nginx` as it's ingress load balancer via [ingress-nginx](https://github.com/kubernetes/ingress-nginx). Properties set by the `nginx` plugin will be respected, either by turning them into annotations or creating a custom server/location snippet that the `ingress-nginx` project can use.
Dokku can also use Traefik on cluster initialization via the [Traefik's CRDs](https://doc.traefik.io/traefik/providers/kubernetes-crd/). To change the ingress, set the `--ingress-class` flag:
> The `dokku` user _must_ be able to ssh onto the server in order to connect nodes to the cluster. The remote user must be root or have sudo enabled, or the install will fail.
#### Adding a worker node
Nodes that run app workloads can be added via the `scheduler-k3s:cluster-add` command. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in worker mode. Workers are typically used to run app workloads.
By default, Dokku will attempt to auto-detect the IP address of the Dokku server for the remote server to connect to. In cases where the auto-detected IP address is incorrect, an override may be specified via the `--server-ip` flag:
> Only the initial Dokku server will be properly configured for push deployment, and should be considered your git remote. Additional server nodes are for ensuring high-availability of the K3s etcd state. Ensure this server is properly backed up and restorable or deployments will not work.
Server nodes are typically used to replicate the cluster state, and it is recommended to have an odd number of nodes spread across several availability zones (datacenters in close proximity within a region). This allows for higher availability in the event of a cluster failure. Server nodes run control-plane services such as the traefik load balancer and the etcd backing store.
Server nodes can also be added with the `scheduler-k3s:cluster-add` command by specifying `--role server`. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in server mode.
```shell
dokku scheduler-k3s:cluster-add --role server ssh://root@server-1.example.com
```
Server nodes allow any workloads to be scheduled on them by default, in addition to the control-plane, etcd, and the scheduler itself. To avoid app workloads being scheduled on your control-plane, use the `--taint-scheduling` flag:
```shell
dokku scheduler-k3s:cluster-add --role server --taint-scheduling ssh://root@server-1.example.com
```
If the server isn't in the `known_hosts` file, the connection will fail. This can be bypassed by setting the `--insecure-allow-unknown-hosts` flag:
```shell
dokku scheduler-k3s:cluster-add --role server --insecure-allow-unknown-hosts ssh://root@server-1.example.com
```
By default, Dokku will attempt to auto-detect the IP address of the Dokku server for the remote server to connect to. In cases where the auto-detected IP address is incorrect, an override may be specified via the `--server-ip` flag:
```shell
dokku scheduler-k3s:cluster-add --role server --server-ip 192.168.20.15 ssh://root@server-1.example.com
```
#### Changing the network interface
When attaching an worker or server node, the K3s plugin will look at the IP associated with the `eth0` interface and use that to connect the new node to the cluster. To change this, set the `network-interface` property to the appropriate value.
The default value may be set by passing an empty value for the option.
```shell
dokku scheduler-k3s:set --global deploy-timeout
```
### Customizing the namespace
By default, app deploys will run against the `default` Kubernetes namespace. To customize this value, set the `namespace` property via `scheduler-k3s:set`:
When authenticating against a registry via `registry:login`, the scheduler-k3s plugin will authenticate all servers in the cluster against the registry specified. If desired, an image pull secret can be used instead. To customize this value, set the `image-pull-secrets` property via `scheduler-k3s:set`:
The `image-pull-secrets` property can also be set globally. The global default is empty string, and k3s will use Dokku's locally configured `~/.docker/config.json` for any private registry pulls.
By default, letsencrypt is disabled and https port mappings are ignored. To enable, set the `letsencrypt-email-prod` or `letsencrypt-email-stag` property with the `--global` flag:
After enabling and rebuilding, all apps with an `http:80` port mapping will have a corresponding `https:443` added and ssl will be automatically enabled. All http requests will then be redirected to https.
#### Customizing the letsencrypt server
The letsencrypt integration is set to the production letsencrypt server by default. This can be changed on an app-level by setting the `letsencrypt-server` property with the `scheduler-k3s:set` command
> The cron ID is used as the process type if your app deploys any cron tasks
#### Setting Annotations
Dokku injects certain annotations into each created resource by default, but it may be necessary to inject others for tighter integration with third-party tools. The `scheduler-k3s:annotations:set` command can be used to perform this task. The command takes an app name and a required `--resource-type` flag.
If not specified, the annotation will be applied to all processes within an app, though it may be further scoped to a specific process type via the `--process-type` flag.
```shell
dokku scheduler-k3s:annotations:set node-js-app annotation.key annotation.value --resource-type deployment --process-type web
dokku scheduler-k3s:annotations:set node-js-app annotation.key --resource-type deployment --process-type web
```
#### Setting Labels
Dokku injects certain labels into each created resource by default, but it may be necessary to inject others for tighter integration with third-party tools. The `scheduler-k3s:labels:set` command can be used to perform this task. The command takes an app name and a required `--resource-type` flag.
If not specified, the label will be applied to all processes within an app, though it may be further scoped to a specific process type via the `--process-type` flag.
```shell
dokku scheduler-k3s:labels:set node-js-app label.key label.value --resource-type deployment --process-type web
dokku scheduler-k3s:labels:set node-js-app label.key --resource-type deployment --process-type web
```
### Autoscaling
#### Workload Autoscaling
> [!IMPORTANT]
> New as of 0.33.8
> Users with older installations will need to manually install Keda.
Autoscaling in k3s is managed by [Keda](https://keda.sh/), which integrates with a variety of external metric providers to allow for autoscaling application workloads.
To enable autoscaling, use the `app.json``formation.$PROCESS_TYPE.autoscaling` key to manage rules. In addition to the existing configuration used for process management, each process type in the `formation.$PROCESS_TYPE.autoscaling` key can have the following keys:
-`min_quantity`: The minimum number of instances the application can run. If not specified, the `quantity` specified for the app is used.
-`max_quantity`: The maximum number of instances the application can run. If not specified, the higher value of `quantity` and the `min_quantity` is used.
-`polling_interval_seconds`: (default: 30) The interval to wait for polling each of the configured triggers
-`cooldown_seconds`: (default: 300) The number of seconds to wait in between each scaling event
-`triggers`: A list of autoscaling triggers.
Autoscaling triggers are passed as is to Keda, and should match the configuration keda uses for a given [scaler](https://keda.sh/docs/2.13/scalers/). Below is an example for [datadog](https://keda.sh/docs/2.13/scalers/datadog/#example-2---driving-scale-directly):
Each value in the `metadata` stanza can use the following interpolated strings:
-`DOKKU_DEPLOYMENT_NAME`: The name of the deployment being scaled
-`DOKKU_PROCESS_TYPE`: The name of the process being scaled
-`DOKKU_APP_NAME`: The name of the app being scaled
#### Workload Autoscaling Authentication
Most Keda triggers require some form of authentication to query for data. In the Kubernetes API, they are represented by `TriggerAuthentication` and `ClusterTriggerAuthentication` resources. Dokku can manage these via the `scheduler-k3s:autoscaling-auth` commands, and includes generated resources with each helm release generated by a deploy.
If no app-specific authentication is provided for a given trigger type, Dokku will fallback to any globally defined `ClusterTriggerAuthentication` resources. Autoscaling triggers within an app all share the same `TriggerAuthentication` resources, while `ClusterTriggerAuthentication` resources can be shared across all apps deployed by Dokku within a given cluster.
##### Creating Authentication Resources
Users can specify custom authentication resources directly via the Kubernetes api _or_ use the `scheduler-k3s:autoscaling-auth:set` command to create the resources in the Kubernetes cluster.
After execution, Dokku will include the following resources for each specified trigger with the helm release generated on subsequent app deploys:
-`Secret`: an Opaque `Secret` resource storing the authentication credentials
-`TriggerAuthentication`: A `TriggerAuthentication` resource that references the secret for use by triggers
If the `--global` flag is specified instead of an app name, a custom helm chart is created on the fly with the above resources.
##### Removing Authentication Resources
To remove a configured authenticatin resource, run the `scheduler-k3s:autoscaling-auth:set` command with no metadata specified. Subsequent deploys will not include these resources.
By default, the report will not display configured metadata - making it safe to include in Dokku report output. To include metadata and their values, add the `--include-metadata` flag:
> Certain ports must be open for interacting with the remote kubernets api. Refer to the [K3s networking documentation](https://docs.k3s.io/installation/requirements?os=debian#networking) for the required open ports between servers prior to running the command.
By default, Dokku assumes that all it controls all actions on the cluster, and thus does not expose the `kubectl` binary for administrators. To interact with kubectl, you will need to retrieve the `kubeconfig` for the cluster and configure your client to use that configuration.
```shell
dokku scheduler-k3s:show-kubeconfig
```
### Interacting with an external Kubernetes cluster
While the k3s scheduler plugin is designed to work with a Dokku-managed k3s cluster, Dokku can be configured to interact with any Kubernetes cluster by setting the global `kubeconfig-path` to a path to a custom kubeconfig on the Dokku server. This property is only available at a global level.
To set the default value, omit the value from the `scheduler-k3s:set` call:
```shell
dokku scheduler-k3s:set --global kubeconfig-path
```
The default value for the `kubeconfig-path` is the k3s kubeconfig located at `/etc/rancher/k3s/k3s.yaml`.
### Customizing the Kubernetes context
When interacting with a custom Kubeconfig, the `kube-context` property can be set to specify a specific context within the kubeconfig to use. This property is available only at the global leve.
To set the default value, omit the value from the `scheduler-k3s:set` call:
```shell
dokku scheduler-k3s:set --global kube-context
```
The default value for the `kube-context` is an empty string, and will result in Dokku using the current context within the kubeconfig.
## Scheduler Interface
The following sections describe implemented and unimplemented scheduler functionality for the `k3s` scheduler.
### Implemented Commands and Triggers
This plugin implements various functionality through `plugn` triggers to integrate with Docker for running apps on a single server. The following functionality is supported by the `scheduler-k3s` plugin.
-`apps:clone`
-`apps:destroy`
-`apps:rename`
-`cron`
-`enter`
-`deploy`
- healthchecks
- Due to Kubernetes limitations, only a single healthcheck is supported for each of the `liveness`, `readiness`, and `startup` healthchecks
- Due to Kubernetes limitations, content checks are not supported
- Ports specified in the `app.json` are ignored in favor of the container port on the port mapping detected
-`logs`
-`ps:stop`
-`run`
- The `scheduler-post-run` trigger is not always triggered
-`run:detached`
-`run:list`
### Unimplemented command functionality
-`run:logs`
-`ps:inspect`
The following Dokku functionality is not implemented at this time.
-`vector` log integration
- persistent storage
### Logging support
App logs for the `logs` command are fetched by Dokku from running containers via the `kubectl` cli. Persisting logs via Vector is not implemented at this time. Users may choose to configure the Vector Kubernetes integration directly by following [this guide](https://vector.dev/docs/setup/installation/platforms/kubernetes/).
### Supported Resource Management Properties
The `k3s` scheduler supports a minimal list of resource _limits_ and _reservations_:
- cpu: is specified in number of CPUs a process can access.
- memory: should be specified with a suffix of `b` (bytes), `Ki` (kilobytes), `Mi` (megabytes), `Gi` (gigabytes). Default unit is `Mi` (megabytes).
If unspecified for any task, the default reservation will be `.1` CPU and `128Mi` RAM, with no limit set for either CPU or RAM. This is to avoid issues with overscheduling pods on a cluster. To avoid issues, set more specific values for at least resource reservations. If unbounded utilization is desired, set CPU and Memory to `0m` and `0Mi`, respectively.
> [!NOTE]
> Cron tasks retrieve resource limits based on the computed cron task ID.
> This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes.
> Deprecation notice: This scheduler has been replaced with the [k3s scheduler plugin](/docs/deployment/schedulers/k3s.md) and is no longer under active development.
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.
- 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.
- Invoked by: `internal function dokku_build() (build phase)`
- 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 buildpacks.
- Invoked by: `internal function dokku_build() (build phase)`
- Arguments: `$APP``$SOURCECODE_WORK_DIR`
@@ -1786,8 +1857,29 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `pre-build-dockerfile`
> [!WARNING]
> Deprecated, please use `pre-build` instead
- 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 a dockerfile.
- Invoked by: `internal function dokku_build() (build phase)`
- Arguments: `$APP`
- Example:
```shell
#!/usr/bin/env bash
set -eo pipefail;[[$DOKKU_TRACE]]&&set -x
# TODO
```
### `pre-build-lambda`
> [!WARNING]
> Deprecated, please use `pre-build` instead
- 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 lambda.
- Invoked by: `internal function dokku_build() (build phase)`
- Arguments: `$APP``$SOURCECODE_WORK_DIR`
@@ -1804,8 +1896,7 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
### `pre-build-pack`
> [!WARNING]
> The pack plugin trigger apis are under development and may change
> between minor releases until the 1.0 release.
> Deprecated, please use `pre-build` instead
- 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.
- Invoked by: `internal function dokku_build() (build phase)`
@@ -1820,21 +1911,6 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `pre-build-dockerfile`
- 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 a dockerfile.
- Invoked by: `internal function dokku_build() (build phase)`
- Arguments: `$APP`
- Example:
```shell
#!/usr/bin/env bash
set -eo pipefail;[[$DOKKU_TRACE]]&&set -x
# TODO
```
### `pre-delete`
- Description: Can be used to run commands before an app is deleted.
> Deprecated, please use `pre-release-builder` instead
- Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using buildpacks.
- Invoked by: `internal function dokku_release() (release phase)`
> Deprecated, please use `pre-release-builder` instead
- Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using lambda.
- Invoked by: `internal function dokku_release() (release phase)`
- Arguments: `$APP $IMAGE_TAG`
@@ -1978,8 +2077,7 @@ APP="$1"; IMAGE_TAG="$2";
### `pre-release-pack`
> [!WARNING]
> The pack plugin trigger apis are under development and may change
> between minor releases until the 1.0 release.
> Deprecated, please use `pre-release-builder` instead
- Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using pack.
- Invoked by: `internal function dokku_release() (release phase)`
@@ -1998,6 +2096,9 @@ APP="$1"; IMAGE_TAG="$2";
### `pre-release-dockerfile`
> [!WARNING]
> Deprecated, please use `pre-release-builder` instead
- Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using a dockerfile.
- Invoked by: `internal function dokku_release() (release phase)`
- Arguments: `$APP $IMAGE_TAG`
@@ -2107,24 +2208,6 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
# TODO
```
### `proxy-configure-ports`
> [!WARNING]
> Deprecated, please use `ports-configure` instead
- Description: Configures the port mapping
- Invoked by: `internally triggered by proxy plugins`
- Arguments: `$APP`
- Example:
```shell
#!/usr/bin/env bash
set -eo pipefail;[[$DOKKU_TRACE]]&&set -x
# TODO
```
### `proxy-disable`
- Description: Disables the configured proxy implementation for an app
As of 0.3.18, Dokku defaults to being installed via Debian package. While certain hosts may require extra work to get running, you may optionally wish to automate the installation of Dokku without the use of our `bootstrap.sh` Bash script. The following are the steps run by said script:
1. Simply add a checkmark next to the existing keys you'd like to add.
7. Under **Finalize and create**, give your Droplet a hostname _(not required)_ and click **Create**.
8. Once created, copy the IP address to your clipboard.
9. In a browser, go to the IP address you copied above and fill out the presented form to complete configuration. _Failure to do so may allow others to reconfigure SSH access on your server._
10.Once the web UI has been submitted, you will be redirected to our [application deployment tutorial](/docs/deployment/application-deployment.md), which will guide you through deploying a sample application to your Dokku server.
9. In a terminal, ssh onto the server by running `ssh root@$SERVER_IP`, where `$SERVER_IP` is your server's IP address.
10.Remove the default nginx site via `rm /etc/nginx/sites-enabled/default`
11. If you added more than one key, use the `dokku ssh-keys:add` to add an ssh key to the dokku user:
12. Ensure your server has a correct global hostname via `dokku domains:set-global`
```shell
# replace dokku.me with a hostname pointed at your server
dokku domains:set-global dokku.me
```
13. Once the web UI has been submitted, you will be redirected to our [application deployment tutorial](/docs/deployment/application-deployment.md), which will guide you through deploying a sample application to your Dokku server.
The alternative is to build a custom docker image via a custom Dockerfile. This Dockerfile can run any `plugin:install` command. Note that the version installed at that time will be the one that persists. Below is an example Dockerfile showing this method.
```Dockerfile
FROMdokku/dokku:0.31.4
FROMdokku/dokku:0.34.2
RUN dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres
RUN dokku plugin:install https://github.com/dokku/dokku-redis.git redis
```
## SSH Key Management
To initialize ssh-keys within the container, use `docker exec` to enter the container and run the appropriate ssh-keys commands.
To initialize ssh-keys within the container, use `docker exec` to enter the container:
<gid="mysql"data-bs-toggle="svg-tooltip"data-bs-placement="bottom"title="MySQL"filter="url(#filter9_d_55_77)"transform="translate(79.2566,394.257) translate(-79.2566,-394.257)"style="animation: 30s linear infinite both mysql_t;">
@@ -49,110 +49,6 @@ The nginx server can be stopped via `nginx:stop`.
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.
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.
This may be reverted by setting an empty bind address.
```shell
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.
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.
If SSL certificates are present, HSTS will be automatically enabled. It can be toggled via `nginx:set`:
```shell
dokku nginx:set node-js-app hsts true
dokku nginx:set node-js-app hsts false
```
The following options are also available via the `nginx:set` command:
-`hsts` (type: boolean, default: `true`): Enables or disables HSTS for your application.
-`hsts-include-subdomains` (type: boolean, default: `true`): Tells the browser that the HSTS policy also applies to all subdomains of the current domain.
-`hsts-max-age` (type: integer, default: `15724800`): Time in seconds to cache HSTS configuration.
-`hsts-preload` (type: boolean, default: `false`): Tells most major web browsers to include the domain in their HSTS preload lists.
Beware that if you enable the header and a subsequent deploy of your application results in an HTTP deploy (for whatever reason), the way the header works means that a browser will not attempt to request the HTTP version of your site if the HTTPS version fails until the max-age is reached.
#### 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.
HSTS Header can be disabled for all apps by setting the `hsts` property to false after passing the `--global` flag to `nginx:set`.
```shell
dokku nginx:set --global hsts false
```
Once the HSTS setting is disabled globally, it can be re-enabled on a per-app basis by setting the `hsts` property as normal.
```shell
dokku nginx:set node-js-app hsts true
```
### Running behind another proxy — configuring `X-Forwarded-*` headers
Dokku's default Nginx configuration passes the de-facto standard HTTP headers [`X-Forwarded-For`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), [`X-Forwarded-Proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto), and `X-Forwarded-Port` to your application.
These headers indicate the IP address of the original client making the request, the protocol of the original request (HTTP or HTTPS), and the port number of the original request, respectively.
If you have another HTTP proxy sitting in between the end user and your server (for example, a load balancer, or a CDN), then the values of these headers will contain information about (e.g. the IP address of) the the closest proxy, and not the end user.
To fix this, assuming that the other proxy also passes `X-Forwarded-*` headers, which in turn contain information about the end user, you can tell Nginx include those values in the `X-Forwarded-*` headers that it sends to your application. You can do this via `nginx:set`, like so:
1. Requests to your website always go through a trusted proxy.
2. That proxy is configured to send the aforementioned `X-Forwarded-*` headers.
Otherwise, if it's possible for clients to make HTTP requests directly against your server, bypassing the other proxy, or if the other proxy is not configured to set these headers, then a client can basically pass any arbitrary values for these headers (which your app then presumably reads) and thereby fake an IP address, for example.
There's also the `X-Forwarded-Ssl` header which a less common alternative to `X-Forwarded-Proto` — and because of that, isn't included in Dokku's default Nginx configuration.
But you can tell Nginx to send this header as well, if necessary.
```shell
# force-setting value to `on`
dokku nginx:set node-js-app x-forwarded-ssl on
# force-setting value to `off`
dokku nginx:set node-js-app x-forwarded-ssl off
# removing the value from nginx.conf (default)
dokku nginx:set node-js-app x-forwarded-ssl
```
### Checking access logs
> [!NOTE]
@@ -184,130 +80,6 @@ You may also follow the logs by specifying the `-t` flag.
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.
The path to where log files are stored can be changed by calling the `nginx:set` command with the following options:
The defaults should not be changed without verifying that the paths will be writeable by nginx. However, this setting is useful for enabling or disabling logging by setting the values to `off`.
```shell
dokku nginx:set node-js-app access-log-path off
dokku nginx:set node-js-app error-log-path off
```
The default value may be set by passing an empty value for the option:
```shell
dokku nginx:set node-js-app access-log-path
dokku nginx:set node-js-app error-log-path
```
In all cases, the nginx config must be regenerated after setting the above values.
### 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.
The format of the access log can be changed by calling the `nginx:set` command as follows:
Prior to changing the log-format, log formats should be specified at a file such as `/etc/nginx/conf.d/00-log-formats.conf`. This will ensure they are available within your app's nginx context. For instance, the following may be added to the above file. It only needs to be specified once to be used for all apps.
Finally, a proxy rebuild will change the format as desired.
```shell
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.
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:
The default value is `60s`, and all numeric values _must_ have a trailing time value specified (`s` for seconds, `m` for minutes).
The default value may be set by passing an empty value for the option:
```shell
dokku nginx:set node-js-app proxy-read-timeout
```
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.
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.
The default value is empty string, which will result in nginx falling back to any configured, higher-level defaults (or `1m` if unconfigued; all numerical values _must_ have a size unit specified (`k` for kilobytes, `m` for megabytes).
The default value may be set by passing an empty value for the option:
```shell
dokku nginx:set node-js-app client-max-body-size
```
In all cases, the nginx config must be regenerated after setting the above value.
Changing this value when using the PHP buildpack (or any other buildpack that uses an intermediary server) will require changing the value in the server config shipped with that buildpack. Consult your buildpack documentation for further details.
### Showing the nginx config
For debugging purposes, it may be useful to show the nginx config. This can be achieved via the `nginx:show-config` command.
@@ -341,6 +113,65 @@ The `--clean` flag may also be specified for a given app:
dokku nginx:validate-config node-js-app --clean
```
### Custom Error Pages
By default, Dokku provides custom error pages for the following three categories of errors:
- 4xx: For all non-404 errors with a 4xx response code.
- 404: For "404 Not Found" errors.
- 5xx: For all 5xx error responses
These are provided as an alternative to the generic Nginx error page, are shared for _all_ applications, and their contents are located on disk at `/var/lib/dokku/data/nginx-vhosts/dokku-errors`. To customize them for a specific app, create a custom `nginx.conf.sigil` as described above and change the paths to point elsewhere.
### Default site
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:
>
> ```
> rm /etc/nginx/sites-enabled/default
> dokku nginx:stop
> dokku nginx:start
> ```
If services should only be accessed via their domain name, you may want to disable the default site by adding the following configuration to the global nginx configuration.
Create the file at `/etc/nginx/conf.d/00-default-vhost.conf`:
```nginx
server{
listen80default_server;
listen[::]:80default_server;
# If services hosted by dokku are available via HTTPS, it is recommended
# to also uncomment the following section.
#
# Please note that in order to let this work, you need an SSL certificate. However
# it does not need to be valid. Users of Debian-based distributions can install the
# `ssl-cert` package with `sudo apt install ssl-cert` to automatically generate
# a self-signed certificate that is stored at `/etc/ssl/certs/ssl-cert-snakeoil.pem`.
Make sure to reload nginx after creating this file by running `systemctl reload nginx.service`.
This will catch all unknown HOST header values and close the connection without responding. You can replace the `return 444;` with `return 410;` which will cause nginx to respond with an error page.
The configuration file must be loaded before `/etc/nginx/conf.d/dokku.conf`, so it can not be arranged as a vhost in `/etc/nginx/sites-enabled` that is only processed afterwards.
Alternatively, you may push an app to your Dokku host with a name like "00-default". As long as it lists first in `ls /home/dokku/*/nginx.conf | head`, it will be used as the default nginx vhost.
### Customizing the nginx configuration
> [!IMPORTANT]
@@ -445,64 +276,189 @@ location / {
Please adjust the `Procfile` and `nginx.conf` file as appropriate.
### Custom Error Pages
### Setting Properties for the nginx config
By default, Dokku provides custom error pages for the following three categories of errors:
The nginx plugin exposes a variety of properties configurable via the `nginx:set` command. The properties are used to configure the generated `nginx.conf` file from the `nginx.conf.sigil` template. The value precedence is app-specific, then global, and finally the Dokku default.
- 4xx: For all non-404 errors with a 4xx response code.
- 404: For "404 Not Found" errors.
- 5xx: For all 5xx error responses
The nginx:set command takes an app name or the `--global` flag.
These are provided as an alternative to the generic Nginx error page, are shared for _all_ applications, and their contents are located on disk at `/var/lib/dokku/data/nginx-vhosts/dokku-errors`. To customize them for a specific app, create a custom `nginx.conf.sigil` as described above and change the paths to point elsewhere.
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:
>
> ```
> rm /etc/nginx/sites-enabled/default
> dokku nginx:stop
> dokku nginx:start
> ```
If services should only be accessed via their domain name, you may want to disable the default site by adding the following configuration to the global nginx configuration.
Create the file at `/etc/nginx/conf.d/00-default-vhost.conf`:
```nginx
server{
listen80default_server;
listen[::]:80default_server;
# If services hosted by dokku are available via HTTPS, it is recommended
# to also uncomment the following section.
#
# Please note that in order to let this work, you need an SSL certificate. However
# it does not need to be valid. Users of Debian-based distributions can install the
# `ssl-cert` package with `sudo apt install ssl-cert` to automatically generate
# a self-signed certificate that is stored at `/etc/ssl/certs/ssl-cert-snakeoil.pem`.
Make sure to reload nginx after creating this file by running `systemctl reload nginx.service`.
Additionally, setting an empty value will result in reverting the value back to it's default. For app-specific values, this means that Dokku will revert to the globally specified (or global default) value.
This will catch all unknown HOST header values and close the connection without responding. You can replace the `return 444;` with `return 410;` which will cause nginx to respond with an error page.
```shell
# default the value back to the global value for node-js-app
dokku nginx:set node-js-app property-name
The configuration file must be loaded before `/etc/nginx/conf.d/dokku.conf`, so it can not be arranged as a vhost in `/etc/nginx/sites-enabled` that is only processed afterwards.
# use the dokku default as the global value
dokku nginx:set --global property-name
```
Changing these value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
> [!WARNING]
> Validation is not performed against the values, and they are used as is within Dokku.
| access-log-format | empty string | string | Name of custom log format to use (log format must be specified elsewhere) |
| access-log-path | `${NGINX_LOG_ROOT}/${APP}-access.log` | string | Log path for nginx access logs (set to `off` to disable) |
| bind-address-ipv4 | `0.0.0.0` | string | Default IPv4 address to bind to |
| bind-address-ipv6 | `[::]` | string | Default IPv6 address to bind to |
| client-max-body-size | `1m` | string | Size (with units) of client request body (usually modified for file uploads) |
| error-log-path | `${NGINX_LOG_ROOT}/${APP}-error.log` | string | Log path for nginx error logs (set to `off` to disable) |
| hsts | `true` | boolean | Enables or disables HSTS for your application |
| hsts-include-subdomains | `true` | boolean | Forces the browser to apply the HSTS policy to all app subdomains |
| hsts-max-age | `15724800` | integer | Time in seconds to cache HSTS configuration |
| hsts-preload | `false` | boolean | Tells the browser to include the domain in their HSTS preload lists |
| nginx-conf-sigil-path | `nginx.conf.sigil` | string | Path in the repository to the `nginx.conf.sigil` file |
| 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 |
| proxy-busy-buffers-size | `16k` | string | Limits the total size of buffers that can be busy sending a response to the client while the response is not yet fully read. |
| proxy-read-timeout | `60s` | string | Timeout (with units) for reading response from your backend server |
| underscore-in-headers | `off` | string | Enables or disables the use of underscores in client request header fields. |
| x-forwarded-for-value | `$remote_addr` | string | Used for specifying the header value to set for the `X-Forwared-For` header |
| x-forwarded-port-value | `$server_port` | string | Used for specifying the header value to set for the `X-Forwared-Port` header |
| x-forwarded-proto-value | `$scheme` | string | Used for specifying the header value to set for the `X-Forwared-Proto` header |
| x-forwarded-ssl | empty string | string | Less commonly used alternative to `X-Forwarded-Proto` (valid values: `on` or `off`) |
#### Binding to specific addresses
> [!NOTE]
> 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.
Properties:
-`bind-address-ipv4`
-`bind-address-ipv6`
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.
#### HSTS Header
> [!WARNING]
> if you enable the header and a subsequent deploy of your application results in an HTTP deploy (for whatever reason), the way the header works means that a browser will not attempt to request the HTTP version of your site if the HTTPS version fails until the max-age is reached.
Properties:
-`hsts`
-`hsts-include-subdomains`
-`hsts-max-age`
-`hsts-preload`
If SSL certificates are present, HSTS will be automatically enabled.
#### Running behind another proxy — configuring `X-Forwarded-*` headers
> [!WARNING]
> These values should only be modified if there is an intermediate Load balancer or CDN between the user and the Dokku server hosting your application.
Properties:
-`x-forwarded-for-value`
-`x-forwarded-port-value`
-`x-forwarded-proto-value`
-`x-forwarded-ssl`
Dokku's default Nginx configuration passes the de-facto standard HTTP headers [`X-Forwarded-For`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), [`X-Forwarded-Proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto), and `X-Forwarded-Port` to your application.
These headers indicate the IP address of the original client making the request, the protocol of the original request (HTTP or HTTPS), and the port number of the original request, respectively.
If you have another HTTP proxy sitting in between the end user and your server (for example, a load balancer, or a CDN), then the values of these headers will contain information about (e.g. the IP address of) the the closest proxy, and not the end user.
To fix this, assuming that the other proxy also passes `X-Forwarded-*` headers, which in turn contain information about the end user, you can tell Nginx include those values in the `X-Forwarded-*` headers that it sends to your application. You can do this via `nginx:set`, like so:
1. Requests to your website always go through a trusted proxy.
2. That proxy is configured to send the aforementioned `X-Forwarded-*` headers.
Otherwise, if it's possible for clients to make HTTP requests directly against your server, bypassing the other proxy, or if the other proxy is not configured to set these headers, then a client can basically pass any arbitrary values for these headers (which your app then presumably reads) and thereby fake an IP address, for example.
There's also the `X-Forwarded-Ssl` header which a less common alternative to `X-Forwarded-Proto` — and because of that, isn't included in Dokku's default Nginx configuration. It can be turned `on` if need be:
```shell
# force-setting value to `on`
dokku nginx:set node-js-app x-forwarded-ssl on
```
#### Changing log path
> [!WARNING]
> The defaults should not be changed without verifying that the paths will be writeable by nginx.
Properties:
-`access-log-path`
-`error-log-path`
These setting can be useful for enabling or disabling logging by setting the values to `off`.
```shell
dokku nginx:set node-js-app access-log-path off
dokku nginx:set node-js-app error-log-path off
```
#### Changing log format
Properties:
-`acccess-log-format`
Prior to changing the log-format, log formats should be specified at a file such as `/etc/nginx/conf.d/00-log-formats.conf`. This will ensure they are available within your app's nginx context. For instance, the following may be added to the above file. It only needs to be specified once to be used for all apps.
```nginx
# /etc/nginx/conf.d/00-log-formats.conf
# escape=json was added in nginx 1.11.8
log_formatjson_combinedescape=json
'{'
'"time_local":"$time_local",'
'"remote_addr":"$remote_addr",'
'"remote_user":"$remote_user",'
'"request":"$request",'
'"status":"$status",'
'"body_bytes_sent":"$body_bytes_sent",'
'"request_time":"$request_time",'
'"http_referrer":"$http_referer",'
'"http_user_agent":"$http_user_agent"'
'}';
```
#### Specifying a read timeout
> [!NOTE]
> All numeric values _must_ have a trailing time value specified (`s` for seconds, `m` for minutes).
Properties:
-`proxy-read-timeout`
#### Specifying a custom client_max_body_size
> [!NOTE]
> All numerical values _must_ have a trailing size unit specified (`k` for kilobytes, `m` for megabytes).
Properties:
-`client-max-body-size`
This property is commonly used to increase the max file upload size.
Changing this value when using the PHP buildpack (or any other buildpack that uses an intermediary server) will require changing the value in the server config shipped with that buildpack. Consult your buildpack documentation for further details.
Alternatively, you may push an app to your Dokku host with a name like "00-default". As long as it lists first in `ls /home/dokku/*/nginx.conf | head`, it will be used as the default nginx vhost.
It may be necessary to check the OpenResty container's logs to ensure that OpenResty is operating as expected. This can be performed with the `openresty:logs` command.
The above command will show logs continually from the openresty container, with an initial history of 10 log lines
### Customizing Openresty Settings for an app
#### OpenResty Properties
The OpenResty plugin supports all properties supported by the `nginx:set` command via `openresty:set`. At this time, please consult the nginx documentation for more information on what properties are available.
Please note that the oldest running container will be used for OpenResty configuration, and thus newer config may not apply until older app containers are retired during/after a deploy, depending on your zero-downtime settings.
#### Custom OpenResty Templates
At this time, the OpenResty plugin does not allow complete customization of the template used to manage an app's vhost. Apps will use a template provided by the OpenResty container to proxy requests. See the next section for documentation on how to configure portions of the template.
#### Injecting custom snippets into the OpenResty config
The OpenResty plugin allows users to specify templates in their repository for auto-injection into the OpenResty config. Please note that this configuration should be validated prior to deployment or may cause outages in your OpenResty proxy layer.
The following folders within an app repository may have `*.conf` files that will be automatically injected into the OpenResty config.
-`openresty/http-includes/`: Injected in the `server` block serving http(s) requests for the app.
-`openresty/http-location-includes/`: Injected in the `location` block that proxies to the app in the app's respective `server` block.
### SSL Configuration
The OpenResty plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the `certs` plugin are ignored.
After enabling, the OpenResty container will need to be restarted and apps will need to be rebuilt to retrieve certificates from the new server.
#### Limiting letsencrypt to certain domains
> [!WARNING]
> Changing this value may cause OpenResty to fail to start if the value is not valid. Caution should be exercised when changing this value from the defaults.
In cases where your server's IP may have invalid domains pointing at it, limiting letsencrypt to certain allowed domains may be desirable to reduce spam requests on the Letsencrypt servers. The default is to allow all domains to have certificates retrieved, but this can be limited by specifying the `allowed-letsencrypt-domains-func-base64` global property.
The default internal value for `allowed-letsencrypt-domains-func-base64` is the base64 representation of `return true`, and is meant to be the body of a lua function that return a boolean value.
As this is a global value, once changed, OpenResty should be stopped and started again for the value to take effect:
```shell
dokku openresty:stop
dokku openresty:start
```
A more complex example would be to limit provisioning of certificates to domains in a specific list. The body of the lua function has access to a variable `domain`, and we can use it like so:
After modifying, the Traefik container will need to be restarted.
### Setting rule priority
By default, app deployments will result in the newer traefik rules using a higher priority in order to have any newer rules respected by Traefik. Rule priorities will always increase according to the current unix timestamp. The priority may be fixed by setting the app-level `priority` property:
```shell
dokku traefik:set node-js-app priority 12345
```
After modifying, the app container will need to be recreated via a `ps:rebuild` or an app deployment.
### SSL Configuration
The traefik plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the `certs` plugin are ignored.
@@ -9,13 +9,39 @@ proxy:clear-config [--all|<app>] # Clears config for given app
proxy:disable [--parallel count] [--all|<app>] # Disable proxy for app
proxy:enable [--parallel count] [--all|<app>] # Enable proxy for app
proxy:report [<app>] [<flag>] # Displays a proxy report for one or more apps
proxy:set <app> <proxy-type> # Set proxy type for app
proxy:set [<app>|--global] <proxy-type> # Set proxy type for app
```
In Dokku 0.5.0, port proxying was decoupled from the `nginx-vhosts` plugin into the proxy plugin. Dokku 0.6.0 introduced the ability to map host ports to specific container ports. In the future this will allow other proxy software - such as HAProxy or Caddy - to be used in place of nginx.
In Dokku 0.5.0, port proxying was decoupled from the `nginx-vhosts` plugin into the proxy plugin. Dokku 0.6.0 introduced the ability to map host ports to specific container ports. This allows other proxy software - such as HAProxy or Caddy - to be used in place of nginx.
## Usage
### Changing the proxy
The default proxy shipped with Dokku is `nginx`. It can be changed via the `proxy:set` command.
```shell
dokku proxy:set node-js-app caddy
```
```
-----> Setting config vars
DOKKU_APP_PROXY_TYPE: caddy
```
The proxy may also be set on a global basis. This is usually preferred as running multiple proxy implementations may cause port collision issues.
```shell
dokku proxy:set --global caddy
```
```
-----> Setting config vars
DOKKU_PROXY_TYPE: caddy
```
Changing the proxy does not stop or start any given proxy implementation. Please see the documentation for your proxy implementation for details on how to perform a change.
### Regenerating proxy config
In certain cases, your app proxy configs may drift from the correct config for your app. You may regenerate the config at any point via the `proxy:build-config` command. This command will trigger a rebuild for the configured proxy implementation (default: nginx) for a given app. The command may fail if there are no current web listeners for your app.
run [-e|--env KEY=VALUE] [--no-tty] <app> <cmd> # Run a command in a new container using the current app image
run:detached [-e|-env KEY=VALUE] [--no-tty] <app> <cmd> # Run a command in a new detached container using the current app image
run:detached [-e|-env KEY=VALUE] [--force-tty] <app> <cmd> # Run a command in a new detached container using the current app image
run:list [--format json|stdout] [<app>] # List all run containers for an app
run:logs <app|--container CONTAINER> [-h] [-t] [-n num] [-q] # Display recent log output for run containers
run:stop <app|--container CONTAINER> # Stops all run containers for an app or a specified run container
@@ -73,6 +73,12 @@ dokku run:detached node-js-app ls -lah
# returns the ID of the new container
```
To start a detached container with a tty, specify the `--force-tty` flag. Containers will still exit upon command termination, but can be attached to as long as they are running.
```shell
dokku run:detached --force-tty node-js-app bash
```
### Displaying one-off container logs
You can easily get logs of all one-off containers for an app using the `logs` command:
cron:list <app> [--format json|stdout] # List scheduled cron tasks for an app
cron:report [<app>] [<flag>] # Display report about an app
cron:run <app> <cron_id> [--detach] # Run a cron task on the fly
cron:list <app> [--format json|stdout] # List scheduled cron tasks for an app
cron:report [<app>] [<flag>] # Display report about an app
cron:run <app> <cron_id> [--detach] # Run a cron task on the fly
cron:set [--global|<app>] <key> <value> # Set or clear a cron property for an app
```
## Usage
@@ -46,10 +47,27 @@ When running scheduled cron tasks, there are a few items to be aware of:
- Scheduled cron tasks are performed within the app environment available at runtime. If the app image does not exist, the command may fail to execute.
- Schedules are performed on the hosting server's timezone, which is typically UTC.
- At this time, only the `PATH` and `SHELL` environment variables are specified in the cron template.
- A `MAILTO` value can be set via the `cron:set` command.
- Each scheduled task is executed within a one-off `run` container, and thus inherit any docker-options specified for `run` containers. Resources are never shared between scheduled tasks.
- 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 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.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
