# History
## 0.19.12
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.19.12/bootstrap.sh
sudo DOKKU_TAG=v0.19.12 bash bootstrap.sh
```
### New Features
- #3819: @josegonzalez Allow binding nginx to specific IPv4/IPv6 interfaces
- #3818: @josegonzalez Add support for host-mode networking
### Documentation
- #3814: @treyssatvincent Use dokku:report to for listing domains
- #3809: @josegonzalez Document nginx:show-conf
- #3650: @vincelwt Clarify resource management for docker-local scheduler
- #3806: @kimar Make default vhost example listen to ipv6
### Other
- #3816: @dependabot-preview[bot] chore(deps): bump handlebars from 4.6.0 to 4.7.1 in /tests/apps/.websocket.disabled
- #3815: @dependabot-preview[bot] chore(deps): bump handlebars from 4.5.3 to 4.6.0 in /tests/apps/.websocket.disabled
- #3811: @dependabot-preview[bot] chore(deps-dev): bump heroku/heroku-buildpack-php from 165 to 166 in /tests/apps/php
- #3812: @dependabot-preview[bot] chore(deps): bump jetty-servlet from 9.4.24.v20191120 to 9.4.25.v20191220 in /tests/apps/java
- #3810: @dependabot-preview[bot] chore(deps): bump monolog/monolog from 1.25.2 to 1.25.3 in /tests/apps/php
- #3808: @dependabot-preview[bot] chore(deps): [security] bump rack from 1.6.11 to 1.6.12 in /tests/apps/ruby
- #3807: @dependabot-preview[bot] chore(deps): bump google.golang.org/grpc from 1.25.1 to 1.26.0 in /tests/apps/gogrpc
- #3804: @dependabot-preview[bot] chore(deps-dev): bump heroku/heroku-buildpack-php from 164 to 165 in /tests/apps/php
In host-mode, there is no 'bridge' network by default, so we return an invalid IP address of 'no value'. Instead, return '127.0.0.1' for those containers.
As there can be custom schedulers, including scheduler-specific information on the resource management page can be a disingenuous - the values don't map to kubernetes, for example - and thus we should call out to the scheduler docs (and underlying docker docs) to make the mapping more clear.
# History
## 0.19.10
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.19.10/bootstrap.sh
sudo DOKKU_TAG=v0.19.10 bash bootstrap.sh
```
### Bug Fixes
- #3784: @josegonzalez Ensure checks attempts are tracked per-check instead of globally
### New Features
- #3793: @josegonzalez Omit DWARF symbol table and debug information from go binaries
- #3792: @josegonzalez Unify property function implementations
### Documentation
- #3712: @fruitl00p Added new plugin
### Other
- #3790: @dependabot-preview[bot] chore(deps): bump gunicorn from 20.0.3 to 20.0.4 in /tests/apps/python-flask
- #3791: @dependabot-preview[bot] chore(deps): bump gunicorn from 20.0.3 to 20.0.4 in /tests/apps/multi
- #3787: @dependabot-preview[bot] chore(deps): bump gunicorn from 20.0.2 to 20.0.3 in /tests/apps/multi
- #3788: @dependabot-preview[bot] chore(deps): bump gunicorn from 20.0.2 to 20.0.3 in /tests/apps/python-flask
- #3785: @dependabot-preview[bot] chore(deps): bump gunicorn from 20.0.0 to 20.0.2 in /tests/apps/python-flask
- #3786: @dependabot-preview[bot] chore(deps): bump gunicorn from 20.0.0 to 20.0.2 in /tests/apps/multi
- #3748: @dependabot-preview[bot] chore(deps): [security] bump express from 2.5.11 to 4.17.1 in /tests/apps/dockerfile-dokku-scale
- #3749: @dependabot-preview[bot] chore(deps): [security] bump express from 2.5.11 to 4.17.1 in /tests/apps/nodejs-express-noappjson
- #3747: @dependabot-preview[bot] chore(deps): [security] bump express from 2.5.11 to 4.17.1 in /tests/apps/config
- #3746: @dependabot-preview[bot] chore(deps): [security] bump express from 2.5.11 to 4.17.1 in /tests/apps/dockerfile-procfile
- #3741: @dependabot-preview[bot] chore(deps): [security] bump express from 2.5.11 to 4.17.1 in /tests/apps/nodejs-express
- #3783: @dependabot-preview[bot] chore(deps): bump jetty-servlet from 9.4.23.v20191118 to 9.4.24.v20191120 in /tests/apps/java
- #3777: @dependabot-preview[bot] chore(deps): [security] bump symfony/http-kernel from 3.4.32 to 3.4.35 in /tests/apps/php
- #3774: @dependabot-preview[bot] chore(deps): bump gunicorn from 19.9.0 to 20.0.0 in /tests/apps/python-flask
- #3779: @dependabot-preview[bot] chore(deps): bump monolog/monolog from 1.25.1 to 1.25.2 in /tests/apps/php
- #3782: @dependabot-preview[bot] chore(deps): bump jetty-servlet from 9.4.22.v20191022 to 9.4.23.v20191118 in /tests/apps/java
This will reduce the size of binaries in exchange for worse debugging output. This is acceptable for our users and worth it to save money on packagecloud package hosting - which is currently free under a given repository size.
Rather than reimplementing the property functions in two different languages - and potentially having compatibility issues - standardize on golang for the implementation through the use of a generated binary.
This also implements all the list functions for use with shell-based plugins.
Note that the interface to the prop binary is experimental, and it should not be used directly.
# History
## 0.19.9
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.19.9/bootstrap.sh
sudo DOKKU_TAG=v0.19.9 bash bootstrap.sh
```
### Bug Fixes
- #3781: @michaelshobbs Respect DOKKU_APP_USER in is_image_herokuish_based
### Other
- #3773: @dependabot-preview[bot] chore(deps): bump google.golang.org/grpc from 1.25.0 to 1.25.1 in /tests/apps/gogrpc
- #3772: @dependabot-preview[bot] chore(deps): bump gunicorn from 19.9.0 to 20.0.0 in /tests/apps/multi
- #3778: @dependabot-preview[bot] chore(deps): [security] bump symfony/http-foundation from 3.4.32 to 3.4.35 in /tests/apps/php
- #3768: @dependabot-preview[bot] chore(deps): bump google.golang.org/grpc from 1.24.0 to 1.25.0 in /tests/apps/gogrpc
# History
## 0.19.7
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.19.7/bootstrap.sh
sudo DOKKU_TAG=v0.19.7 bash bootstrap.sh
```
### Documentation
- #3765: @znz Fix typo in desc of is_tls13_available
### Other
- #3739: @safeforge dokku run do not supports interactive mode.
- #3762: @dependabot-preview[bot] chore(deps): bump handlebars from 4.4.5 to 4.5.1 in /tests/apps/.websocket.disabled
# History
## 0.19.6
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.19.6/bootstrap.sh
sudo DOKKU_TAG=v0.19.6 bash bootstrap.sh
```
### Other
- #3761: @pithyless Fix type-errors in dokku-installer.py
- #3759: @dependabot-preview[bot] chore(deps-dev): bump heroku/heroku-buildpack-php from 163 to 164 in /tests/apps/php
- #3758: @dependabot-preview[bot] chore(deps): bump jetty-servlet from 9.4.21.v20190926 to 9.4.22.v20191022 in /tests/apps/java
# History
## 0.19.3
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.19.3/bootstrap.sh
sudo DOKKU_TAG=v0.19.3 bash bootstrap.sh
```
### Bug Fixes
- #3753: @josegonzalez Always use python3 for the installer
### Other
- #3743: @dependabot-preview[bot] chore(deps): [security] bump express from 3.1.2 to 4.17.1 in /tests/apps/.websocket.disabled
- #3744: @dependabot-preview[bot] chore(deps): [security] bump handlebars from 1.0.12 to 4.4.5 in /tests/apps/.websocket.disabled
- #3750: @dependabot-preview[bot] chore(deps): [security] bump express from 2.5.11 to 4.17.1 in /tests/apps/dockerfile-procfile-bad
- #3745: @dependabot-preview[bot] chore(deps): [security] bump express from 3.3.8 to 4.17.1 in /tests/apps/gitsubmodules
- #3742: @dependabot-preview[bot] chore(deps): [security] bump express from 2.5.11 to 4.17.1 in /tests/apps/nodejs-express-noprocfile
- #3729: @dependabot-preview[bot] chore(deps): bump monolog/monolog from 1.12.0 to 1.25.1 in /tests/apps/php
- #3732: @dependabot-preview[bot] chore(deps): bump silex/silex from 1.2.3 to 2.2.4 in /tests/apps/php
- #3728: @dependabot-preview[bot] chore(deps): bump jetty-servlet from 7.6.0.v20120127 to 9.4.21.v20190926 in /tests/apps/java
- #3730: @dependabot-preview[bot] chore(deps): bump werkzeug from 0.15.6 to 0.16.0 in /tests/apps/python-flask
- #3737: @dependabot-preview[bot] chore(deps): bump express3-handlebars from 0.2.3 to 0.5.2 in /tests/apps/.websocket.disabled
- #3734: @dependabot-preview[bot] chore(deps-dev): bump heroku/heroku-buildpack-php from 59 to 163 in /tests/apps/php
- #3735: @dependabot-preview[bot] chore(deps): [security] bump symfony/http-kernel from 2.6.4 to 2.8.51 in /tests/apps/php
- #3723: @dependabot-preview[bot] chore(deps): bump sass-globbing from 1.1.1 to 1.1.5 in /tests/apps/multi
- #3731: @dependabot-preview[bot] chore(deps): bump jinja2 from 2.10.1 to 2.10.3 in /tests/apps/python-flask
- #3736: @dependabot-preview[bot] chore(deps): bump socket.io from 0.9.19 to 2.3.0 in /tests/apps/.websocket.disabled
- #3726: @dependabot-preview[bot] chore(deps): bump google.golang.org/grpc from 1.23.0 to 1.24.0 in /tests/apps/gogrpc
- #3727: @dependabot-preview[bot] chore(deps): bump maven-dependency-plugin from 2.4 to 3.1.1 in /tests/apps/java
- #3733: @dependabot-preview[bot] chore(deps): [security] bump symfony/http-foundation from 2.6.4 to 2.8.50 in /tests/apps/php
- #3720: @dependabot-preview[bot] chore(deps): bump compass from 1.0.1 to 1.0.3 in /tests/apps/multi
- #3721: @dependabot-preview[bot] chore(deps): bump sinatra from 1.4.4 to 1.4.8 in /tests/apps/ruby
- #3719: @dependabot-preview[bot] chore(deps): bump thin from 1.6.1 to 1.7.2 in /tests/apps/ruby
This actually breaks compatability since now we drop python2 support completely, but it's worth it to fix the weird issues with trying to support both versions.
Closes#3740Closes#3752
Refs #3717
Ideally python usage goes away - the dokku-installer should become a mandatory cli command, and the plugin is rewritten in golang - but for now, we need to use the correct binary when running dokku.
Closes#3714
This adds the Nginx Trust Proxy plugin
This plugin allows dokku to be run behind (multiple) proxies in and gives developers the opportunity to support reverse proxy layers
After a `dokku run` container is created and started, this plugin trigger will allow developers to run auxiliary commands in response to that container.
This feature is allows users to add extra label metadata to one-off containers. As this can interfere with Dokku internals if they shadow labels used by plugins, care should be taken to avoid the `com.dokku` or `org.label-schema` namespace.
Also proper name run containers so they don't get random names from docker...
This change allows supporting the openresty package as installed on Ubuntu 18.04 from the official openresty package repository, while also returning general nginx support.
Closes#3675
It may be desirable to keep the contents of the git directory for the build process. Certain build tools can extract extra information from the .git directory, and some workflows may require that the shipped artifact has the entire source code available locally for later usage.
This change refactors the compiled golang plugins into 3 distinct binaries:
- commands: already existing
- subcommands/subcommands: entrypoint into all subcommands
- triggers: entrypoint into all triggers
It then further symlinks triggers and subcommands to the built binaries. This results in both a much faster build process as well as smaller package size.
This PR uses the new syntax for commands introduced in Docker 1.13, making it a bit easier to understand just what a particular command is trying to do.
This also pushes the long-form syntax for docker command flags, which are also easier to understand at a glance.
The version in DOKKU_ROOT may be incorrect for docker-based installs if that directory is mounted from an external volume. Instead, pull it from the DOKKU_LIB_ROOT directory, and respect the STABLE_VERSION if specified (VERSION will be the entire version, including commit sha).
This will allow background processes to cleanup these files if they were unable to be cleaned up during a run of the dokku binary, as is the case for files copied by the docker binary when running in docker.
This will allow those triggers to insert and extract files from the sourcecode work directory. Note that changes are not committed to this directory, nor will they be reflected in the committed codebase.
# History
## 0.18.1
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.18.1/bootstrap.sh
sudo DOKKU_TAG=v0.18.1 bash bootstrap.sh
```
### New Features
- #3636: @josegonzalez Unify deb and rpm creation code
- #3635: @josegonzalez Upgrade herokuish to 0.5.2
# History
## 0.18.0
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.18.0/bootstrap.sh
sudo DOKKU_TAG=v0.18.0 bash bootstrap.sh
```
### Bug Fixes
- #3627: @josegonzalez Make image removal synchronous
- #3618: @josegonzalez Ensure the dokku-retire timer is properly installed
- #3614: @alexquick Validate args for config:set and config:unset
- #3605: @josegonzalez Handle case where there are empty newlines in the authorized_keys file
- #3603: @josegonzalez Drop extra % sign in common.LogVerboseQuiet
- #3597: @josegonzalez Allow default trace function to work
### New Features
- #3628: @josegonzalez Handle file copying in a secure and reliable fashion
- #3630: @josegonzalez Fix issue where push warning on bad branch was skipped
- #3629: @josegonzalez Avoid calling the user-auth trigger where possible
- #3626: @josegonzalez Builder plugins
- #3599: @josegonzalez Scope docker-cleanup to specific app
- #3589: @michaelshobbs Allow running Dokku in Docker
- #3607: @josegonzalez Purge cache using herokuish image
- #3602: @alexymik Create a 502 error page to automatically refresh if backend status changes
- #3600: @josegonzalez Refactor IsImageHerokuishBased to match shell version
### Documentation
- #3625: @josegonzalez Remove old reference to SPONSORS.md
- #3619: @josegonzalez Cleanup plugin creation docs
- #3612: @jayjun Improve testing docs
- #3613: @Lyelt Remove all uses of proxy_set_header Connection "upgrade"
- #3596: @josegonzalez Add missing hooks to events plugin and plugin triggers docs
### Tests
- #3610: @jayjun Correct Bats path in single tests
If you are running docker in docker, the permissions on the generated file are such that they may not be accessible by the normal dokku user. For dokku, it is good enough to ignore the failed removal.
If "docker cp" is run within docker, it seems the owner is root, resulting in other processes not being able to directly read the file without resorting to `cat` trickery. Doing this in a single place avoids the problem completely.
Asynchronous image removal would remove intermediate build images during the build process, causing intermittent build failures for users of multi-stage dockerfiles. While we still remove intermediate docker images that may be used in the current build, we now do so during the deploy, ensuring that there are no intermediate build failures in the future.
Closes#3474
As this trigger is always in the execution path, `plugn` starts and expensively checks to see if it can execute the trigger. Rather than call this on every invocation, skip the trigger if no non-core implementation exists.
This is a "one-shot" ability, meaning that it is highly discouraged for multiple plugins to implement the triggers.
The `builder-create-dokku-image` trigger is meant to modify the base DOKKU_IMAGE that will be used to build an application. A good use of the hook is to inject system packages by:
- calculating an image tag from the set of system packages
- checking that the image doesnt already exist
- creating the image if it does not
As the output is sent to stdout, we have to find an alternative way of fetching the new DOKKU_IMAGE. The `builder-dokku-image` trigger can output an image tag based on the calculated image tag. If no tag is output, then the DOKKU_IMAGE is used as is.
Using this pattern, users can efficiently modify the base image in use for an app without duplicating the work on every push. This is especially useful for package installation, where packages are required for app building, but may take a long time and can be error prone.
A builder plugin implements some method for 'building' artifacts from a given source code archive. This refactor moves the majority of the image building code into separate plugins, allowing us to implement other builders, but also simplifying the common pugin codebase.
Also move the pre-build-buildpack hook from the build-env plugin to builder-herokuish.
This reduces duplication and allows users to rely on global arguments to generate most labels needed.
The 'commit' command cannot have global arguments because the whitespace within the label change breaks string-based interpolation, and shell arrays cannot be exported.
The plugin creation docs were hard to follow, unnecessarily complicating issues for developers. The new format should make the recommendations clear, and align examples with the core code.
[ci skip]
In some cases, the cache directory may exist but there may be no app image to use for cache purging. This may be the case if the app was never deployed.
Instead of failing, we can simply use the configured herokuish image for clearing cache, as that image is the base image for anything that would have modified cache.
# History
## 0.17.9
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.17.9/bootstrap.sh
sudo DOKKU_TAG=v0.17.9 bash bootstrap.sh
```
### Bug Fixes
- #3593: @JakeAngell Fix nginx template for https in "Connection" header
### Documentation
- #3595: @josegonzalez Drop extra help output for trace
# History
## 0.17.8
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.17.8/bootstrap.sh
sudo DOKKU_TAG=v0.17.8 bash bootstrap.sh
```
### Bug Fixes
- #3591: @palfrey Allow SSH keys with no ending newline
### New Features
- #3587: @josegonzalez feat: drop make and gcc as dependencies
# History
## 0.17.6
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.17.6/bootstrap.sh
sudo DOKKU_TAG=v0.17.6 bash bootstrap.sh
```
### New Features
- #3578: @josegonzalez Allow omitting resource args by setting DOKKU_OMIT_RESOURCE_ARGS
This change allows operators to specify a DOCKER_BIN environment variable. This will specify a binary to run when executing docker, which is useful in cases where the 'docker' command being run must be modified in a way that would otherwise be invasive to Dokku, but minimalistic if done within a wrapper.
The post-delete hook will delete config, and thus scheduler-post-delete is the best place to actually delete resources where some local config may be necessary in order to reference resources.
# History
## 0.17.3
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.17.3/bootstrap.sh
sudo DOKKU_TAG=v0.17.3 bash bootstrap.sh
```
### Bug Fixes
- #3570: @znz Fix typos in trace help
### New Features
- #3574: @josegonzalez Add support for pulling app status from scheduler plugins
- #3571: @znz Simplify hostname_regex
`[a-z0-9\.\*-]+` includes `\.` and `[a-z0-9\*-]+`.
So I think `^([a-z0-9\.\*-]+\.)*[a-z0-9\*-]+$` means last char is `[a-z0-9\*-]`
and other optional chars are `[a-z0-9\.\*-]*`.
A DOKKU_SCALE file will always be used for managing the scale count for an app if it exists in a repository. As such, ps:scale usage should be disabled in those cases. This commit makes that more apparent.
Also document how to build a specific core plugin for testing purposes.
Closes#3544
This was removed in c9bbddcfcb as it was more complicated for operators to figure out _exactly_ which combination of limits/reservations would apply to their applications. Unfortunately, the documentation was never updated.
We may re-add this functionality in the future, but for now, cleaning up the docs is the best option.
[ci skip]
# History
## 0.16.4
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.16.4/bootstrap.sh
sudo DOKKU_TAG=v0.16.4 bash bootstrap.sh
```
### Bug Fixes
- #3547: @josegonzalez Correct retrieval of resource values for alternative schedulers
### New Features
- #3546: @josegonzalez Add ability to trigger an arbitrary plugin hook
This is useful in cases where the command output must be tested, but it is otherwise embedded in a specific part of the dokku core.
As the 'plugin' commands require root, this is safe to add to the core.
# History
## 0.16.3
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.16.3/bootstrap.sh
sudo DOKKU_TAG=v0.16.3 bash bootstrap.sh
```
### Bug Fixes
- #3541: @josegonzalez Handle case where image is null on first deploy
### New Features
- #3543: @josegonzalez Add ability to clear global domains
- #3517: @josegonzalez SSH key updates
- #3538: @josegonzalez Silence dokku run 'errors'
### Documentation
- #3523: @MarcDiethelm Add an example how to specify a Dockerfile for deployment
- #3539: @josegonzalez Warn users when ufw is enabled
If the subdomain is url-like, assume it is a valid url and use it for the default domain name. This allows users to specify the default domain for an app even if that is a subdomain of a global vhost.
Closes#3529
- <0.13.0: `docker inspect CONTAINER_ID`: WARNING, `docker inspect` will print environment variables for some commands, be sure you're not exposing any sensitive information when posting issues. You may replace these values with XXXXXXX.
- Container Inspect Output (if applicable) via `dokku ps:inspect APP_NAME`
- The nginx configuration (if applicable) via `dokku nginx:show-conf`
- Link to the exact repository being deployed (if possible/applicable):
- If a deploy is failing or behaving unexpectedly:
- Application name
@@ -40,5 +38,5 @@
- If using buildpacks, which custom buildpacks are in use
- If using a `Dockerfile`, the contents of that file
- If it exists, the contents of your `Procfile`.
- Output of failing Dokku commands after running `dokku traceon`
(BEWARE: `traceon` will print environment variables for some commands, be sure you're not exposing any sensitive information when posting issues. You may replace these values with XXXXXXX):
- Output of failing Dokku commands after running `dokku trace:on`
(BEWARE: `trace:on` will print environment variables for some commands, be sure you're not exposing any sensitive information when posting issues. You may replace these values with XXXXXX):
print"Listening on 0.0.0.0:{0}, CTRL+C to stop".format(port)
print("Listening on 0.0.0.0:{0}, CTRL+C to stop".format(port))
httpd.serve_forever()
@@ -294,6 +348,9 @@ PAGE = """
<small class="form-text text-muted">When enabled, Nginx will be run on port 80 and proxy requests to apps based on hostname.</small>
<small class="form-text text-muted">When disabled, a specific port will be setup for each application on first deploy, and requests to that port will be proxied to the relevant app.</small>
</div>
<div class="alert alert-warning small mt-3 d-{UFW_DISPLAY}" role="alert">
<strong>Warning:</strong> UFW is active. To allow traffic to specific ports, run <code>sudo ufw allow PORT</code> for the port in question.
@@ -34,7 +34,7 @@ Each "phase" has different expectations and limitations:
Please keep the above in mind when utilizing deployment tasks.
> To execute commands on the host during a release phase, see the [plugin creation documentation](/docs/development/plugin-creation) docs for more information on building your own custom plugin.
> To execute commands on the host during a release phase, see the [plugin creation documentation](/docs/development/plugin-creation.md) docs for more information on building your own custom plugin.
Installing a plugin is easy as well using the `plugin:install` command. This command will also trigger the `install` pluginhook on all existing plugins.
See the [Supported Resource Management Properties](/docs/advanced-usage/schedulers/docker-local.md#supported-resource-management-properties) section of the docker local scheduler documentation for more information on how each resource limit maps to Docker.
Resource limits and reservations are applied only during the `run` and `deploy` phases of an application, and will not impact the `build` phase of an application.
Running the `resource:limits` command without any flags will display the currently configured app reservation.
Running the `resource:limit` command without any flags will display the currently configured default app limits.
```shell
dokku resource:limits node-js-app
=====> resource limits node-js-app information
dokku resource:limit node-js-app
```
```
=====> resource limits node-js-app information [defaults]
cpu:
memory:
memory-swap: 100
network: 100
network-ingress:
network-egress:
```
This may also be combined with the `--process-type` flag to see app limits on a process-type level. Note that the displayed values are not merged with the defaults.
```shell
dokku resource:limit --process-type web node-js-app
```
```
=====> resource limits node-js-app information (web)
By default, Dokku does not limit any resources, though these can be specified at the server level via the `--global` flag on the `resource:limit` command.
```shell
dokku resource:limit --global --memory 200
```
```
=====> Setting default resource limits
memory: 200
```
This may also be combined with the `--process-type` flag to set global limits on a process-type level:
```shell
dokku resource:limit --global --memory 150 --process-type web node-js-app
```
```
=====> Setting default resource limits (web)
memory: 150
```
#### Displaying Global Resource Limits
Running the `resource:limit` command with only the `--global` flag will display the currently configured default limits.
```shell
dokku resource:limit --global
```
```
=====> resource limits default information
cpu:
memory: 200
memory-swap:
network:
network-ingress:
network-egress:
```
This may also be combined with the `--process-type` flag to see global limits on a process-type level:
```shell
dokku resource:limit --global --process-type web
```
```
=====> resource limits default information (web)
cpu:
memory-swap:
memory: 150
network-egress:
network-ingress:
network:
```
#### Clearing Resource Limits
In cases where the values are incorrect - or there is no desire to limit resources - resource limits may be cleared using the `resource:limit-clear` command.
By default, Dokku does not reserve any resources, though these can be specified at the server level via the `--global` flag on the `resource:reserve` command.
This may also be combined with the `--process-type` flag to see app reservations on a process-type level. Note that the displayed values are not merged with the defaults.
```shell
dokku resource:reserve --global --memory 200
dokku resource:reserve --process-type web node-js-app
```
```
=====> Setting default resource reservation
memory: 200
```
This may also be combined with the `--process-type` flag to set global reservations on a process-type level:
```shell
dokku resource:reserve --global --memory 150 --process-type web node-js-app
```
```
=====> Setting default resource reservation (web)
memory: 150
```
#### Displaying Global Resource Reservations
Running the `resource:reserve` command with only the `--global` flag will display the currently configured default reservation.
```shell
dokku resource:reserve --global
```
```
=====> resource reservation default information
cpu:
memory: 200
=====> resource reservation node-js-app information (web)
cpu: 100
memory: 100
memory-swap:
network:
network-ingress:
network-egress:
```
This may also be combined with the `--process-type` flag to see global reservations on a process-type level:
```shell
dokku resource:reserve --global --process-type web
```
```
=====> resource reservation default information (web)
cpu:
memory-swap:
memory: 150
network-egress:
network-ingress:
network:
```
#### Clearing Resource Reservations
In cases where the values are incorrect - or there is no desire to reserve resources - resource reservations may be cleared using the `resource:reserve-clear` command.
@@ -66,9 +66,13 @@ The `docker-local` scheduler supports a minimal list of resource _limits_ and _r
### Resource Limits
- cpu: (docker option: `--cpus`), and is specified in number of CPUs a process can access.
- memory: (docker option: `--memory`) and should be specified with a suffix of `b` (bytes), `k` (kilobytes), `m` (megabytes), `g` (gigabytes)
- See the ["CPU" section](https://docs.docker.com/config/containers/resource_constraints/#cpu) of the Docker Runtime Options documentation for more information.
- memory: (docker option: `--memory`) and should be specified with a suffix of `b` (bytes), `k` (kilobytes), `m` (megabytes), `g` (gigabytes).
- See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information.
- memory-swap: (docker option: `--memory-swap`) and should be specified with a suffix of `b` (bytes), `k` (kilobytes), `m` (megabytes), `g` (gigabytes)
- See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information.
### Resource Reservations
- memory: (docker option: `--memory-reservation`) and should be specified with a suffix of `b` (bytes), `k` (kilobytes), `m` (megabytes), `g` (gigabytes)
- See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information.
domains:add <app> <domain> [<domain> ...] # Add domains to app
domains:add-global <domain> [<domain> ...] # Add global domain names
domains:clear <app> # Clear all domains for app
domains:clear-global # Clear global domain names
domains:disable <app> # Disable VHOST support
domains:enable <app> # Enable VHOST support
domains:remove <app> <domain> [<domain> ...] # Remove domains from app
@@ -27,21 +28,10 @@ scheme://subdomain.domain.tld
The `subdomain` is inferred from the pushed application name, while the `domain.tld` is set during initial dokku configuration. It can then be modified with `dokku domains:add-global` and `dokku domains:remove-global`. This value is used as a default TLD for all applications on a host.
If a FQDN such as `other.tld` is used as the application name, the global virtualhost will be ignored and the resulting vhost URL for that application will be `other.tld`. The exception to this rule being that if the FQDN has the same ending as the default vhost (such as `subdomain.domain.tld`), then the entire FQDN will be treated as a subdomain. The application will therefore be deployed at `subdomain.domain.tld.domain.tld`.
If an FQDN such as `dokku.org` is used as the application name, the global virtualhost will be ignored and the resulting vhost URL for that application will be `dokku.org`.
You can optionally override this in a plugin by implementing the `nginx-hostname` plugin trigger. For example, you can reverse the subdomain with the following sample `nginx-hostname` plugin trigger:
You can optionally override this in a plugin by implementing the `nginx-hostname` plugin trigger. If the `nginx-hostname` plugin has no output, the normal hostname algorithm will be executed. See the [plugin trigger documentation](/docs/development/plugin-triggers.md#nginx-hostname) for more information.
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
APP="$1"; SUBDOMAIN="$2"; VHOST="$3"
NEW_SUBDOMAIN=`echo $SUBDOMAIN | rev`
echo "$NEW_SUBDOMAIN.$VHOST"
```
If the `nginx-hostname` plugin has no output, the normal hostname algorithm will be executed.
## Disabling VHOSTS
@@ -63,7 +53,7 @@ The domains plugin allows you to specify custom domains for applications. This p
dokku domains:add node-js-app dokku.me
# list custom domains for app
dokku domains node-js-app
dokku domains:report node-js-app
# clear all custom domains for app
dokku domains:clear node-js-app
@@ -88,17 +78,17 @@ dokku domains:report
```
=====> node-js-app domains information
Domains app enabled: true
Domains app vhosts: node-js-sample.dokku.org
Domains app vhosts: node-js-app.dokku.org
Domains global enabled: true
Domains global vhosts: dokku.org
=====> python-sample domains information
=====> python-app domains information
Domains app enabled: true
Domains app vhosts: python-sample.dokku.org
Domains app vhosts: python-app.dokku.org
Domains global enabled: true
Domains global vhosts: dokku.org
=====> ruby-sample domains information
=====> ruby-app domains information
Domains app enabled: true
Domains app vhosts: ruby-sample.dokku.org
Domains app vhosts: ruby-app.dokku.org
Domains global enabled: true
Domains global vhosts: dokku.org
```
@@ -132,6 +122,8 @@ Create the file at `/etc/nginx/conf.d/00-default-vhost.conf`:
config:export (<app>|--global) [--envfile] Export a global or app environment
config:get (<app>|--global) KEY Display a global or app-specific config value
config:keys (<app>|--global) [--merged] Show keys set in environment
config:set [--encoded] [--no-restart] (<app>|--global) KEY1=VALUE1 [KEY2=VALUE2 ...] Set one or more config vars
config:unset [--no-restart] (<app>|--global) KEY1 [KEY2 ...] Unset one or more config vars
config:export (<app>|--global) [--envfile] Export a global or app environment
config:keys (<app>|--global) [--merged] Show keys set in environment
config:bundle (<app>|--global) [--merged] Bundle environment into tarfile
```
> For security reasons - and as per [docker recommendations](https://github.com/docker/docker/issues/13490) - Dockerfile-based deploys have variables available *only* during runtime, as noted in [this issue](https://github.com/dokku/dokku/issues/1860).
@@ -89,10 +90,11 @@ The following list config variables have special meaning and can be set in a var
| `DOKKU_EVENTS_LOGFILE` | `$DOKKU_LOGS_DIR/events.log` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | Where the events log file is written to. |
| `DOKKU_APP_NAME` | none | `--app APP` flag | Name of application to work on. Respected by core plugins. |
| `DOKKU_APPS_FORCE_DELETE` | none | `--force` flag | Whether to force delete an application. Also used by other plugins for destructive actions. |
| `DOKKU_CHECKS_URL` | `http://dokku.viewdocs.io/dokku/deployment/zero-downtime-deploys/` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | Url displayed during deployment when no CHECKS file exists. |
| `DOKKU_DETACH_CONTAINER` | none | `--detach` flag | Whether to detach a container started via `dokku run`. |
| `DOKKU_QUIET_OUTPUT` | none | `--quiet` flag | Silences certain header output for `dokku` commands. |
| `DOKKU_RM_CONTAINER` | none | `dokku config:set` <br /> `--rm-container` flag <br /> `--rm` flag | Whether to keep `dokku run` containers around or not. |
| `DOKKU_TRACE` | none | `dokku traceon` <br /> `dokku trace false` <br /> `--trace` flag | Turn on very verbose debugging. |
| `DOKKU_TRACE` | none | `dokku trace:on` <br /> `dokku trace:off` <br /> `--trace` flag | Turn on very verbose debugging. |
| `DOKKU_APP_SHELL` | `/bin/bash` | `dokku config:set` | Allows users to change the default shell used by Dokku for `dokku enter` and execution of deployment tasks. |
@@ -113,6 +115,7 @@ The following list config variables have special meaning and can be set in a var
@@ -120,6 +123,7 @@ The following list config variables have special meaning and can be set in a var
| `DOKKU_SKIP_CLEANUP` | | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | When a deploy is triggered, if this is set to a non-empty value, then old docker containers and images will not be removed. |
| `DOKKU_START_CMD` | none | `dokku config:set` | Command to run instead of `/start $PROC_TYPE` |
| `DOKKU_SYSTEM_GROUP` | `dokku` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | System group to chown files as. |
| `DOKKU_SYSTEM_USER` | `dokku` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | System user to chown files as. |
| `DOKKU_WAIT_TO_RETIRE` | `60` | `dokku config:set` | After a successful deploy, the grace period given to old containers before they are stopped/terminated. This is useful for ensuring completion of long-running http connections. |
@@ -6,9 +6,32 @@ Dokku uses nginx as its server for routing requests to specific applications. By
nginx:access-logs <app> [-t] # Show the nginx access logs for an application (-t follows)
nginx:build-config <app> # (Re)builds nginx config for given app
nginx:error-logs <app> [-t] # Show the nginx error logs for an application (-t follows)
nginx:report [<app>] [<flag>] # Displays a nginx report for one or more apps
nginx:set <app> <property> (<value>) # Set or clear an nginx property for an app
nginx:show-conf <app> # Display app nginx config
nginx:validate [<app>] [--clean] # Validates and optionally cleans up invalid nginx configurations
```
## Binding to specific addresses
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.
## Checking access logs
You may check nginx access logs via the `nginx:access-logs` command. This assumes that app access logs are being stored in `/var/log/nginx/$APP-access.log`, as is the default in the generated `nginx.conf`.
@@ -45,6 +68,14 @@ In certain cases, your app nginx configs may drift from the correct config for y
dokku nginx:build-config node-js-app
```
## Showing the nginx config
For debugging purposes, it may be useful to show the nginx config. This can be achieved via the `nginx:show-conf` command.
```shell
dokku nginx:show-conf node-js-app
```
## Validating nginx configs
It may be desired to validate an nginx config outside of the deployment process. To do so, run the `nginx:validate` command. With no arguments, this will validate all app nginx configs, one at a time. A minimal wrapper nginx config is generated for each app's nginx config, upon which `nginx -t` will be run.
You can pass flags which will output only the value of the specific information you want. For example:
```shell
dokku certs:report node-js-sample --ssl-enabled
dokku certs:report node-js-app --ssl-enabled
```
## HSTS Header
@@ -125,7 +125,7 @@ Certain versions of nginx have bugs that prevent [HTTP/2](https://nginx.org/en/d
Your application has access to the HTTP headers `X-Forwarded-Proto`, `X-Forwarded-Port` and `X-Forwarded-For`. These headers indicate the protocol of the original request (HTTP or HTTPS), the port number, and the IP address of the client making the request, respectively. The default configuration is for Nginx to set these headers.
If your server runs behind an HTTP/S load balancer, then Nginx will see all requests as coming from the load balancer. If your load balancer sets the `X-Forwarded-` headers, you can tell Nginx to pass these headers from load balancer to your application by using the following [nginx custom template](/docs/configuration/nginx.md#customizing-the-nginx-configuration)
If your server runs behind an HTTP(S) load balancer, then Nginx will see all requests as coming from the load balancer. If your load balancer sets the `X-Forwarded-` headers, you can tell Nginx to pass these headers from load balancer to your application by using a [custom nginx template](/docs/configuration/nginx.md#customizing-the-nginx-configuration). The following is a simple example of how to do so.
1. All requests are terminated at the load balancer, and forwarded to Nginx
2. The load balancer is configured to send the `X-Forwarded-` headers (this may be off by default)
If it's possible to make HTTP/S requests directly to Nginx, bypassing the load balancer, or if the load balancer is not configured to set these headers, then it becomes possible for a client to set these headers to arbitrary values.
If it's possible to make HTTP(S) requests directly to Nginx, bypassing the load balancer, or if the load balancer is not configured to set these headers, then it becomes possible for a client to set these headers to arbitrary values.
This could result in security issue, for example, if your application looks at the value of the `X-Forwarded-Proto` to determine if the request was made over HTTPS.
The location of the `Dockerfile` may also be specified. If the location is changed, the repository **must also** have a `Dockerfile` in the root directory in order to trigger a dockerfile-based deploy.
@@ -76,3 +76,28 @@ This behavior can be disabled entirely on a per-app basis by setting the `rev-en
# override for a specific app
dokku git:set node-js-app rev-env-var ""
```
### Keeping the `.git` directory
By default, Dokku will remove the contents of the `.git` before triggering a build for a given app. This is generally a safe default as shipping the entire source code history of your app in the deployed image artifact is unnecessary as it increases bloat and potentially can leak information if there are any security issues with your app code.
To enable the `.git` directory, run the `git:set` command as follows:
```shell
# on the Dokku host
# keep the .git directory during builds
dokku git:set node-js-app keep-git-dir true
```
The default behavior is to delete this directory and it's contents. To revert to the default behavior, the `keep-git-dir` value can be set to either an empty string or `false`.
```shell
# on the Dokku host
# delete the .git directory during builds (default)
dokku git:set node-js-app keep-git-dir false
# delete the .git directory during builds (default)
@@ -5,7 +5,7 @@ Sometimes you need to either inspect running containers or run a one-off command
## Run a command in an app environment
```
run <app> <cmd> # Run a command in a new container using the current application image
run [ --env KEY=VALUE | -e KEY=VALUE ] <app> <cmd> # Run a command in a new container using the current application image
```
The `run` command can be used to run a one-off process for a specific command. This will start a new container and run the desired command within that container. Note that this container will be stay around even after command completes. The container will be the same container as was used to start the currently deployed application.
@@ -13,6 +13,9 @@ The `run` command can be used to run a one-off process for a specific command. T
```shell
# runs `ls -lah` in the `/app` directory of the application `node-js-app`
dokku run node-js-app ls -lah
# optionally, run can be passed custom environment variables
dokku run --env "NODE_ENV=development" --env "PATH=/custom/path" node-js-app npm run mytask
```
The `run` command can also be used to run a command defined in your Procfile:
@@ -43,6 +46,12 @@ dokku --rm-container run node-js-app ls -lah
dokku --rm run node-js-app ls -lah
```
Containers may have specific labels attached. In order to avoid issues with dokku internals, do not use any labels beginning with either `com.dokku` or `org.label-schema`.
```shell
dokku --label=com.example.test-label=value run node-js-app ls -lah
```
Finally, you may wish to run a container in "detached" mode via the `--detach` Dokku flag. Running a process in detached mode will immediately return a `CONTAINER_ID`. It is up to the user to then further manage this container in whatever manner they see fit, as Dokku will *not* automatically terminate the container.
@@ -123,7 +123,7 @@ To specify checks, add a `CHECKS` file to the root of your project directory. Th
- comments (lines starting with #)
- empty lines
> For Dockerfile-based deploys, the file *must* be in `/app/CHECKS` within the container. `/app` is used by default as the root container directory for buildpack-based deploys.
> For Dockerfile and Docker Image based deploys, the file *must* be in the `WORKDIR` directory of the built image. `/app` is used by default as the root container directory for buildpack-based deploys.
### Check instructions
@@ -327,7 +327,6 @@ curl: (7) Failed to connect to 172.17.0.155 port 5000: Connection refused
A plugin can be a simple implementation of [triggers](/docs/development/plugin-triggers.md) or can implement a command structure of its own. Dokku has no restrictions on the language in which a plugin is implemented; it only cares that the plugin implements the appropriate [commands](/docs/development/plugin-creation.md#command-api) or [triggers](/docs/development/plugin-triggers.md) for the API. **NOTE:** any file that implements triggers or uses the command API must be executable.
If you create your own plugin:
When creating custom plugins:
1. Take a look at [the plugins shipped with Dokku](/docs/community/plugins.md) and hack away!
2. Check out the [list of triggers](/docs/development/plugin-triggers.md) your plugin can implement
3. Upload your plugin to GitHub with a repository name following the `dokku-<name>` convention (e.g. `dokku-mariadb`)
4. Edit [this page](/docs/community/plugins.md) and add a link to your plugin
2. Check out the [list of triggers](/docs/development/plugin-triggers.md) the plugin can implement
3. Upload the plugin to GitHub with a repository name following the `dokku-<name>` convention (e.g. `dokku-mariadb`)
4. Edit [this page](/docs/community/plugins.md) and add a link to the plugin
5. Subscribe to the [dokku development blog](http://progrium.com) to be notified about API changes and releases
## Compilable plugins (Golang, Java(?), C, etc.)
When developing a plugin, you must implement the `install` trigger such that it outputs the built executable(s) using a directory structure that implements the plugin's desired command and/or triggers the API. See the [smoke-test-plugin](https://github.com/dokku/smoke-test-plugin) for an example.
When developing a plugin, the `install` trigger must be implemented such that it outputs the built executable(s) using a directory structure that implements the plugin's desired command and/or triggers the API. See the [smoke-test-plugin](https://github.com/dokku/smoke-test-plugin) for an example.
## Command API
There are 3 main integration points: `commands`, `subcommands/default`, and `subcommands/<command-name>`.
### `commands`
Primarily used to supply the plugin's usage/help output. (i.e. [plugin help](https://github.com/dokku/dokku/tree/master/plugins/plugin/commands)).
### `subcommands/default`
Implements the plugin's default command behavior. (i.e. [`dokku plugin`](https://github.com/dokku/dokku/tree/master/plugins/plugin/subcommands/default)).
### `subcommands/<command-name>`
Implements the additional command interface and will translate to `dokku plugin:cmd` on the command line. (i.e. [`dokku plugin:install`](https://github.com/dokku/dokku/tree/master/plugins/plugin/subcommands/install)).
# Plugin Building Tips
## Always create a `plugin.toml`
The `plugin.toml` file is used to describe the plugin in help output, and helps users understand the purpose of the plugin. This _must_ have a description and a version. The version _should_ be bumped at every plugin release.
```toml
[plugin]
description = "dokku example plugin"
version = "0.1.0"
[plugin.config]
```
## Files should be executable
Commands, subcommands, triggers and source shell scripts should all be executable. On a Unix-like machine, the following command can be used to make them executable:
```shell
chmod +x path/to/file
```
Non-executable commands, subcommands, and triggers will be ignored.
## Use the `pipefail` bash option
Consider whether to include the `set -eo pipefail` option. Look at the following example:
dokku_log_fail "user/repo image not found... Did you run 'dokku plugin:install'?"
fi
```
If `user/repo` doesn't exist, Dokku exits just before the `awk` command and the `dokku_log_fail` message will never go to `STDOUT`. printed with echo. The `set -e` option should be used in this case.
Here is the `help` entry for `set`:
```
help set
Options:
-e Exit immediately if a command exits with a non-zero status.
-o option-name
pipefail the return value of a pipeline is the status of
the last command to exit with a non-zero status,
or zero if no command exited with a non-zero status
```
## Support trace mode
Trace mode is useful for getting debugging output from plugins when the `--trace` flag is specified or `dokku trace:on` is triggered. This should be done at the top of each shell script:
```shell
#!/usr/bin/env bash
set -eo pipefail
[[ $DOKKU_TRACE ]] && set -x
```
In the above example, the third line enables bash's debug mode, which prints command traces before executing command.
## Verify the existence of dependencies
If a plugin depends on a specific command-line tool, check whether that tool exists before utilizing it. Either `command -v` or `which` may be used to do so:
```shell
# `command -v` example
if ! command -v "nginx" &>/dev/null; then
log-fail "Missing nginx, install it"
fi
# `which` example
if ! which nginx >/dev/null 2>&1; then
log-fail "Missing nginx, install it"
fi
```
In cases where a dependency should be installed before the plugin can be used at all, use the `dependencies` plugin trigger to install the dependency.
## Implement a help command
For plugins which expose commands, implement a `help` command. This may be empty, but should contain a listing of all available commands.
Commas - `,` - are used in the help output for columnizing output. Verify that the plugin conforms to the spec by running `dokku help --all` and manually verifying the output.
See the sample plugin below for an example.
## Namespace commands
All commands *should* be namespaced. In cases where a core plugin is overriden, the plugin _may_ utilize the a namespace in use by the core, but generally this should be avoided to reduce confusion as to where the command is implemented.
## Implement a proper catch-all command
As of 0.3.3, a catch-all should be implemented that exits with a `DOKKU_NOT_IMPLEMENTED_EXIT` code. This allows Dokku to output a `command not found` message.
See the sample plugin below for an example.
## Set app config without restarting
In the case that a plugin needs to set app configuration settings and a restart should be avoided (default Heroku-style behavior) these "internal" commands provide this functionality:
To allow other plugins access to (some of) a plugin's functionality, functions can expose by including a `functions` file in the plugin for others to source. All functions in that file should be considered publicly accessible by other plugins.
Any functions that must be kept private should reside in the plugin's `trigger/` or `commands/` directories. Other files may also be used to hide private functions; the official convention for hiding private functions is to place them an `internal-functions` file.
## Use helper functions to fetch app images
> New as of 0.4.0
Dokku allows image tagging and deployment of tagged images. This means hard-coding the `$IMAGE` as `dokku/$APP` is no longer sufficient.
Plugins should use `get_running_image_tag()` and `get_app_image_name()` as sourced from `common/functions`. See the [plugin triggers](/docs/development/plugin-triggers.md) doc for examples.
> **Note:** This is only for plugins that are not `pre/post-build-*` plugins
## Use `$DOCKER_BIN` instead of `docker` directly
> New as of 0.17.5
Certain systems may require a wrapper function around the `docker` binary for proper execution. Utilizing the `$DOCKER_BIN` environment variable when calling docker for those functions is preferred.
```shell
# good
"$DOCKER_BIN" container run -d $IMAGE /bin/bash -e -c "$COMMAND"
# bad
docker run -d $IMAGE /bin/bash -e -c "$COMMAND"
```
## Include labels for all temporary containers and images
> New as of 0.5.0
As of 0.5.0, labels are used to help cleanup intermediate containers with `dokku cleanup`. Plugins that create containers and images should add the correct labels to the `build`, `commit`, and `run` docker commands.
Note that where possible, a label `com.dokku.app-name=$APP` - where `$APP` is the name of the app - should also be included. This enables `dokku cleanup APP` to cleanup the specific containers for a given app.
"$DOCKER_BIN" container run "--label=com.dokku.app-name=${APP}" $DOKKU_GLOBAL_RUN_ARGS ...
```
## Copy files from the built image using `copy_from_image`
Avoid copying files from running containers as these files may change over time. Instead copy files from the image built during the deploy process. This can be done via the `copy_from_image` helper function. This will correctly handle various corner cases in copying files from an image.
Files are copied from the `/app` directory - for images built via buildpacks - or `WORKDIR` - for images built via Dockerfile.
## Avoid calling the `dokku` binary directly
> New as of 0.6.0
Plugins should **not** call the `dokku` binary directly from within plugins because clients using the `--app` argument are potentially broken when doing so.
Plugins should instead source the `functions` file for a given plugin when attempting to call Dokku internal functions.
# Sample plugin
The below plugin is a dummy `dokku hello` plugin.
Each plugin requires a `plugin.toml` descriptor file with the following required fields:
# Use the following lines to reorder args into "$cmd $DOKKU_APP_NAME $@""
local argv=("$@")
declare desc="prints Hello world"
declare cmd="hello:world" argv=("$@")
[[ ${argv[0]} == "$cmd" ]] && shift 1
[[ -n $DOKKU_APP_NAME ]] && set -- $DOKKU_APP_NAME $@
set -- $cmd $@
##
[[ -z $2 ]] && dokku_log_fail "Please specify an app to run the command on"
verify_app_name "$2"
local APP="$2";
echo "Hello world"
}
@@ -91,7 +276,8 @@ hello_world_cmd "$@"
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
set -eo pipefail
[[ $DOKKU_TRACE ]] && set -x
case "$1" in
help | hello:help)
@@ -126,58 +312,3 @@ help_content
esac
```
Each plugin requires a `plugin.toml` descriptor file with the following required fields:
```toml
[plugin]
description = "dokku hello plugin"
version = "0.1.0"
[plugin.config]
```
# A few notes:
- Remember to `chmod +x` your executable files
- Always support `DOKKU_TRACE` as per the 2nd line of the above example
- If your command depends on an application, include a check for whether that application exists (see the above example)
- You must implement a `help` command, though you may leave it empty. Also, you must use commas (`,`) in the command syntax to support output in columns
- Commands **should** be namespaced
- As of 0.3.3, a catch-all should be implemented that exits with a `DOKKU_NOT_IMPLEMENTED_EXIT` code. This allows Dokku to output a `command not found` message.
- Consider whether you want to include the `set -eo pipefail` option. Look at the following example :
dokku_log_fail "user/repo image not found... Did you run 'dokku plugin:install'?"
fi
```
If `user/repo` doesn't exist, Dokku exits just before the `awk` command and the `dokku_log_fail` message will never go to `STDOUT`. printed with echo. You would want to use `set -e` in this case.
Here is the `help` entry for `set`:
```
help set
Options:
-e Exit immediately if a command exits with a non-zero status.
-o option-name
pipefail the return value of a pipeline is the status of
the last command to exit with a non-zero status,
or zero if no command exited with a non-zero status
```
- In the case that your plugin needs to set application configuration settings and you want to avoid having to restart (default Heroku-style behavior) these "internal" commands provide this functionality:
- If you want to allow other plugins access to (some of) your plugin's functionality, you can expose this by including a `functions` file in your plugin for others to source
- You should consider all functions in that file to be publicly accessible by other plugins
- Any functions you want to keep private should reside in your plugin's `trigger/` or `commands/` directories
- As of 0.4.0, Dokku allows image tagging and deployment of tagged images
- This means hard-coding the `$IMAGE` as `dokku/$APP` is no longer sufficient
- You should now use `get_running_image_tag()` and `get_app_image_name()` as sourced from `common/functions` (see the [plugin triggers](/docs/development/plugin-triggers.md) doc for examples). **Note:** This is only for plugins that are not `pre/post-build-*` plugins
- As of 0.5.0, we use container labels to help cleanup intermediate containers with `dokku cleanup
- This means that if you manually call `docker run`, you should include `$DOKKU_GLOBAL_RUN_ARGS` to ensure your intermediate containers are labeled correctly
- As of 0.6.0, you should not **not** call the `dokku` binary directly from within plugins because clients using the `--app` argument are potentially broken when doing so (as well as other issues)
- You should instead source the `functions` file for a given plugin when attempting to call Dokku internal functions
@@ -29,6 +29,21 @@ The following plugin triggers describe those available to a Dokku installation.
> The example plugin trigger code is not guaranteed to be implemented as in within dokku, and are merely simplified examples. Please look at the Dokku source for larger, more in-depth examples.
- 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)`
Dokku has a full test suite to assist in quick iterating development. These tests include a linter using [shellcheck](https://github.com/koalaman/shellcheck), functional unit tests using the [bats testing framework](https://github.com/sstephenson/bats), and a deployment suite of example apps that use the most popular languages and frameworks.
Dokku has a full test suite to assist in quick iterating development. These tests include a linter using [shellcheck](https://github.com/koalaman/shellcheck), functional unit tests using the [Bats testing framework](https://github.com/bats-core/bats-core), and a deployment suite of example apps that use the most popular languages and frameworks.
We maintain the Dokku test harness within the `tests` directory:
@@ -11,13 +11,13 @@ We maintain the Dokku test harness within the `tests` directory:
All pull requests have tests run against them on [CircleCI](https://circleci.com/), a continuous integration platform that provides Docker support for Ubuntu Trusty 14.04.
If you wish to skip tests for a particular commit - e.g. Documentation changes - you may add the `[ci skip]` designator to your commit message. Commits that *should* be tested but have the above designator will not be merged.
If you wish to skip tests for a particular commit, e.g. documentation changes, you may add the `[ci skip]` designator to your commit message. Commits that _should_ be tested but have the above designator will not be merged.
While we do provide official packages for a variety of platforms, as our test suite currently runs on Ubuntu Trusty 14.04, we only provide official installation support for that platform.
## Local Test Execution
- Setup Dokku in a [vagrant vm](/docs/getting-started/install/vagrant.md)
- Setup Dokku in a [Vagrant VM](/docs/getting-started/install/vagrant.md).
- Run the following to setup tests and execute them:
```shell
@@ -29,8 +29,8 @@ While we do provide official packages for a variety of platforms, as our test su
# execute the entire test suite (linter, bats tests, and app deployment tests)
make test
# run linter & update vagrant Dokku install from local git clone
make lint copyfiles
# run linter
make lint
# execute all bats tests
make unit-tests
@@ -39,6 +39,16 @@ While we do provide official packages for a variety of platforms, as our test su
make deploy-tests
```
After making changes to your local Dokku clone, don't forget to update the Vagrant Dokku install.
```shell
# update vagrant dokku install from local git clone
make copyfiles
# build a specific plugin
make go-build-plugin copyplugin PLUGIN_NAME=apps
```
Additionally you may run a specific app deployment tests with a target similar to:
Some special characters are translated in the test listing - specifically the characters `( ) :` - while others are not. The fuzzy matching happens on the test names listed when no second character is invoked, so executing a test with a more specific name will work as expected.
Some special characters are translated in the test listing, specifically the characters `( ) :`, while others are not. The fuzzy matching happens on test names as listed by this script, so executing a test with a more specific name will work as expected.
@@ -46,7 +46,7 @@ sudo BUILD_STACK=true STACK_URL=https://github.com/gliderlabs/herokuish.git make
## Skipping Herokuish installation
The Herokuish package is recommended but not required if not using Heroku buildpacks for deployment. Debian-based OS users can run the bootstrap installer via `sudo DOKKU_NO_INSTALL_RECOMMENDS=true bash bootstrap.sh` to skip the dependency. Please note that this will _also_ skip installation of other recommended dependencies.
The Herokuish package is recommended but not required if not using Heroku buildpacks for deployment. Debian-based OS users can run the bootstrap installer via `sudo DOKKU_NO_INSTALL_RECOMMENDS=" --no-install-recommends " bash bootstrap.sh` to skip the dependency. Please note that this will _also_ skip installation of other recommended dependencies.
[DigitalOcean](https://www.digitalocean.com/products/compute/) offers a pre-installed Dokku image. You can run this image on any sized Droplet, although larger Droplets will allow you to run larger applications.
- The global hostname is set to `dokku.me` on boot.
- The container name is dokku.
- Container SSH port 22 is exposed on the host as 3022.
- Container HTTP port 80 is exposed on the host as 8080.
- Container HTTPS port 443 is exposed on the host as 8443.
- Data within the container is stored on the host within the `/var/lib/dokku` directory.
- The docker socket is mounted into container
Application repositories, plugin config, and plugin data is persisted to disk within the specified host directory for `/var/lib/dokku`.
To install custom plugins, create a `plugin-list` file in the host's `/var/lib/dokku` directory. The plugins listed herein will be automatically installed by Dokku on container boot. This file should be the following format:
```yaml
plugin_name: repository_url
```
An example for installing the postgres and redis plugins follows:
By default, Dokku will constrain the amount of output displayed for any given command run. The verbosity of output can be increased by enabling trace mode. Trace mode will turn on the `set -x` flag for bash plugins, while other plugins are free to respect the environment variable `DOKKU_TRACE` and log differently as approprate. Trace mode can be useful to see _where_ plugins are running commands that would otherwise be unexpected.
To enable trace mode, run `trace:on`
```shell
dokku trace:on
```
```
-----> Enabling trace mode
```
Trace mode can be disabled with `trace:off`
```shell
dokku trace:off
```
```
-----> Disabling trace mode
```
## Common Problems
__Symptom:__ I deployed my app but I am getting the default nginx page.
__Solution:__
@@ -41,22 +74,7 @@ __Symptom:__ I want to deploy my app, but while pushing I get the following erro
__Solution:__
The `remote rejected` error does not give enough information. Anything could have failed.
To enable Dokku tracing, simply run the following command:
```shell
# since 0.3.9
dokku trace on
```
In versions older than 0.3.9, you can create a `/home/dokku/dokkurc` file containing the following:
```shell
export DOKKU_TRACE=1
```
This will trace all of Dokku's activity. If this does not help you, create a [gist](https://gist.github.com) containing the full log, and create an issue.
The `remote rejected` error does not give enough information. Anything could have failed. Enable trace mode and begin debugging. If this does not help you, create a [gist](https://gist.github.com) containing the full log, and create an issue.
proxy:ports <app> # List proxy port mappings for app
proxy:ports-set <app> <scheme>:<host-port>:<container-port> [<scheme>:<host-port>:<container-port>...] # Set proxy port mappings for app
proxy:ports-add <app> <scheme>:<host-port>:<container-port> [<scheme>:<host-port>:<container-port>...] # Add proxy port mappings for app
proxy:ports-clear <app> # Clear all proxy port mappings for app
proxy:ports-remove <app> <host-port> [<host-port>|<scheme>:<host-port>:<container-port>...] # Unset proxy port mappings for app
proxy:ports <app> # List proxy port mappings for an app
proxy:ports-add <app> <scheme>:<host-port>:<container-port> [<scheme>:<host-port>:<container-port>...] # Add proxy port mappings to an app
proxy:ports-clear <app> # Clear all proxy port mappings for an app
proxy:ports-remove <app> <host-port> [<host-port>|<scheme>:<host-port>:<container-port>...] # Remove specific proxy port mappings from an app
proxy:ports-set <app> <scheme>:<host-port>:<container-port> [<scheme>:<host-port>:<container-port>...] # Set proxy port mappings for an app
```
In Dokku 0.5.0, port proxying was decoupled from the `nginx-vhosts` plugin into the proxy plugin. Dokku 0.6.0 introduced the ability to map host ports to specific container ports. In the future this will allow other proxy software - such as HAProxy or Caddy - to be used in place of nginx.
## Usage
> Warning: Mapping alternative ports may conflict with the active firewall installed on your server or hosting provider. Such software includes - but is not limited to - AWS Security Groups, iptables, and UFW. Please consult the documentation for those softwares as applicable.
@@ -124,7 +124,7 @@ For buildpack deployments, your application *must* respect the `PORT` environmen
> Changed as of 0.5.0
Dokku's default proxy implementation - nginx - only supports HTTP request proxying. At this time, we do not support proxying plain TCP or UDP ports. UDP ports can be exposed by disabling the nginx proxy with `dokku proxy:disable myapp`. If you would like to investigate alternative proxy methods, please refer to our [proxy management documentation](/docs/advanced-usage/proxy-management.md).
Dokku's default proxy implementation - nginx - supports HTTP and GRPC request proxying. At this time, we do not support proxying plain TCP or UDP ports. UDP ports can be exposed by disabling the nginx proxy with `dokku proxy:disable myapp`. If you would like to investigate alternative proxy methods, please refer to our [proxy management documentation](/docs/advanced-usage/proxy-management.md).
@@ -69,7 +69,8 @@ The proxy port scheme is as follows:
- `SCHEME:HOST_PORT:CONTAINER_PORT`
The scheme metadata can be used by proxy implementations in order to properly handle proxying of requests. For example, the built-in `nginx-vhosts` proxy implementation supports both the `http` and `https` schemes.
The scheme metadata can be used by proxy implementations in order to properly handle proxying of requests. For example, the built-in `nginx-vhosts` proxy implementation supports the `http`, `https`, `grpc` and `grpcs` schemes.
For the `grpc` and `grpcs` see [nginx blog post on grpc](https://www.nginx.com/blog/nginx-1-13-10-grpc/).
Developers of proxy implementations are encouraged to use whatever schemes make the most sense, and ignore configurations which they do not support. For instance, a `udp` proxy implementation can safely ignore `http` and `https` port mappings.
Loaded 100 of 343 files, more 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.