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
# History
## 0.16.1
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.16.1/bootstrap.sh
sudo DOKKU_TAG=v0.16.1 bash bootstrap.sh
```
### New Features
- #3532: @josegonzalez refactor: allow the scheduler to decide if an app is deployed
### Documentation
- #3530: @jhstatewide Updated info about supported Ubuntu versions
The previous output required too much parsing to be used in an automated fashion. This change makes that a bit easier, without sacrificing usability.
Note that the output is quite a bit different from heroku. This is purposeful as we do not have the concept of dynos.
Closes#3520
Use `GIT_STRATEGY: none` in `stop_review_app` to make job work after successful
merges and when the branch was deleted.
Without this, the application is not stopped when the branch is deleted on merge as the runner pulls the git repository by default, but cannot find the tree in this moment.
[skip ci]
# History
## 0.15.5
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.15.5/bootstrap.sh
sudo DOKKU_TAG=v0.15.5 bash bootstrap.sh
```
### New Features
- #3511: @josegonzalez Add json output to config:export
### Documentation
- #3510: @josegonzalez Remove SPONSORS doc in favor of OpenCollective
- #3509: @Neamar Missing space in markdown formatting
- #3507: @renestalder Fix GitLab CI examples
This change adds json output as both key/value as well as a list of objects. The former can be used in quick scripting environments, while the latter allows higher-level languages to have a bit more structure around how environment variables are declared. Specifically, systems such as kubernetes understand the latter method, while the former can be used within Nomad job files.
The GitLab CI examples used `$CI_ENVIRONMENT_SLUG` for defining the environment names
of the deploy jobs. But this variable is actually the OUTPUT of setting the environment name,
thus, it tries to reference itself, but does not exist in that moment.
The correct way to set this is to use `$CI_COMMIT_REF_NAME` as based on the documentation
of GitLab's dynamic environments.
With the introduciton of procfile-util, scaling a non-existent process to 0 was disabled. This brings back that functionality, allowing users to scale all processes to 0. This is especially useful when a user has accidentally scaled a non-existent process up, causing deploys to fail without any way to revert outside of manually editing files.
Closes#3428
The `domains` command previously had this functionality, but is deprecated, and thus we should provide an alternative method of presenting the information.
This moves the base image from Xenial to Bionic, which is the latest supported LTS release of Ubuntu. Note that all previous releases of herokuish are no longer supported, and users are encouraged to upgrade where possible.
In the case of upgrades, a 'dokku repo:purge-cache APP' should be called for each app, or built applications may include code linked to non-ABI compatible libraries due to the OS upgrade.
This sort of change is usually performed _only_ during a minor release, but as the window since the release is fairly small, the risk to our users is negligible in comparison to the inability to stay on a maintained herokuish release.
Global limits make it harder to reason about the inheritance in the system. Rather than support global limits, Dokku should provide primitives to automatically set them on an app at provision time, or explicitly set them for an app. Both of these are likely best suited for a higher-level provisioner, or a community plugin.
This will allow validation to work if the default logging locations cannot be written to but the configuration is otherwise okay. This will be the case for users with custom nginx configurations that log to other places, such as syslog.
When setting environment variables, we should respect a passed `--quiet` flag - and the respective environment variable. This will allow users to have a nicer experience when using the config functions within their own plugins.
Rather than always assuming a missing `WORKDIR` means herokuish, we instead inspect the image to verify that it is. If it is, then and _only_ then do we set WORKDIR. Otherwise, we respect the decision of `docker cp` to execute from within the last known `WORKDIR` context, which is inherited at the image level, not image metadata level.
Additionally, speed up `is_image_herokuish_based` by inspecting the environment variables on the image. When there is a "USER=herokuishuser", we can more or less safely assume it is an image that Dokku built, and is therefore a herokuish image. While possible, it would be very strange if a non-herokuish image had this environment variable set, so it is a relatively safe change.
- ensure nginx is always installed
- install nginx in the same way for apt-using distros
- do not install software-properties-common or python-software-properties if not needed
Log output for ps:retire was previously a bit too verbose because we weren't handling the following edge-cases.
- if a container doesn't exist, remove it from the dead container list
- ensure a restarting container is properly killed
- only attempt to stop/kill if the state is not dead or exited
- do not attempt to do anything if the container doesn't exist
- correct check on running state
Previously, if running 'dokku report --all', the early exit 1 in apps:report would cause the entire process to bail, resulting in a partial report. Instead, we exit 0, allowing plugn to continue.
Technically a non-deployed app is not an error case at this position.
# History
## 0.14.1
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.14.1/bootstrap.sh
sudo DOKKU_TAG=v0.14.1 bash bootstrap.sh
```
### Bug Fixes
- #3386: @josegonzalez Ensure we can deploy code when there is no pre or post-deploy script defined
# History
## 0.14.0
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.14.0/bootstrap.sh
sudo DOKKU_TAG=v0.14.0 bash bootstrap.sh
```
### Bug Fixes
- #3384: @josegonzalez fix: use updated gpg key for apt repository
- #3382: @josegonzalez Set cleanup to global when no application is specified
- #3350: @josegonzalez Do not build the proxy config when there are no app listeners
- #3366: @josegonzalez Add post-app-clone-setup to network clean make target
- #3349: @josegonzalez Ensure apps are cleanly cloned
- #3356: @josegonzalez Move storage directory into DOKKU_LIB_ROOT
- #3341: @baikunz Select only default dokku network IP
- #3348: @josegonzalez Use correct name for packagecloud token when running CI commands
- #3339: @josegonzalez Properly check args when calling cleanup globally
- #3344: @josegonzalez Allow running dokku report without needing an interactive shell
### New Features
- #3381: @josegonzalez Add support for the Procfile release command
- #3380: @josegonzalez Install stable docker when using bootstrap script
- #3378: @josegonzalez Make admin setup UI look nicer
- #3369: @josegonzalez Pull invalid nginx configuration when the nginx configs fail to validate
- #3371: @josegonzalez Add tests section to changelog
- #3358: @josegonzalez Image tag deploy workflow cleanup
- #3351: @josegonzalez Do not clone URLS and VHOST files to new apps
- #3357: @josegonzalez Add support for building arbitrary releases
- #3354: @josegonzalez Drop default dhparam key size to 2048
- #3347: @josegonzalez Upgrade herokuish
- #3352: @josegonzalez Increase security of default SSL setup
- #3353: @josegonzalez Normalize tests
- #3345: @josegonzalez Allow triggering the full report for all apps via --all flag
- #3346: @josegonzalez Always overwrite the dokku.conf file for nginx
### Documentation
- #3377: @josegonzalez Remove team member section on homepage in favor of sponsor section
- #3376: @josegonzalez Switch from rawgit to jsdelivr
- #3365: @josegonzalez Remove extra tags:create call from docs
### Tests
- #3379: @josegonzalez Run mvdan/shfmt on test runs
- #3370: @josegonzalez Add junit support to shellcheck output
- #3308: @josegonzalez Add timing info to test runs on CircleCI
- #3367: @josegonzalez Run tests from built artifact
- #3368: @josegonzalez Balance circleci tests
- #3363: @josegonzalez Add a wrapper for invoking a single test
- #3362: @josegonzalez Allow tests to be run from any directory
- #3360: @josegonzalez Switch to bats-core
- #3361: @josegonzalez Do not generate dhparam for tests
### Other
- #3279: @fruitl00p Make sure the universe repo is loaded into APT
This script previously ran through the docker installation process with the edge channel on each run. Instead, we only run the docker installation if docker is not available. In addition, we force set the channel to stable, ensuring the script installs the correct channel for stable docker installations.
Closes#3269
While I do not agree with _every_ style change, this will force Dokku to have consistent formatting across all shell scripts, which is arguably a Good Thing™.
The command used to reprocess everything is:
```shell
shfmt -l -bn -ci -i 2 -w .
```
The initial admin setup UI is a bit of a hack, but could also be a bit frustrating to new users as the settings are unclear. Rather than throw them to the wolves, include some useful information to allow them to make good decisions when setting up Dokku.
- Upgrade to latest bootstramp and latest jquery 1.x release
- Add a warning for people who might miss this setup page
- Add placeholder text to both the ssh key area and the hostname
- Add descriptions to all form fields to further explain the consequences of a particular field
- Add links where necessary for users who wish to explore how to change settings in the future
- Make the "result" message on submission red or green depending on the success or failure of the submission.
- Wait 3 seconds before redirecting on success
On Ubuntu within AWS environments, the default user is the `ubuntu` user, and this is where the ssh key should be pulled from. CentOS has a tendency to use `ec2-user`.
On all other environments, the `root` user is typically the only user provisioned.
Closes#3372
The checkstyle xslt wasn't quite good enough, resulting in missing/malformatted output. Note that this now excludes _passing_ tests, which also isn't quite right, but a fair bit closer to the xsd here: https://github.com/windyroad/JUnit-Schema
This requires us to run shellcheck twice, as the first pass doesn't output anything human readable - both because of the redirect and because shellcheck doesn't directly support it - which increases lint runtime but allows us to have both the junit information and the normal human-readable output.
Note that the checkstyle output does not contain timing info.
This removes outdated information on the main page in favor of the "official" ways of sponsoring Dokku.
Also update the contributing note to mention where to post
Are you a crypto-user and want other options? Feel free to send bitcoin to 3MY2HxMVsxuWmhQkgYBsE3iZFjJgkjNPyQ
Closes#3374
Rawgit is no longer being offered due to spammers, but jsdelivr has graciously allowed folks to use their cdn to mirror assets from github.
Closes#3284
- expose an nginx:validate command that can be used to show validation information
- properly reference the invalid nginx config, rather than tell the user that another app's nginx config is invalid when deploying their own app
- allow a user to cleanup bad nginx config files out of band when they are blocking a deploy _without_ requiring knowing where that nginx config is
Note that this may have issues with generated nginx.conf files that depend on other apps or other parts of the nginx config. For now, this is acceptable, though it is something that needs to be field tested.
Closes#3162
This avoids cases where a developer believes they should be able to provision an nginx proxy but is unable to as no web process is configured to listen for the app.
Also silence stderr when extracting custom nginx templates. If there is stderr, that means we were not able to retrieve the template, but it's of no consequence for debugging.
Closes#3262
Rather than testing against an install from source, ensure that all tests run from what _would_ be installed on a user's server. This ensures that the build process is sound, regardless of what code changes are implemented.
This switches from the older, unmaintained version of bats to one that _is_ maintained. In particular, this fork of the community version - bats-core/bats-core - adds junit timing support, which can be used to track down slow tests.
Once the bats-core/bats-core repository merges junit support, we will switch back to upstream.
Note that tests on OS X will still run using a version that _does not_ have junit timing support.
The cipher list is from from https://cipherli.st/ and will remove a few older browsers:
- Android 5.0
- Android 6.0
- Chrome 49 / XP SP3
- Firefox 31.3.0 ESR / Win 7
- Firefox 47 / Win 7 R
- IE 11 / Win Phone 8.1
I _think_ thats an okay drop - dropping Android kinda hurts, but we're far from the only ones dropping them from being served, and our users are free to override these settings on their own servers.
Closes#3343
This is necessary as sometimes older config is shipped with Dokku, meaning that security directives - amongst others - are not properly updated.
Refs #3342
# History
## 0.13.4
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.13.4/bootstrap.sh
sudo DOKKU_TAG=v0.13.4 bash bootstrap.sh
```
### Bug Fixes
- #3337: @josegonzalez Use correct container id variable for killing containers
### New Features
- #3338: @josegonzalez Redirect ps:retire output to a log file
This will allow systems to properly monitor whether retiring old containers works.
Note that the file will be logrotated by the 20_events logrotate config.
# History
## 0.13.3
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.13.3/bootstrap.sh
sudo DOKKU_TAG=v0.13.3 bash bootstrap.sh
```
### Bug Fixes
- #3330: @josegonzalez Ensure chowned properties always have a user and group set
### New Features
- #3334: @josegonzalez refactor: run every 5 minutes instead of 2
# History
## 0.13.2
Install/update via the bootstrap script:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/v0.13.2/bootstrap.sh
sudo DOKKU_TAG=v0.13.2 bash bootstrap.sh
```
### Bug Fixes
- #3329: @josegonzalez Avoid parsing missing file when retiring containers
- #3325: @wcalandro Add "--global" to dokku cleanup on dokku update
### Documentation
- #3326: @josegonzalez Add note to release on how to upgrade via the bootstrap script
# History
## 0.13.0
### Bug Fixes
- #3312: @josegonzalez fix: keep track of failed containers regardless of docker kill output
- #3299: @josegonzalez Wrap script_bin in double-quotes
- #3295: @alexquick Sort config:show by key name
- #3288: @josegonzalez Wrap script binary in single quotes during executable check
### New Features
- #3302: @josegonzalez Add ability to check on app lock status via apps:locked command
- #3315: @aokon Upgrade herokuish to 0.4.5 version
- #3236: @josegonzalez Retire old containers
- #3307: @josegonzalez Add support for docker.io package
- #3301: @josegonzalez Add ability to sync packages to a new version of ubuntu
- #3286: @josegonzalez Sanitize docker inspect output with ps:inspect
- #3240: @josegonzalez Refactor Procfile handling to use go-procfile-util
- #3282: @josegonzalez Use create instead of run for faster and more reliable file copy from docker images
- #3280: @josegonzalez Better scheduler support
- #3259: @josegonzalez Check if script is executable when a full path is specified
### Documentation
- #3314: @royklutman Remove reference to non-existent DigitalOcean hosting plan
- #3313: @morenoh149 Indicate to user to specify hostname
- #3310: @josegonzalez Add a note to our issue template begging for money
- #3281: @josegonzalez Add documentation on custom error pages
This is new in Ubuntu Bionic, and should allow users to install without using upstream docker.
Note that we recommend installing from upstream where possible.
Closes#3297
These will be killed on a cron schedule, allowing us to ensure old containers don't run once memory pressure clears up - even across restarts.
Closes#3225
Often-times, we will want to have the container inspect output for debugging purposes, but this process is:
- error prone, as the user needs to know what their containers are
- potentially insecure, as the output must be sanitized of sensitive data
Instead of making users wade through this process, we provide a helper `ps:inspect` command, that can be used to diagnose problems associated with containers that may or may not exist for an application.
This allows us to force another plugin as the default vhost implementation, or disable it altogether in favor of some higher-level proxy implementation, such as one that integrates with service discovery.
Some systems - such as a mounted read-only CIFS filesystem - do not fully support chown, and chowning should be considered optional for cases when the host os has already taken care of permissioning. This commit allows users to disable chown by setting a property on the scheduler-docker-local plugin.
# History
## 0.12.11
### Bug Fixes
- #3238: @josegonzalez Handle proxy issues in app renaming
- #3234: @mashrikt Unset GIT_QUARANTINE_PATH when updating repo submodule
- #3223: @josegonzalez Get the global scheduler if no app is specified
- #3218: @wcalandro Fix error text when using "dokku plugin:uninstall"
### New Features
- #3242: @josegonzalez Upgrade herokuish to 0.4.3
- #3241: @josegonzalez Add a subcommand for retrieving failed app deploy logs
- #3237: @josegonzalez Support --quiet header when showing all environment variables
### Documentation
- #3235: @josegonzalez Switch from ps:rebuild to ps:restart
- #3221: @josegonzalez Better callout for why env vars do not get applied to dockerfile builds
This can be useful in cases where a developer wishes to see what error messages are available for a failed deploy, but does not wish to spelunk around `docker ps -a` output.
Note that the logs are not made available once a further deploy is triggered, or after the containers have been garbage collected.
This will allow us to kill stale proxy configuration within apps, which is critical during application renames.
- redirect rmdir output to dev-null
- trigger a proxy-clear-config (new trigger) when renaming an application
- The configuration will be rebuilt during the later `ps_rebuild`
Closes#3231
Ubuntu has been slimming down their installations recently, so requiring net-tools fixes usage issues for many commonly installed plugins (such as the datastore plugins).
- reorder things to make it clearer to the user what they are filing
- use headers for various sections
- separate the `dokku report` section to increase its importance
[ci skip]
# History
## 0.12.6
### Bug Fixes
- #3193: @josegonzalez Install bash-completion files correctly
- #3179: @josegonzalez Ignore issues with popd when OS versions with stricter security
- #3177: @philm ensure dokku-redeploy runs when docker is stopped then started
- #3176: @josegonzalez Detect mixed running status on service start
### New Features
- #3195: @josegonzalez Allow lower versions of docker-engine
- #3181: @malixsys Adding support for `http2_push_preload` to nginx 1.13.9+ configuration
- #3183: @josegonzalez Unskip initial herokuish test
- #3175: @josegonzalez Implement bash-completion for commands
### Documentation
- #3197: @josegonzalez Add a tutorial for deploying applications via gitlab ci
- #3194: @josegonzalez Clarify why dokku report information is useful
- #3189: @josegonzalez Correct issue with adding a user remotely
In some cases, a single allocation for a service may not be running, but the others will, and `is_app_running` will return the wrong thing.
Closes#2772
This will allow us to _actually_ introspect on the running state of an application. In certain cases, the detected state can be "mixed", meaning that we may need to take action, depending on what we want to do in mixed mode.
This only completes the command names - not any arguments - and also relies on a completion cache as the response from Dokku for help output can be slow.
Closes#2095
# History
## 0.12.5
### Bug Fixes
- #3173: @josegonzalez fix: do not output error message twice
### New Features
- #3172: @josegonzalez feat: Add the ability to ignore existing applications during a git clone
- #3171: @josegonzalez Allow users to override the reported app url
- #3170: @josegonzalez Add ps:startall command
### Documentation
- #3159: @zuck Improve docs for default site with HTTPS
This is useful in cases where the app url has some "interesting" structure - such as a subdomain or scheme change - for a specific installation.
Closes#3160
# History
## 0.12.3
### Bug Fixes
- #3156: @josegonzalez fix: ensure we _always_ include all types in history output
### Documentation
- #3163: @josegonzalez Better apt install formatting
### Other
- #3153: @scjody Allow specifying a separate DOKKU_HOST_ROOT
In some cases, we might miss pull requests where there is more than one 'type' label, causing that pull request to be omitted from the history. This change ensures we always include pull requests in the change log
As this was not strictly announced in our migration guide, removing it is a bc-incompatible change we are not comfortable with. We may wish to remove it in the future
This is to be used in place of `DOKKU_ROOT` when we need to refer to a
path on the system where the Docker daemon is being run; if `dokku` is
running in a container this may be different from the regular
`DOKKU_ROOT`.
# History
## 0.12.0
### Bug Fixes
- #3146: @josegonzalez Fix non ubuntu installs
- #3138: @josegonzalez Use correct path for /etc/default file
- #3137: @josegonzalez Ensure we can disable setting the rev-env-var
- #3131: @axilleas Capitalize log sentence when renaming containers
- #3128: @Modicrumb Improve windows vagrant experience
- #3105: @znz Follow renaming from deploy-method to deploy-source
- #3101: @josegonzalez Handle stopped nginx during debian installation
### New Features
- #3141: @josegonzalez Centralize app existence checks into the apps plugin
- #3147: @josegonzalez Create proxy:ports-set call
- #3145: @josegonzalez Add report trigger
- #3144: @josegonzalez Increase curl max timeout to 600 seconds (10 minutes)
- #3107: @znz Remove unused password in ssl cert generation
- #3095: @josegonzalez Migrate env for NGINX_* to PROXY_*
- #3140: @josegonzalez Add newline to config:get output
- #3139: @josegonzalez Add ability to initialize a git repository out of band
- #3111: @josegonzalez Upgrade herokuish to 0.4.0
- #3110: @josegonzalez Upgrade herokuish to 0.3.36
- #3106: @znz Remove unnecessary shellcheck disable
- #3098: @josegonzalez Pull herokuish from docker hub when installing via package
- #3100: @josegonzalez Properly handle invalid process type entries during DOKKU_SCALE generation
- #3097: @josegonzalez Update herokuish to 0.3.35
### Documentation
- #3148: @josegonzalez Use consistent terms for domains, apps, and commands
- #3135: @josegonzalez Revert "Clarify that the checks plugin only matches content start"
- #3134: @tomdyson Fix typo in upgrading docs
- #3119: @TomasHubelbauer Link through to the application deployment page after the installation
- #3118: @Tyilo Clarify that the checks plugin only matches content start
- #3113: @ilyapoz Fix proxy management link
- #3112: @josegonzalez Minor doc css fixes
- #3104: @sarendsen Add dokku-limit to plugins documentation
- #3108: @znz Update plugin list output
In some cases, it may be useful to completely override the set ports for a given application - such as on initial deploy when there is no global domain set. This change also further allows us to handle automation in a smoother fashion.
This allows users to quickly show the state of any configured application, as well as the state of their server. In doing so, we make it easy for them to provide information necessary for debugging in a single command.
The correct way to handle getting the status should be ps:report.
Also cleaned up an issue where ps:report failed to catch errors for non-running containers.
This is useful in contexts where the repository directory may be created and interacted with via git-http-backend or other methods of updating a repository.
- add `report` and `set` subcommands to the git plugin
- move configuring the DOKKU_DEPLOY_BRANCH to the git plugin
- implement configurable GIT_REV support
- migrate DOKKU_DEPLOY_BRANCH settings
- add a golang-compatible, shell based method of setting plugin configuration variables
Deprecates the community dokku-git-rev plugin.
Closes#2621
Refs dokku-community/dokku-git-rev#9
# History
## 0.11.6
### Bug Fixes
- #3091: @josegonzalez Properly trigger tar-based deploys on git-deployed repositories
- #3076: @Kjwon15 Prune worktree after build
- #3090: @josegonzalez Ensure all plugin triggers have docs and events integration
- #3089: @josegonzalez Use a longer password for self-signed certificates
### New Features
- #2950: @adelq Add configuration option to disable automatic app creation
- #3093: @josegonzalez Add subcommands to allow app locking and unlocking
- #3092: @josegonzalez Add support for configuring the app shell
### Documentation
- #3096: @josegonzalez docs: Document how to check on a running dokku-installer
This removes the ability to support http proxy directly, but fixes issues where users may not
be using exactly the same herokuish as we expect.
Closes#2828
[ci skip]
Unlocking an app will not stop running deploys, so users may need to clean up. However, it is useful for deploys that fail in unusual ways that cause the lock to stay around.
Closes#2883
This allows developers to change the shell from /bin/bash to any other when executing
`dokku enter` or pre/post deployment tasks. Ideally we could detect the shells available,
but that is slow and potentially error prone.
Closes#2572
# History
## 0.11.5
### Bug Fixes
- #3088: @josegonzalez Silence port retrieval stderr
- #3086: @josegonzalez Fix help output for golang plugins
- #3079: @josegonzalez Move container status exclusively to ps plugin
### New Features
- #3085: @josegonzalez Add support for checking if an application exists
- #3032: @josegonzalez Add support for arbitrary ubuntu versions
- #3074: @josegonzalez Add the ability to disable ANSI prefixes via DOKKU_DISABLE_ANSI_PREFIX_REMOVAL
- #3083: @josegonzalez Source /etc/defaults/dokku if available
### Documentation
- #2958: @silverfix Add tutorial for running Dokku on an external volume
- #3082: @josegonzalez Switch from Gratipay to Patreon
- #3081: @josegonzalez Add docs for switching between deployment methodologies
This allows users to override - at a top-level - the DOKKU_ROOT, DOKKU_LIB_ROOT, and other
configuration variables. If specified, this should begin to enable users to move their
Dokku installations to mounted drives.
Note that items installed from packages may not respect these paths, so further work may be in order.
Closes#2958
These should never have been in common, and more directly relate to domain handling than anything else.
As this is a BC-break, merging will need to wait until the next minor.
# History
## 0.11.4
### Bug Fixes
- #3071: @josegonzalez Do not grab restart policies if the deploy phase cannot be read
- #3065: @josegonzalez Check if dokkurc files are readable before attempting to source
- #3066: @josegonzalez Validate that all application names are valid domain names
- #3052: @alexquick Remove bad config keys on load from app/global envfiles
### New Features
- #3073: @josegonzalez Add support for rhel
- #3039: @josegonzalez Enhance security-related upgrade process
- #3038: @shrmnk Add ps:stopall subcommand
- #3055: @michaelshobbs Update to herokuish v0.3.34
- #3045: @jcrben Remove nginx configuration files on debian purge
### Documentation
- #3072: @josegonzalez Remove all references to VHOST files from documentation
- #3069: @josegonzalez Remove potentially bad nginx template examples
- #3059: @lwm Add note for runtime host configuration for checks.
- #3041: @jcrben Point to unattended install instructions
- #3053: @mimischi Add plugin to manage Dockerfile location to documentation
- #3062: @shannara Change help run command be more explicit
- #3034: @znz Fix a typo in golang config.go source
- #3061: @tomdyson Fix plugin-triggers docs typo
- #3056: @raine Fix typo in config help output
- #3044: @takuti Fix links to port-management
- #3042: @josegonzalez Improve documentation around port handling.
The centos rpm packages should be installable on centos once this is merged and released. However, Dokku will not maintain an Rhel-specific repository as there is no way for us to feasibly test it.
Closes#3046
Users should never be in a position where they need to manually edit files managed by Dokku, and should be pushed to using the `domains` plugin where necessary.
Closes#3064
[ci skip]
These examples do not include _all_ of the contents of the original template. Rather than having to keep them up to date and confuse users when we don't, lets just remove them. The section above contains a link to the current `nginx.conf.sigil` and should be referenced by our users instead.
Closes#3068
[ci skip]
While there are a number of enhancements we could do to make port handling more seamless, this is a first step towards documenting the various oddities around port management for Docker vs Buildpack deploys.
Refs #2903Closes#2970
[ci skip]
# History
## 0.11.3
### Bug Fixes
- #3031: @josegonzalez fix: ensure we respect DOKKU_DEPLOY_BRANCH when rebuilding applications
### New Features
- #3028: @josegonzalez Ensure parallel runs properly for non-restorable apps and moreutils parallel
- #3030: @josegonzalez feat: allow changing the system user the properties plugin uses
- #3024: @jcrben Use high-availability pool keyserver during tests
- #3017: @josegonzalez feat: add pre-start trigger for notifying on application start
### Documentation
- #3020: @gliwka Point to docs in the right version
- #3016: @josegonzalez Update nginx template example to use http2 when available
# History
## 0.11.2
### Bug Fixes
- #3014: @josegonzalez fix: handle case where DOKKU_DOCKERFILE_PORTS is an empty string
- #3013: @alexquick Fix some issues with config/network/repo help output
- #3012: @alexquick Fail when setting/unsetting invalid keys
- #3011: @alexquick Forward output from plugn triggers to user
- #3004: @josegonzalez Return/Exit 1 when an image being deployed is invalid
### Documentation
- #3015: @elia Tiny fixes to triggers documentation
# History
## 0.11.1
### Bug Fixes
- #3010: @josegonzalez fix: route config_all to the `config` command to fix datastore plugin usage
- #3009: @josegonzalez fix: correct the guard around the config_export call in config_sub
- #3006: @josegonzalez fix: do not allow shadowing of the CACHE_DIR variable
- #3005: @josegonzalez fix: persist users in the dokku group through installations
- #3003: @josegonzalez Fix issues in apps:clone calls
- #3001: @josegonzalez fix: allow applications to begin with numeric values
### New Features
- #3002: @josegonzalez fix: omit redirection of docker build output
- #3000: @josegonzalez fix: remove golang files and triggers directory for packaging
# History
## 0.11.0
### Bug Fixes
- #2998: @josegonzalez Fix issues in release process
- #2993: @josegonzalez Add config_all alias for plugin usage
- #2972: @buckle2000 Correct typo in docker-options:remove error output
- #2964: @znz Remove unused variable
- #2967: @znz Fix indentation in test file
- #2963: @znz Correct typos in config plugin and remove potential infinite recursion issue
- #2951: @josegonzalez Handle case where the app directory is a symlink
- #2939: @znz Remove unnecessary lines
- #2945: @znz Fix network plugin version
- #2937: @michaelshobbs Strip restart flag from app_user_pre_deploy_trigger
- #2931: @josegonzalez Upgrade git package for CI
- #2928: @silverfix Do not overwrite the VHOST file during installation if it exists
- #2926: @vtavernier Remove leading forward slash from app name in git-upload-pack
### New Features
- #2985: @bitmand Build a custom dhparam file once for nginx and include it as default
- #2974: @josegonzalez Upgrade to herokuish 0.3.33
- #2973: @josegonzalez Allow usage of git 2.13.0+ by unsetting GIT_QUARANTINE_PATH during git worktree usage
- #2971: @miraculixx Add support for older virtualbox versions in official Dokku Vagrantfile
- #2966: @znz Simplify internal config functions to reduce duplication
- #2751: @alexquick Move config plugin to golang
- #2938: @michaelshobbs Upgrade to golang 1.9.1
- #2736: @josegonzalez Implement Network Plugin
- #2929: @michaelshobbs Add codacy config and coverage targets
### Documentation
- #2935: @jcrben Document how to make herokuish optional during the bootstrap installation
- #2982: @agorf Correct typo in user management docs
- #2981: @agorf Correct typos in process management docs
- #2969: @znz Correct comments on network triggers
- #2965: @znz Remove spaces from config subcommand help output to mirror help output of other subcommands
- #2954: @mrname Add vernemq community datastore plugin to docs
- #2944: @axilleas Fix syntax typo in debian installation docs
- #2932: @znz Update code comment to match documentation
- #2933: @znz Fix version number for network binding documentation
- use a plugin trigger to see whether we should bind to all interfaces
- create a generic way of setting properties for a plugin
- migrate proxy-enabled to the new network property "bind-all-interfaces"
- add network:set subcommand
- Add proxy-build-config hook to rebuild network and proxy settings for an application
- Scope nginx:build-config to work only when it is the configured proxy for an application
- Refactor deploy code to interact with network plugin for computed and actual ipaddr/port settings
- Ensure the proxy-build-config plugin trigger is called on ps:restore
- Expose a few plugin triggers for retrieving networking information for a given APP/PROC_TYPE/CONTAINER_ID combination
Add forward slash cleanup of the app name for the git-upload-pack
command. Prevents is_valid_app_name from removing the application folder
on `git fetch`.
# History
## 0.10.5
### Bug Fixes
- #2912: @josegonzalez Add missing depends statement for rsyslog
- #2906: @manuel-colmenero Check the location of nginx in a central way
- #2895: @josegonzalez cd to app directory when calling git worktree add
### Documentation
- #2922: @axilleas Clarify the minimum Nginx version for HTTP/2 support
- #2919: @wootwoot1234 Update nginx documentation surrounding file uploading for php buildpack users
- #2913: @znz Fix a typo in the rpm release script
- #2910: @buckle2000 Add a note about using the full git url for non-compliant toolchains
You can now set b64encoded values. They are
stored decoded, this is so dokku over ssh can set
odd config values
```
config:set --encoded KEY=BASE_64_VALUE
```
still to do:
* Rework disk format to be okay with quotes
* Fix Dockerfile deployments
* Dedup code in the subcommands
* Add --encode
* Add deploytests for the new stuff
* Restore some log messages (should I make some helpers in common?)
* Restore some functions that may be used by 3d-party plugins
# History
## 0.10.4
### Bug Fixes
- #2894: @josegonzalez fix: bail if any step in the release process fails
- #2880: @josegonzalez fix: properly detect empty subcommands
- #2881: @josegonzalez Verify app name on git push
- #2858: @cstroe Use correct port number for the upstream.
- #2848: @josegonzalez Ensure https applications return an https url from `dokku url`
- #2839: @josegonzalez fix: skip clearing cache if we are not building a herokuish image
### New Features
- #2890: @michaelshobbs use circleci 2.0
- #2847: @scjody Add nginx ppa before installing Dokku
- #2850: @michaelshobbs add optional PROC_TYPE and CONTAINER_INDEX to docker-args-deploy plugn trigger
- #2840: @josegonzalez Add DYNO environment variable to run containers
- #2824: @josegonzalez Upgrade herokuish to version 0.3.31
### Documentation
- #2861: @adelq Use non-deprecated apps command
- #2878: @m0rth1um Add telegram notifications plugin
- #2876: @josegonzalez docs: clarify storage documentation caveats
- #2873: @josegonzalez docs: add a note on which docs to look at for customizing nginx docs
- #2867: @josegonzalez docs: cleanup help output for dokku shell
- #2859: @josegonzalez docs: use relative link for application deployment doc
- #2866: @josegonzalez Add missing migration guides
- #2863: @josegonzalez docs: fix syntax on getting started docs
- #2836: @fishnux Add a note regarding nginx dependency to installation docs
- #2834: @iansu Clarify port exposure in Dockerfile documentation
On hosts where python3 is the system default python env and there is a minimal server installation, Dokku will silently fail to return the values of json keys.
# History
## 0.10.0
### Bug Fixes
- #2820: @josegonzalez Require netcat in debian packaging
- #2774: @fruitl00p Include docker-options in the default `dokku`
- #2778: @zarqman Fix /etc/logrotate.d/dokku on debian
- #2747: @ebeigarts Update herokuish base image on updates using --pull
- #2739: @josegonzalez Use listener_port in nginx.conf.sigil
- #2735: @josegonzalez Ensure we can call ps:report without specifying an application
- #2733: @josegonzalez Add support for new docker package names
- #2730: @weyert Ignore the cache directory when cloning an app
- #2723: @weyert Call non-deprecated plugin:list method
### New Features
- #2803: @iSDP Adding related articles on the Docker Image Deployment page
- #2798: @znz Update CURL_CONNECT_TIMEOUT in docs
- #2795: @josegonzalez docs: Add documentation around adding build-time configuration variables
- #2791: @yazinsai Correct typo in persistent storage docs
- #2789: @h4ckninja Subject-verb agreement
- #2790: @flyinggrizzly Add entry for insecure connection issue in Rails
- #2788: @josegonzalez Flesh out uninstallation documentation
- #2784: @josegonzalez Document special dokku environment variables
- #2773: @znz Update year in footer [ci skip]
- #2768: @znz Ubuntu 12.04 is EOL
- #2769: @lucianopf Fix SlackButton for mobile devices.
- #2763: @ZiadSalah Update vagrant documentation for windows users
- #2764: @joshmanders Create PULL_REQUEST_TEMPLATE.md
- #2758: @AxelTheGerman Update doc location for dokku-git-rev community plugin
- #2757: @nodanaonlyzuul Fix typo from "To use a dockerfiles" to "To use a dockerfile" singular
- #2753: @abrkn Use short-hand method for shutting down all applications in upgrade docs
- #2746: @josegonzalez Add redirect for installation to advanced install docs
- #2738: @josegonzalez Add missing `NO_SSL_SERVER_NAME` to example template
- #2457: @john-doherty Update Digitalocean installation instructions
- #2725: @timaschew Fix typo in application management docs
- #2719: @joshco Clarify that nginx.conf.sigil must be committed to repository
- #2715: @josegonzalez Use urls that are linkable on github
### Documentation
- #2822: @josegonzalez refactor: allow skipping cleanup on a per-application basis
- #2754: @fzerorubigd Add support for set DOKKU_IMAGE per app
- #2815: @markstory Add stickler-ci configuration.
- #2809: @oliw Remove aufs step from Makefile
- #2785: @josegonzalez Add a release-plugin binary
- #2777: @stokarenko Turn on ps-post-stop hook.
- #2781: @fruitl00p Adds docker.io support
- #2766: @josegonzalez Upgrade to herokuish 0.3.29
- #2765: @josegonzalez Install python3-software-properties as an alternative to python-software-properties
- #2642: @chiedo Added better default nginx error pages
- #2678: @callahad Default to secure PCI-compliant SSL setup
- #2734: @josegonzalez Allow quieter report output
In talking with @josegonzalez, stickler-ci.com helps reduce the amount of
time maintainers spend reviewing code by automatically giving style
feedback as pull request comments.
I've added linters for shell scripts and go files based on the linting
I could find in the existing make files.
If an application is configured to enforce secure connections and SSL isn't configured for Dokku or the application, browsers will raise an Invalid Connection error.
Entry describes issue, a code resolution for Rails, and points users to the SSL docs.
This adds a table of environment variables that Dokku will use to change internal behavior.
Not all are fully documented/listed, but this should be enough to get people hacking.
[ci skip]
Herokuish update fails if existing herokuish is used by other containers,
using docker build --pull will force to update also the base image.
Setting up herokuish (0.3.28) ...
Removing old herokuish image
Failed to remove image (gliderlabs/herokuish): Error response from daemon: conflict: unable to remove repository reference "gliderlabs/herokuish" (must force) - container dbf2298ab5a5 is using its referenced image 7d4a8d661476
Importing herokuish into docker (around 5 minutes)
Docker has this thing where they rebrand the debian package name once a year, and as YUM doesn't resolve anything like a "Provides" field, this is the best we can do (unless they all required the same metapackage).
Note that now we can't ensure a specific minor docker version via RPM, though I feel as though if you choose a crappy OS/package manager and we fail you, thats on you, not Dokku.
Closes#2732
Developers can override this in a custom nginx.conf.sigil.
While it may be backwards incompatible - and will therefore require a minor release - it does make things much more secure.
# History
## 0.9.3
### Bug Fixes
- #2706: @josegonzalez fix: ensure nginx conf.d directory exists when running nginx install hook
- #2701: @scjody Set SSH_USER for root commands
### New Features
- #2708: @josegonzalez Document that we will not do buildpack support in the issue tracker
### Documentation
- #2709: @michaelshobbs increase CURL_TIMEOUT and CURL_CONNECT_TIMEOUT defaults
- #2699: @mbreit Add support for git >= 2.11
Git 2.11.0 breaks the git clone approach in git_build_app_repo() in
25ab004c53
git worktree is a much simpler approach but only works for git >= 2.5
so it is not available in Ubuntu 14.04.
Fixes#2512.
# History
## 0.9.2
### New Features
- #2698: @josegonzalez docs: Document that we only care about specific sections
- #2697: @callahad Restore installer note regarding AUFS on Linode
- #2694: @scjody Add documentation note re: git-pre-pull vs. auth
### Documentation
- #2695: @michaelshobbs add tests for pre/post deploy tasks
# History
## 0.9.0
### Bug Fixes
- #2691: @josegonzalez Fix package building when golang binaries are available
- #2671: @znz Fix variable name
- #2672: @callahad Fix logrotate on Debian
- #2666: @josegonzalez Use correct flag for build arguments when installing herokuish
- #2664: @pvalentim Fix remote name when using --remote option with apps:create
### New Features
- #2689: @mbreit Add dokku-monit to community plugin list
- #2683: @josegonzalez Ensure we have an example for adding keys as another user
- #2682: @josegonzalez Clarify supported stanzas in app.json
- #2679: @callahad Remove unnecessary Linode-specific instructions
- #2670: @znz Remove duplicated `(i.e. `
### Documentation
- #2685: @josegonzalez Pass shellcheck on os x
- #2677: @callahad Prefer HTTP2 to SPDY in nginx-vhosts
- #2673: @michaelshobbs Update to herokuish 0.3.27
- #2674: @michaelshobbs Update sshcommand to 0.7.0
- #2654: @ebeigarts Enable nginx and docker on system startup when using bootstrap.sh on CentOS
- #2546: @michaelshobbs Convert repo plugin to golang
- Requires docker, git, and package_cloud gems
- Requires the PACKAGECLOUD_API_TOKEN environment variable
- Builds both a deb and rpm, pushing both to packagecloud
- Upgrades the golang build environment to 1.7.5
- Combines both build Dockerfiles into a single, generic env
- Fixes issue where internal-functions file for tar plugin was not executable
- Ensures that built plugins have a callback to clean up their source files before packaging
- Adds support for “betafish” releases, which are untested versions of Dokku that are available via a separate packagecloud repository.
1. SPDY has been deprecated and removed from modern browsers:
http://caniuse.com/#feat=spdy
2. HTTP/2 is present in all modern browsers:
http://caniuse.com/#feat=http2
3. SPDY and HTTP/2 are mutually exclusive in port-based `listen` directives:
http://nginx.org/en/docs/http/ngx_http_core_module.html#listen
Caniuse suggests that 74% of global users have a browser that supports
HTTP/2, while only 27% have a browser that supports SPDY. Only IE11 and
Safari support both.
Therefore, when both are available, Dokku should choose HTTP/2 to
maximize the benefit to users.
> If you're using Dokku - especially for commercial purposes - consider donating to project development via [OpenCollective](https://opencollective.com/dokku) or [Patreon](https://www.patreon.com/dokku). Funds go to general development, support, and infrastructure costs.
>
> If you need help figuring out how to use a specific buildpack, or are having issues using multiple buildpacks, please see our [irc or slack channels](http://dokku.viewdocs.io/dokku/getting-started/where-to-get-help/#the-irc-and-slack-channels). Issues pertaining to buildpacks may be closed and locked.
## Description of problem
Output of the following commands
### How reproducible
<!-- If you're running 0.4.10+ just use dokku report-->
### Steps to Reproduce
-`uname -a`:
-`free -m`:
-`docker version`:
-`docker -D info`:
-`sigil -v`:
-`docker run -ti gliderlabs/herokuish:latest herokuish version`:
-`dokku version`:
-`dokku plugin`:
-`docker inspect CONTAINER_ID` (if applicable):
(BEWARE: `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):
1.
2.
3.
#### Actual Results
#### Expected Results
## Environment Information
### `dokku report APP_NAME` output
> This is required! Issues missing this information may be closed.
>
> For problems affecting all applications, the report output for a broken application is useful for our debugging.
> You may also run `dokku report` without any arguments to display the top-level reporting information.
### How (deb/make/rpm) and where (AWS, VirtualBox, physical, etc.) was Dokku installed?:
### Additional information
- Container Inspect Output (if applicable) via `dokku ps:inspect APP_NAME`
- Link to the exact repository being deployed (if possible/applicable):
- If a deploy is failing or behaving unexpectedly:
@@ -23,25 +38,5 @@ Output of the following commands
- 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):
<strong>Warning:</strong> The SSH key filled out here can grant root access to the server. Please complete the setup as soon as possible.
</div>
<div class="checkbox">
<label><input id="vhost" name="vhost" type="checkbox" value="true"> Use <abbr title="Nginx will be run on port 80 and backend to your apps based on hostname">virtualhost naming</abbr> for apps</label>
<div class="row">
<div class="col">
<h3>Admin Access</h3>
<div class="form-group">
<label for="key">Public SSH Keys</label><br />
<textarea class="form-control" name="keys" rows="5" id="key" placeholder="Begins with 'ssh-rsa', 'ssh-dss', 'ssh-ed25519', 'ecdsa-sha2-nistp256', 'ecdsa-sha2-nistp384', or 'ecdsa-sha2-nistp521'">{ADMIN_KEYS}</textarea>
<small class="form-text text-muted">Public keys allow users to ssh onto the server as the <code>dokku</code> user, as well as remotely execute Dokku commands. They are currently auto-populated from: <code>{AUTHORIZED_KEYS_LOCATION}</code>, and can be changed later via the <a href="http://dokku.viewdocs.io/dokku/deployment/user-management/" target="_blank"><code>dokku ssh-keys</code></a> plugin.</small>
<input class="form-control" type="text" id="hostname" name="hostname" value="{HOSTNAME}" placeholder="A hostname or ip address such as {HOSTNAME}" />
<small class="form-text text-muted">This will be used as the default host for all applications, and can be changed later via the <a href="http://dokku.viewdocs.io/dokku/configuration/domains/" target="_blank"><code>dokku domains:set-global</code></a> command.</small>
<label class="form-check-label" for="vhost">Use virtualhost naming for apps</label>
<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.
Dokku doesn't enforce a [300mb](https://devcenter.heroku.com/articles/slug-compiler#slug-size) limit on apps, but it's best practice to keep binary assets outside of git. Since containers are considered volatile in Dokku, external stores like s3 or storage mounts should be used for non-volatile items like user uploads. The Dokku storage core plugin can be used to mount local directories / volumes inside the docker container.
See the [persistent storage documentation](/dokku/advanced-usage/persistent-storage/) for more details.
See the [persistent storage documentation](/docs/advanced-usage/persistent-storage.md) for more details.
Sometimes you need to run a command on at deployment time, but before an app is completely deployed.
Common use cases include:
Sometimes you need to run a command on at deployment time, but before an app is completely deployed. Common use cases include:
* Checking a database is initialized
* Running database migrations
* Any commands required to set up the server (e.g. something like a Django `collectstatic`)
## `app.json` and `scripts.dokku`
To support this, Dokku provides support for a special `release` command within your app's `Procfile`, as well as a special `scripts.dokku` key inside of your app's `app.json` file. Be aware that all commands are run within the context of the built docker image - no commands affect the host unless there are volume mounts attached to your app.
Dokku accomplishes this by using an `app.json` file. The format in use is similar to format of Heroku's [app.json](https://devcenter.heroku.com/articles/app-json-schema).
However, Dokku currently only supports the nodes `scripts.dokku.predeploy` and `scripts.dokku.postdeploy`.
For buildpack apps, simply place an `app.json` file in the root of your repository.
For dockerfile apps, place `app.json` in the configured `WORKDIR` directory; otherwise Dokku defaults to the buildpack app behavior of looking in `/app`.
Each "phase" has different expectations and limitations:
> NOTE: postdeploy changes are *NOT* committed to the app image.
-`app.json`: `scripts.dokku.predeploy`
- When to use: This should be used if your app does not support arbitrary build commands and you need to make changes to the built image.
- Are changes committed to the image at this phase: Yes
- Example use-cases
- Bundling assets in a slightly different way
- Installing a custom package from source or copying a binary into place
-`app.json`: `scripts.dokku.postdeploy`
- When to use: This should be used in conjunction with external systems to signal the completion of your deploy.
- Are changes committed to the image at this phase: No
- Example use-cases
- Notifying slack that your app is deployed
- Coordinating traffic routing with a central load balancer
-`Procfile`: `release`
- When to use: This should be used in conjunction with external systems to signal the completion of your app image build.
- Are changes committed to the image at this phase: No
- Example use-cases
- Sending CSS, JS, and other assets from your app’s slug to a CDN or S3 bucket
- Priming or invalidating cache stores
- Running database migrations
### Example app.json
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.
## `app.json` deployment tasks
Dokku provides limited support for the `app.json` manifest from Heroku (documentation available [here](https://devcenter.heroku.com/articles/app-json-schema)). The keys available for use with Deployment Tasks are:
-`scripts.dokku.predeploy`: This is run _after_ an app's docker image is built, but _before_ any containers are scheduled. Changes made to your image are committed at this phase.
-`scripts.dokku.postdeploy`: This is run _after_ an app's containers are scheduled. Changes made to your image are *not* committed at this phase.
For buildpack-based deployments, the location of the `app.json` file should be at the root of your repository. Dockerfile-based app deploys should have the `app.json` in the configured `WORKDIR` directory; otherwise Dokku defaults to the buildpack app behavior of looking in `/app`.
> Warning: Any failed `app.json` deployment task will fail the deploy. In the case of either phase, a failure will not affect any running containers.
The following is an example `app.json` file. Please note that only the `scripts.dokku.predeploy` and `scripts.dokku.postdeploy` tasks are supported by Dokku at this time. All other fields will be ignored and can be omitted.
```json
{
"name":"barebones nodejs",
"description":"A barebones Node.js app using Express 4.",
The `Procfile` also supports a special `release` command which acts in a similar way to the [Heroku Release Phase](https://devcenter.heroku.com/articles/release-phase). This command is executed _after_ an app's docker image is built, but _before_ any containers are scheduled. This is also run _after_ any command executed by `scripts.dokku.predeploy`.
To use the `release` command, simply add a `release` stanza to your Procfile.
@@ -14,9 +14,19 @@ storage:unmount <app> <host-dir:container-dir> # Remove an existing bind mount
> The storage plugin is compatible with storage mounts created with the docker-options. The storage plugin will only list mounts from the deploy/run phase.
## Ideology and Background
The storage plugin supports the following mount points:
The storage plugin requires explicit paths on the host side. This is intentional to ensure that new users avoid running into unexpected results with implicit paths that may not exist (a feature deprecate in [Docker 1.9.0](https://github.com/docker/docker/releases/tag/v1.9.0])). The container directory is created for the mount point in the container. Any existing directory contents are not accessible after a mount is added to the container. Dokku creates a new directory `/var/lib/dokku/data/storage` during installation, it's the general consensus that new users should use this directory. Mounts are only available at run and deploy times, you must redeploy (restart) an app to mount or unmount to an existing app's container.
- explicit paths that exist on the host
- docker volumes
There are a few caveats to using the persistent storage plugin:
- Using implicit paths that do not exist are no longer supported, and actually deprecated in [Docker 1.9.0](https://github.com/docker/docker/releases/tag/v1.9.0). When you specify a persistent storage mount, the host directory is **not** autocreated by either Dokku or Docker.
- We recommend using the directory `/var/lib/dokku/data/storage` directory as the root host path for mounts, and we create this on Dokku installation.
- Mounts are only available at run and deploy times, and you **must** redeploy (restart) an app to mount or unmount to an existing app's container.
- When a directory is mounted, any existing files within the container will be overwritten. If you are writing assets during the build process and then replace the directory with a mount, those files will no longer exist. This is a Docker limitation.
- Paths are mounted within the container at the root of the disk - `/` - and are **not** relative to `/app` (for buildpacks deploys) or the `WORKDIR` (for Dockerfile/Docker images).
- For applications using buildpack deploys, the host directory should be owned by the user and group id `32767`. This is due to how permissions within Herokuish - which builds the Docker images - works. For Dockerfile or Docker image deployments, please use the user and group id which corresponds to the one running the process within the container.
Dokku will then mount the shared contents of `/var/lib/dokku/data/storage` to `/storage` inside the container.
Once you have mounted persistent storage, you will also need to restart the application. See the
[process scaling documentation](/dokku/deployment/process-management) for more information.
Once you have mounted persistent storage, you will also need to restart the application. See the
[process scaling documentation](/docs/deployment/process-management.md) for more information.
```shell
dokku ps:rebuild app-name
dokku ps:restart app-name
```
A more complete workflow may require making a custom directory for your application and mounting it within your `/app/storage` directory instead. The mount point is *not* relative to your application's working directory, and is instead relative to the root of the container.
You can mount one or more directories as desired by following the above pattern.
### Displaying storage reports about an app
### Displaying storage reports for an app
> New as of 0.8.1
@@ -121,7 +132,7 @@ Your app may have services that are running in memory and need to be backed up l
By default, Dokku will only bind storage mounts during the deploy and run phases. Under certain conditions, one might want to bind a storage mount during the build phase. This can be accomplished by using the `docker-options` plugin directly.
You cannot use mounted volumes during the build phase of a Dockerfile deploy. This is because Docker does not support volumes when executing `docker build`.
@@ -136,4 +147,4 @@ By default, Dokku will execute your buildpack application processes as the `hero
> NOTE: this user must exist in your herokuish image.
Additionally, Dokku will ensure your storage mounts are owned by either `herokuishuser` or the overridden value you have set in `DOKKU_APP_USER`.
Additionally, the default `docker-local` scheduler that comes with Dokku will ensure your storage mounts are owned by either `herokuishuser` or the overridden value you have set in `DOKKU_APP_USER`. See the [scheduler-docker-local documentation](/docs/advanced-usage/schedulers/docker-local.md#disabling-chown-of-persistent-storage) docs for more information.
Installing a plugin is easy as well using the `plugin:install` command. This command will also trigger the `install` pluginhook on all existing plugins.
proxy:ports <app> # List proxy port mappings for app
proxy:ports-add <app> <scheme>:<host-port>:<container-port> [<scheme>:<host-port>:<container-port>...] # Set 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:report [<app>] [<flag>] # Displays a proxy report for one or more apps
proxy:set <app> <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.
## Usage
### Container network interface binding
> New as of 0.5.0
By default, the deployed docker container running your app's web process will bind to the internal docker network interface (i.e. `docker inspect --format '{{ .NetworkSettings.IPAddress }}' $CONTAINER_ID`). This behavior can be modified per app by disabling the proxy (i.e. `dokku proxy:disable <app>`). In this case, the container will bind to an external interface (i.e. `0.0.0.0`) and your app container will be directly accessible by other hosts on your network.
> If a proxy is disabled, Dokku will bind your container's port to a random port on the host for every deploy, e.g. `0.0.0.0:32771->5000/tcp`.
By way of example, in the default case, each container is bound to the docker interface:
```shell
docker ps
```
```
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
1b88d8aec3d1 dokku/node-js-app:latest "/bin/bash -c '/star About a minute ago Up About a minute node-js-app.web.1
```
As such, the container's IP address will be an internal IP, and thus it is only accessible on the host itself:
However, you can disable the internal proxying via the `proxy:disable` command so that it will listen on the host's IP address:
```shell
dokku proxy:disable node-js-app
# container bound to all interfaces
docker ps
```
```
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
d6499edb0edb dokku/node-js-app:latest "/bin/bash -c '/star About a minute ago Up About a minute 0.0.0.0:49153->5000/tcp node-js-app.web.1
```
### Displaying proxy reports about an app
> New as of 0.8.1
You can get a report about the app's proxy status using the `proxy:report` command:
```shell
dokku proxy:report
```
```
=====> node-js-app proxy information
Proxy enabled: true
Proxy type: nginx
Proxy port map: http:80:5000 https:443:5000
=====> python-sample proxy information
Proxy enabled: true
Proxy type: nginx
Proxy port map: http:80:5000
=====> ruby-sample proxy information
Proxy enabled: true
Proxy type: nginx
Proxy port map: http:80:5000
```
You can run the command for a specific app also.
```shell
dokku proxy:report node-js-app
```
```
=====> node-js-app proxy information
Proxy enabled: true
Proxy type: nginx
Proxy port map: http:80:5000 https:443:5000
```
You can pass flags which will output only the value of the specific information you want. For example:
```shell
dokku proxy:report node-js-app --proxy-type
```
### Proxy port mapping
> New as of 0.6.0
You can now configure `host -> container` port mappings with the `proxy:ports-*` commands. This mapping is currently supported by the built-in nginx-vhosts plugin.
To inspect the port mapping for a given application, use the `proxy:ports` command:
```shell
dokku proxy:ports node-js-app
```
```
-----> Port mappings for node-js-app
-----> scheme host port container port
http 80 5000
```
The above application is listening on the host's port `80`, which we can test via curl:
```shell
curl http://node-js-app.dokku.me
```
```
Hello World!
```
There are cases where we may wish for the service to be listening on more than one port, such as port 8080. Normally, this would not be possible:
```shell
curl http://node-js-app.dokku.me:8080
```
```
curl: (7) Failed to connect to node-js-app.dokku.me port 8080: Connection refused
```
However, we can use the `proxy:ports-add` command to add a second external port mapping - `8080` - to our application's port `5000`.
We can now test that port 80 still responds properly:
```shell
curl http://node-js-app.dokku.me
```
```
Hello World!
```
And our new listening port of `8080` also works:
```shell
curl http://node-js-app.dokku.me:8080
```
```
Hello World!
```
You can also remove a port mapping that is no longer necessary:
```shell
dokku proxy:ports-remove node-js-app http:80:5000
```
By default, buildpack apps and dockerfile apps **without** explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on port `80` (and additionally a listener on 443 if ssl is enabled) that will proxy to the application container on port `5000`. Dockerfile apps **with** explicitly exposed ports will be configured with a listener on each exposed port and will proxy to that same port of the deployed application container.
> Note: This default behavior **will not** be automatically changed on subsequent pushes and must be manipulated with the `proxy:ports-*` syntax detailed above.
#### Proxy Port Scheme
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.
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.
To change the proxy implementation in use for an application, use the `proxy:set` command:
resource:limit [--process-type <process-type>] [RESOURCE_OPTS...] <app> # Limit resources for a given app/process-type combination
resource:limit-clear [--process-type <process-type>] <app> # Limit resources for a given app/process-type combination
resource:report [<app>] [<flag>] # Displays a resource report for one or more apps
resource:reserve [--process-type <process-type>] [RESOURCE_OPTS...] <app> # Reserve resources for a given app/process-type combination
resource:reserve-clear [--process-type <process-type>] <app> # Reserve resources for a given app/process-type combination
```
The resource plugin is meant to allow users to limit or reserve resources for a given app/process-type combination.
## Usage
By default, Dokku allows unlimited resource access to apps deployed on a server. In some cases, it may be desirable to limit this on a per-app or per-process-type basis. The `resource` plugin allows management of both resource "limits" and resource "reservations", where each resource request type has specific meaning to the scheduler in use for a given app.
> The meaning of a values and it's units are specific to the scheduler in use for a given app. If a scheduler does not support a given resource type combination, it will be ignored. All resource commands require an app rebuild or deploy in order to take effect.
Valid resource options include:
-`--cpu`
-`--memory`
-`--memory-swap`
-`--network`
-`--network-ingress`
-`--network-egress`
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.
### Resource Limits
When specified and supported, a resource limit will ensure that your app does not go _over_ the specified value. If this occurs, the underlying scheduler may either cap resource utilization, or it may decide to terminate and reschedule your process.
Resource limits may be set via the `resource:limit` command:
```shell
dokku resource:limit --memory 100 node-js-app
```
```
=====> Setting resource limits for node-js-app
memory: 100
```
Multiple resources can be limited in a single call:
=====> Setting resource limits for node-js-app (worker)
cpu: 100
memory: 100
```
#### Displaying Resource Limits
Running the `resource:limit` command without any flags will display the currently configured default app limits.
```shell
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)
cpu: 100
memory: 100
memory-swap:
network:
network-ingress:
network-egress:
```
#### 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.
```shell
dokku resource:limit-clear node-js-app
```
```
-----> Clearing resource limit for node-js-app
```
Defaults can also be cleared by leaving the app unspecified.
```shell
dokku resource:limit-clear
```
```
-----> Clearing default resource limits
```
### Resource Reservations
When specified and supported, a resource reservation will ensure that your server has _at least_ the specified resources before placing a given app's process. If there a resource exhaustion, future rebuilds and deploys may fail.
Resource reservations may be set via the `resource:reserve` command:
```shell
dokku resource:reserve --memory 100 node-js-app
```
```
=====> Setting resource reservation for node-js-app
memory: 100
```
Multiple resources can be limited in a single call:
=====> Setting resource reservation for node-js-app (worker)
cpu: 100
memory: 100
```
#### Displaying Resource Reservations
Running the `resource:reserve` command without any flags will display the currently configured default app reservations.
```shell
dokku resource:reserve node-js-app
```
```
=====> resource reservation node-js-app information [defaults]
cpu: 100
memory: 100
memory-swap:
network:
network-ingress:
network-egress:
```
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 --process-type web node-js-app
```
```
=====> resource reservation node-js-app information (web)
cpu: 100
memory: 100
memory-swap:
network:
network-ingress:
network-egress:
```
#### 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.
```shell
dokku resource:reserve-clear node-js-app
```
```
-----> Clearing resource reservation for node-js-app
```
Defaults can also be cleared by leaving the app unspecified.
```shell
dokku resource:reserve-clear
```
```
-----> Clearing default resource reservation
```
### Displaying resource reports for an app
You can get a report about the app's resource status using the `resource:report` command:
```shell
dokku resource:report
```
```
=====> node-js-app resource information
web limit cpu:
web limit memory: 1024
web limit memory swap: 0
web limit network: 10
web limit network ingress:
web limit network egress:
web reservation cpu:
web reservation memory: 512
web reservation memory swap:
web reservation network: 8
web reservation network ingress:
web reservation network egress:
=====> python-sample resource information
web limit cpu:
web limit memory:
web limit memory swap:
web limit network:
web limit network ingress:
web limit network egress:
web reservation cpu:
web reservation memory:
web reservation memory swap:
web reservation network:
web reservation network ingress:
web reservation network egress:
=====> ruby-sample resource information
web limit cpu:
web limit memory:
web limit memory swap:
web limit network:
web limit network ingress:
web limit network egress:
web reservation cpu:
web reservation memory:
web reservation memory swap:
web reservation network:
web reservation network ingress:
web reservation network egress:
```
You can run the command for a specific app also.
```shell
dokku resource:report node-js-app
```
```
=====> node-js-app resource information
web limit cpu:
web limit memory: 1024
web limit memory swap: 0
web limit network: 10
web limit network ingress:
web limit network egress:
web reservation cpu:
web reservation memory: 512
web reservation memory swap:
web reservation network: 8
web reservation network ingress:
web reservation network egress:
```
You can pass flags which will output only the value of the specific information you want. For example:
scheduler-docker-local:report [<app>] [<flag>] # Displays a scheduler-docker-local report for one or more apps
scheduler-docker-local:set <app> <key> (<value>) # Set or clear a scheduler-docker-local property for an app
```
> New as of 0.12.0
Dokku natively includes functionality to manage application lifecycles for a single server using the `scheduler-docker-local` plugin. It is the default scheduler, but as with all schedulers, it is set on a per-application basis. The scheduler can currently be overridden by running the following command:
As it is the default, unsetting the `DOCKER_SCHEDULER` config variable is also a valid way to reset the scheduler.
```shell
dokku config:unset node-js-app DOCKER_SCHEDULER
```
## Usage
### Disabling chown of persistent storage
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:
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-docker-local` plugin.
-`check-deploy`
-`core-post-deploy`
-`post-app-clone-setup`
-`post-create`
-`post-delete`
-`pre-deploy`
-`pre-restore`
-`scheduler-deploy`
-`scheduler-docker-cleanup`
-`scheduler-inspect`
-`scheduler-logs-failed`
-`scheduler-logs`
-`scheduler-retire`
-`scheduler-run`
-`scheduler-stop`
-`scheduler-tags-create`
-`scheduler-tags-destroy`
## Supported Resource Management Properties
The `docker-local` scheduler supports a minimal list of resource _limits_ and _reservations_. The following properties are supported:
### 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)
- memory-swap: (docker option: `--memory-swap`) and should be specified with a suffix of `b` (bytes), `k` (kilobytes), `m` (megabytes), `g` (gigabytes)
### Resource Reservations
- memory: (docker option: `--memory-reservation`) and should be specified with a suffix of `b` (bytes), `k` (kilobytes), `m` (megabytes), `g` (gigabytes)
By default, Dokku will ship a PCI Compliant nginx configuration. For developers whose users are on older browsers or mobile devices, you may need to ship a custom `nginx.conf.sigil` to enable ciphers for older browsers.
See the [nginx customization](/docs/configuration/nginx/#customizing-the-nginx-configuration) docs for more details.
## Nginx Error Pages
We now ship with nicer error pages by default. You are free to customize your Dokku installation via a custom `nginx.conf.sigil` to change what error pages are displayed in different circumstances.
See the [nginx customization](/docs/configuration/nginx/#customizing-the-nginx-configuration) docs for more details.
-`DOKKU_CHECKS_ENABLED` has been migrated to `DOKKU_CHECKS_SKIPPED`
-`DOKKU_CHECKS_DISABLED` is now a thing
- The values for the above can be a comma-separated list of process-types or the literal string `_all_`
- See the [updated `checks`](/dokku/deployment/zero-downtime-deploys/) docs for more info
- See the [updated `checks`](/docs/deployment/zero-downtime-deploys.md) docs for more info
## Proxy port mapping
- You can now configure host -> container proxy port mappings
- The UI is handled by the [proxy](/dokku/advanced-usage/proxy-management/) interface plugin by setting the `DOKKU_PROXY_PORT_MAP` config variable in the format of `scheme:host-port:container-port`. The default `nginx-vhosts` proxy plugin supports both the `http` and `https` schemes.
- The UI is handled by the [proxy](/docs/advanced-usage/proxy-management.md) interface plugin by setting the `DOKKU_PROXY_PORT_MAP` config variable in the format of `scheme:host-port:container-port`. The default `nginx-vhosts` proxy plugin supports both the `http` and `https` schemes.
- Default port mappings
- buildpack apps will be set to `http:80:5000` and will also include `https:443:5000` if SSL is enabled.
- dockerfile apps with explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on each exposed port that proxies to the same port of the deployed application container.
- You may override this behavior with the [`proxy:ports-*` commands](/dokku/advanced-usage/proxy-management/) or by directly setting `DOKKU_PROXY_PORT_MAP` with the `config:set` command
- You may override this behavior with the [`proxy:ports-*` commands](/docs/advanced-usage/proxy-management.md) or by directly setting `DOKKU_PROXY_PORT_MAP` with the `config:set` command
- dockerfile apps without explicitly exposed ports will behave the same as a buildpack app
- NOTE: These defaults **are not** automatically changed on subsequent pushes and must be manipulated with the aforementioned commands
We should now properly handle file ownership for mounted directories. This was enhanced in 0.7.1. See the [persistent storage documentation](/dokku/advanced-usage/persistent-storage/) for more details.
We should now properly handle file ownership for mounted directories. This was enhanced in 0.7.1. See the [persistent storage documentation](/docs/advanced-usage/persistent-storage.md) for more details.
## Restart Policies
If you previously managed container restart policies via docker-options, these can now be managed natively via the built-in `ps` plugin. There is no migration necessary. See the [restart policy documentation](/dokku/deployment/process-management/#restart-policies) for more details.
If you previously managed container restart policies via docker-options, these can now be managed natively via the built-in `ps` plugin. There is no migration necessary. See the [restart policy documentation](/docs/deployment/process-management.md#restart-policies) for more details.
## SSH Keys
Dokku now has an `ssh-keys` plugin that can be used to manage ssh keys for the `dokku` user on the host operating system. See the [user management documentation](/dokku/deployment/user-management/) for more details.
Dokku now has an `ssh-keys` plugin that can be used to manage ssh keys for the `dokku` user on the host operating system. See the [user management documentation](/docs/deployment/user-management.md) for more details.
You can now set global and app domains via `domains:set` and `domains:set-global`. See the [domains documentation](/docs/configuration/domains/) for more details.
## Plugin Uninstallation
A new `uninstall` plugin trigger was introduced. This functionality may be in use for newer plugins, so be aware that older Dokku versions may require manual cleanup.
See the [uninstall trigger documentation](/docs/development/plugin-triggers/#uninstall) for implementation instructions.
## Deployment Tasks
Should a pre or post deployment task fail, we now fail the entire deploy.
## Nginx HTTP2 Support
Due to bugs in Nginx, the minimum version for HTTP2 is now 1.11.5.
There is an ongoing migration to rewrite Dokku in Golang. The reasons are beyond the scope of this document, but this may impact any patches you have for Dokku. As of 0.9.0, only the `repo` plugin is in Golang.
The following shall remain true, regardless of the state of our rewrite:
- You will be able to write custom plugins in any language.
- You will be able to enable or disable core plugins.
-`plugn` will continue to be used for executing plugin triggers.
- We will provide bash wrappers that can be sourced to execute core functionality that is implemented in golang.
Gitlab-CI can be used to automatically deploy a Dokku application using the [ilyasemenov/gitlab-ci-git-push image](https://github.com/IlyaSemenov/gitlab-ci-git-push) docker image.
## Prerequisites
Make sure you have a Gitlab account and a Dokku project hosted on Gitlab. This method works whether if you are using buildpacks or Dockerfile.
Make sure you have set up an app on the remote machine following [these instructions](http://dokku.viewdocs.io/dokku/deployment/application-deployment/) and can successfully deploy to it from the local machine.
## Deploy automatically to production
### Add a secret variable
Browse to the repository in question and visit the following path: `the Gitlab project > Settings > CI/CD.`
Click on `Secret variables > Expand` and fill in the blanks.
- Key: `SSH_PRIVATE_KEY`
- Value: paste in an SSH private key registered in Dokku:
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
- Environment scope: `production` (This make sure that `SSH_PRIVATE_KEY` is not available on merge requests or tests)
- Protected: Do not check this checkbox unless you know what you are doing
### Add CI script
Create a file named `.gitlab-ci.yml` at the root directory of the repository with the following contents:
```yaml
stages:
- deploy
variables:
APP_NAME:node-js-app
deploy:
image:ilyasemenov/gitlab-ci-git-push
stage:deploy
environment:
name:production
url:https://$APP_NAME.dokku.me/
only:
- master
script:
- git-push ssh://dokku@dokku.me:22/$APP_NAME
```
You will need to modify the `APP_NAME` variable to the correct value for your application name.
Running `git push origin master` will now trigger a gitlab-ci pipeline that will automatically deploy your application to your Dokku server. Go to your project on Gitlab and visit "Project > Pipelines" to see the deployment log.
## Review Applications
One useful feature of gitlab is to be able to create review applications for non-production branches. This allows teams to review changes _before_ they are pushed to production. First, recreate the `SSH_PRIVATE_KEY` secret - do not delete the existing secret - but scoped to the `review/*` environment. This will allow non-production gitlab environments access to the secret.
Next, we'll need to create the `review_app` gitlab job in our `.gitlab-ci.yaml`.
The first two lines ensure that Gitlab can talk to the Dokku server. Next, we take advantage of the `apps:clone` command, and clone the existing application and all of it's configuration to a new location. If the new application already exists, the third line of the `script` step will be ignored. We also ignore the first deploy script to speed up the cloning process. Finally, the fourth line of the `script` step will deploy the code as normal.
The above only runs for non-master branches, and will _also_ trigger an `on_stop` job called `stop_review_app`. When the branch is deleted or the code is merged, the `stop_review_app` job will be triggered.
In order to leverage cloud-provider facilities like _attachable volumes_, (_a.k.a. block storage_)
the following is an easy tutorial to achieve Dokku runs on them.
> Warning: If the block storage is not available and attached on boot it is possible that containers will not correctly start. Please keep this in mind when considering moving Dokku and/or Docker to network attached storage.
## Tutorial
The following is intended to be executed on the dokku host machine as `root`.
Say, _for instance_, that our volume is mapped into the systems as `/dev/vdb1`.
Stop docker daemon
```shell
systemctl stop docker
```
Prepare the filesystem:
```shell
mkfs -t ext4 /dev/vdb1
mkdir /mnt/volume
mount /dev/vdb1 /mnt/volume
```
Move the old data directories:
```shell
mv /home/dokku /home/dokku.OLD
mv /var/lib/docker /var/lib/docker.OLD
mv /var/lib/dokku /var/lib/dokku.OLD
```
Move the data on the volume
```shell
mkdir /mnt/volume/home/
mkdir /mnt/volume/var/lib/
mv /home/dokku.OLD /mnt/volume/home/dokku
mv /var/lib/dokku.OLD /mnt/volume/var/lib/dokku
mv /var/lib/docker.OLD /mnt/volume/var/lib/docker
```
Prepare the mountpoints
```shell
mkdir /home/dokku
mkdir /var/lib/dokku
mkdir /var/lib/docker
chown dokku:dokku /home/dokku # respect the original ownership
chmod 711 /var/lib/docker # respect the original permissions
```
Mount bind
```shell
mount -o bind /mnt/volume/home/dokku /home/dokku
mount -o bind /mnt/volume/var/lib/dokku /var/lib/dokku
mount -o bind /mnt/volume/var/lib/docker /var/lib/docker
```
Start docker daemon
```shell
systemctl start docker
```
At this point all should be working fine, please check it out.
Then, let the changes be reboot-persistent
```shell
echo'/dev/vdb1 /mnt/volume ext4 defaults 0 2'| sudo tee -a /etc/fstab
echo'/mnt/volume/home/dokku /home/dokku none defaults,bind 0 0'| sudo tee -a /etc/fstab
echo'/mnt/volume/var/lib/dokku /var/lib/dokku none defaults,bind 0 0'| sudo tee -a /etc/fstab
echo'/mnt/volume/var/lib/docker /var/lib/docker none defaults,bind 0 0'| sudo tee -a /etc/fstab
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
domains:remove-global <domain> [<domain> ...] # Remove global domain names
domains:report [<app>] [<flag>] # Displays a domains report for one or more apps
domains:report [<app>|--global] [<flag>] # Displays a domains report for one or more apps
domains:set <app> <domain> [<domain> ...] # Set domains for app
domains:set-global <domain> [<domain> ...] # Set global domain names
```
> Adding a domain before deploying an application will result in port mappings being set. This may cause issues for applications that use non-standard ports, as those will not be automatically detected. Please refer to the [proxy documentation](/dokku/advanced-usage/proxy-management/) for information as to how to reconfigure the mappings.
> Adding a domain before deploying an application will result in port mappings being set. This may cause issues for applications that use non-standard ports, as those will not be automatically detected. Please refer to the [proxy documentation](/docs/networking/proxy-management.md) for information as to how to reconfigure the mappings.
## Customizing hostnames
@@ -25,57 +26,46 @@ Applications typically have the following structure for their hostname:
scheme://subdomain.domain.tld
```
The `subdomain` is inferred from the pushed application name, while the `domain.tld` is set during initial configuration and stored in the `$DOKKU_ROOT/VHOST` file. 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.
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 default `$DOKKU_ROOT/VHOST` 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
If desired, it is possible to disable vhosts with the domains plugin.
```shell
dokku domains:disable myapp
dokku domains:disable node-js-app
```
On subsequent deploys, the nginx virtualhost will be discarded. This is useful when deploying internal-facing services that should not be publicly routeable. As of 0.4.0, nginx will still be configured to proxy your app on some random high port. This allows internal services to maintain the same port between deployments. You may change this port by setting `DOKKU_NGINX_PORT` and/or `DOKKU_NGINX_SSL_PORT` (for services configured to use SSL.)
On subsequent deploys, the nginx virtualhost will be discarded. This is useful when deploying internal-facing services that should not be publicly routeable. As of 0.4.0, nginx will still be configured to proxy your app on some random high port. This allows internal services to maintain the same port between deployments. You may change this port by setting `DOKKU_PROXY_PORT` and/or `DOKKU_PROXY_SSL_PORT` (for services configured to use SSL.)
The domains plugin allows you to specify custom domains for applications. This plugin is aware of any ssl certificates that are imported via `certs:add`. Be aware that disabling domains (with `domains:disable`) will override any custom domains.
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
```
> 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).
The variables are available both at run time and during the application build/compilation step for buildpack-based deploys. 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).
Environment variables are available both at run time and during the application build/compilation step for buildpack-based deploys.
For buildpack deploys, Dokku will create a `/app/.env` file that can be used for legacy buildpacks. Note that this is *not* updated when `config:set` or `config:unset` is called, and is only written during a `deploy` or `ps:rebuild`. Developers are encouraged to instead read from the application environment directly, as the proper values will be available then.
@@ -23,10 +28,15 @@ You can set multiple environment variables at once:
When setting variables with whitespaces, you need to escape them:
> Note: Whitespace and special characters get tricky. If you are using dokku locally you don't need to do any special escaping. If you are using dokku over ssh you will need to backslash-escape spaces:
Dokku can also read base64 encoded values. That's the easiest way to set a value with newlines or spaces. To set a value with newlines you need to base64 encode it first and pass the `--encoded` flag:
When setting or unsetting environment variables, you may wish to avoid an application restart. This is useful when developing plugins or when setting multiple environment variables in a scripted manner. To do so, use the `--no-restart` flag:
@@ -35,25 +45,84 @@ When setting or unsetting environment variables, you may wish to avoid an applic
| `DOKKU_ROOT` | `~dokku` | `/etc/environment` | The root directory where dokku will store application repositories, as well as certain configuration files. |
| `DOKKU_IMAGE` | `gliderlabs/herokuish` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The default image to use when building herokuish containers. |
| `DOKKU_LIB_ROOT` | `/var/lib/dokku` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The directory where plugins, certain data, and general configuration is stored. |
| `PLUGIN_PATH` | `$DOKKU_LIB_ROOT/plugins"` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The top-level directory where plugins are stored. |
| `PLUGIN_AVAILABLE_PATH` | `$PLUGIN_PATH/available"` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The directory that holds all available plugins, including core. |
| `PLUGIN_ENABLED_PATH` | `$PLUGIN_PATH/enabled"` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The directory that holds all enabled plugins, including core. |
| `PLUGIN_CORE_PATH` | `$DOKKU_LIB_ROOT/core-plugins"` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The directory that stores all core plugins. |
| `PLUGIN_CORE_AVAILABLE_PATH` | `$PLUGIN_CORE_PATH/available"` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The directory that stores all available core plugins. |
| `PLUGIN_CORE_ENABLED_PATH` | `$PLUGIN_CORE_PATH/enabled"` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The directory that stores all enabled core plugins. |
| `DOKKU_LOGS_DIR` | `/var/log/dokku` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | Where dokku logs should be written to. |
| `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_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 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. |
| `DOKKU_APP_TYPE` | `herokuish` | Auto-detected by using buildpacks or dockerfile | |
| `DOKKU_CHECKS_WAIT` | `5` | `dokku config:set` | Wait this many seconds for the container to start before running checks.
| `DOKKU_CHECKS_TIMEOUT` | `30` | `dokku config:set` | Wait this many seconds for each response before marking it as a failure.
| `DOKKU_CHECKS_ATTEMPTS` | `5` | `dokku config:set` | Number of retries for to run for a specific check before marking it as a failure
| `DOKKU_DEFAULT_CHECKS_WAIT` | `10` | `dokku config:set` | If no user-defined checks are specified - or if the process being checked is not a `web` process - this is the period of time Dokku will wait before checking that a container is still running. |
| `DOKKU_DISABLE_PROXY` | none | `dokku proxy:disable` <br /> `dokku proxy:enable` | Disables the proxy in front of your application, resulting in publicly routing the docker container. |
| `DOKKU_DISABLE_ANSI_PREFIX_REMOVAL` | none | `dokku config:set` <br /> `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | Disables removal of the ANSI prefix during deploys. Can be used in cases where the client deployer does not understand ansi escape codes. |
| `DOKKU_DISABLE_APP_AUTOCREATION` | none | `dokku config:set` | Disables automatic creation of a non-existent app on deploy. |
| `DOKKU_DOCKER_STOP_TIMEOUT` | `10` | `dokku config:set` | Configurable grace period given to the `docker stop` command. If a container has not stopped by this time, a `kill -9` signal or equivalent is sent in order to force-terminate the container. Both the `ps:stop` and `apps:destroy` commands _also_ respect this value. If not specified, the docker defaults for the [docker stop command](https://docs.docker.com/engine/reference/commandline/stop/) will be used.|
| `DOKKU_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,6 +6,67 @@ 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:validate [<app>] [--clean] # Validates and optionally cleans up invalid nginx configurations
```
## 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`.
```shell
dokku nginx:access-logs node-js-app
```
You may also follow the logs by specifying the `-t` flag.
```shell
dokku nginx:access-logs node-js-app -t
```
## Checking error logs
You may check nginx error logs via the `nginx:access-logs` command. This assumes that app error logs are being stored in `/var/log/nginx/$APP-error.log`, as is the default in the generated `nginx.conf`.
```shell
dokku nginx:error-logs node-js-app
```
You may also follow the logs by specifying the `-t` flag.
```shell
dokku nginx:error-logs node-js-app -t
```
## Regenerating nginx config
In certain cases, your app nginx configs may drift from the correct config for your app. You may regenerate the config at any point via the `nginx:build-config` command. This may fail if there are no current web listeners for your app.
```shell
dokku nginx:build-config 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.
```shell
dokku nginx:validate
```
As app nginx configs are actually executed within a shared context, it is possible for an individual config to be invalid when being validated standalone but _also_ be valid within the global server context. As such, the exit code for the `nginx:validate` command is the exit code of `nginx -t` against the server's real nginx config.
The `nginx:validate` command also takes an optional `--clean` flag. If specified, invalid nginx configs will be removed.
> Warning: Invalid app nginx config's will be removed _even if_ the config is valid in the global server context.
```shell
dokku nginx:validate --clean
```
The `--clean` flag may also be specified for a given app:
```shell
dokku nginx:validate node-js-app --clean
```
## Customizing the nginx configuration
@@ -15,54 +76,13 @@ nginx:error-logs <app> [-t] # Show the nginx error logs for an appl
Dokku uses a templating library by the name of [sigil](https://github.com/gliderlabs/sigil) to generate nginx configuration for each app. You may also provide a custom template for your application as follows:
- Copy the following example template to a file named `nginx.conf.sigil` and either:
- check it into the root of your app repo for buildpack applications
- If using a buildpack application, you __must__ check it into the root of your app repo.
-`ADD` it to your dockerfile `WORKDIR`
- if your dockerfile has no `WORKDIR`, `ADD` it to the `/app` folder
> When using a custom `nginx.conf.sigil` file, depending upon your application configuration, you *may* be exposing the file externally. As this file is extracted before the container is run, you can, safely delete it in a custom `entrypoint.sh` configured in a Dockerfile `ENTRYPOINT`.
> The default template is available [here](https://github.com/dokku/dokku/blob/master/plugins/nginx-vhosts/templates/nginx.conf.sigil), and can be used as a guide for your own, custom `nginx.conf.sigil` file. Please refer to the appropriate template file version for your Dokku version.
### Available template variables
@@ -71,8 +91,8 @@ upstream {{ .APP }} {
{{ .APP_SSL_PATH }} Path to SSL certificate and key
{{ .DOKKU_ROOT }} Global Dokku root directory (ex: app dir would be `{{ .DOKKU_ROOT }}/{{ .APP }}`)
{{ .DOKKU_APP_LISTENERS }} List of IP:PORT pairs of app containers
{{ .NGINX_PORT }} Non-SSL nginx listener port (same as `DOKKU_NGINX_PORT` config var)
{{ .NGINX_SSL_PORT }} SSL nginx listener port (same as `DOKKU_NGINX_SSL_PORT` config var)
{{ .PROXY_PORT }} Non-SSL nginx listener port (same as `DOKKU_PROXY_PORT` config var)
{{ .PROXY_SSL_PORT }} SSL nginx listener port (same as `DOKKU_PROXY_SSL_PORT` config var)
{{ .NOSSL_SERVER_NAME }} List of non-SSL VHOSTS
{{ .PROXY_PORT_MAP }} List of port mappings (same as `DOKKU_PROXY_PORT_MAP` config var)
{{ .PROXY_UPSTREAM_PORTS }} List of configured upstream ports (derived from `DOKKU_PROXY_PORT_MAP` config var)
@@ -83,155 +103,81 @@ upstream {{ .APP }} {
> Note: Application config variables are available for use in custom templates. To do so, use the form of `{{ var "FOO" }}` to access a variable named `FOO`.
### Example HTTP to HTTPS Custom Template
Use case: a simple dockerfile app that includes `EXPOSE 80`
The example above uses additional configuration files directly on the Dokku host. Unlike the `nginx.conf.sigil` file, these additional files will not be copied over from your application repo, and thus need to be placed in the `/home/dokku/myapp/nginx.conf.d/` directory manually.
The example above uses additional configuration files directly on the Dokku host. Unlike the `nginx.conf.sigil` file, these additional files will not be copied over from your application repo, and thus need to be placed in the `/home/dokku/node-js-app/nginx.conf.d/` directory manually.
For PHP Buildpack users, you will also need to provide a `Procfile` and an accompanying `nginx.conf` file to customize the nginx config *within* the container. The following are example contents for your `Procfile`
Your `nginx.conf` file - not to be confused with Dokku's `nginx.conf.sigil` - would also need to be configured as shown in this example:
client_max_body_size 50m;
location / {
index index.php;
try_files $uri $uri/ /index.php$is_args$args;
}
Please adjust the `Procfile` and `nginx.conf` file as appropriate.
## 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.
## Domains plugin
See the [domain configuration documentation](/dokku/configuration/domains/).
See the [domain configuration documentation](/docs/configuration/domains.md).
## Customizing hostnames
See the [customizing hostnames documentation](/dokku/configuration/domains/#customizing-hostnames).
See the [customizing hostnames documentation](/docs/configuration/domains.md#customizing-hostnames).
## Disabling VHOSTS
See the [disabling vhosts documentation](/dokku/configuration/domains/#disabling-vhosts).
See the [disabling vhosts documentation](/docs/configuration/domains.md#disabling-vhosts).
## Default site
See the [default site documentation](/dokku/configuration/domains/#default-site).
See the [default site documentation](/docs/configuration/domains.md#default-site).
## Running behind a load balancer
See the [load balancer documentation](/dokku/configuration/ssl/#running-behind-a-load-balancer).
See the [load balancer documentation](/docs/configuration/ssl.md#running-behind-a-load-balancer).
## HSTS Header
See the [HSTS documentation](/dokku/configuration/ssl/#hsts-header).
See the [HSTS documentation](/docs/configuration/ssl.md#hsts-header).
## SSL Configuration
See the [ssl documentation](/dokku/configuration/ssl/).
See the [ssl documentation](/docs/configuration/ssl.md).
## Disabling Nginx
See the [proxy documentation](/dokku/advanced-usage/proxy-management/).
See the [proxy documentation](/docs/advanced-usage/proxy-management.md).
## Managing Proxy Port mappings
See the [proxy documentation](/dokku/advanced-usage/proxy-management/#proxy-port-mapping).
See the [proxy documentation](/docs/advanced-usage/proxy-management.md#proxy-port-mapping).
@@ -17,7 +17,7 @@ certs:update <app> CRT KEY # Update an SSL Endpoint on an app. Can
dokku nginx:import-ssl <app> < certs.tar
```
> Adding an ssl certificate before deploying an application will result in port mappings being updated. This may cause issues for applications that use non-standard ports, as those may not be automatically detected. Please refer to the [proxy documentation](/dokku/advanced-usage/proxy-management/) for information as to how to reconfigure the mappings.
> Adding an ssl certificate before deploying an application will result in port mappings being updated. This may cause issues for applications that use non-standard ports, as those may not be automatically detected. Please refer to the [proxy documentation](/docs/advanced-usage/proxy-management.md) for information as to how to reconfigure the mappings.
When an SSL certificate is associated to an application, the certificate will be associated with *all* domains currently associated with said application. Your certificate _should_ be associated with all of those domains, otherwise accessing the application will result in SSL errors. If you wish to remove one of the domains from the application, refer to the [domain configuration documentation](/dokku/configuration/domains/).
When an SSL certificate is associated to an application, the certificate will be associated with *all* domains currently associated with said application. Your certificate _should_ be associated with all of those domains, otherwise accessing the application will result in SSL errors. If you wish to remove one of the domains from the application, refer to the [domain configuration documentation](/docs/configuration/domains.md).
Note that with the default nginx template, requests will be redirected to the `https` version of the domain. If this is not the desired state of request resolution, you may customize the nginx template in use. For more details, see the [nginx documentation](/dokku/configuration/nginx/).
Note that with the default nginx template, requests will be redirected to the `https` version of the domain. If this is not the desired state of request resolution, you may customize the nginx template in use. For more details, see the [nginx documentation](/docs/configuration/nginx.md).
### Certificate generation
@@ -56,7 +56,7 @@ If you decide to obtain a CA signed certificate, you can import that certificate
The `certs:remove` command only works on app-specific certificates. It will `rm` the app-specific tls directory, rebuild the nginx configuration, and reload nginx.
Ssl issuer: C=GB, ST=Greater Manchester, L=Salford, O=COMODO CA Limited, CN=COMODO RSA Domain Validation Secure Server CA
Ssl starts at: Oct 5 00:00:00 2016 GMT
Ssl subject: OU=Domain Control Validated; OU=PositiveSSL Wildcard; CN=*.node-js-sample.org
Ssl subject: OU=Domain Control Validated; OU=PositiveSSL Wildcard; CN=*.node-js-app.org
Ssl verified: self signed.
=====> python-sample
Ssl dir: /home/dokku/python-sample/tls
=====> python-app
Ssl dir: /home/dokku/python-app/tls
Ssl enabled: false
Ssl hostnames:
Ssl expires at:
@@ -90,25 +90,25 @@ dokku certs:report
You can run the command for a specific app also.
```shell
dokku certs:report node-js-sample
dokku certs:report node-js-app
```
```
=====> node-js-sample ssl information
Ssl dir: /home/dokku/node-js-sample/tls
=====> node-js-app ssl information
Ssl dir: /home/dokku/node-js-app/tls
Ssl enabled: true
Ssl hostnames: *.example.org example.org
Ssl hostnames: *.dokku.org dokku.org
Ssl expires at: Oct 5 23:59:59 2019 GMT
Ssl issuer: C=GB, ST=Greater Manchester, L=Salford, O=COMODO CA Limited, CN=COMODO RSA Domain Validation Secure Server CA
Ssl starts at: Oct 5 00:00:00 2016 GMT
Ssl subject: OU=Domain Control Validated; OU=PositiveSSL Wildcard; CN=*.example.org
Ssl subject: OU=Domain Control Validated; OU=PositiveSSL Wildcard; CN=*.dokku.org
Ssl verified: self signed.
```
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
@@ -117,16 +117,20 @@ The [HSTS header](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security)
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.
## HTTP/2 support
Certain versions of nginx have bugs that prevent [HTTP/2](https://nginx.org/en/docs/http/ngx_http_v2_module.html) from properly responding to all clients, thus causing applications to be unavailable. For HTTP/2 to be enabled in your applications' nginx configs, you need to have installed nginx 1.11.5 or higher. See [issue 2435](https://github.com/dokku/dokku/issues/2435) for more details.
## Running behind a load balancer
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](/dokku/configuration/nginx/#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 the following [nginx custom template](/docs/configuration/nginx.md#customizing-the-nginx-configuration)
@@ -162,4 +166,4 @@ This could result in security issue, for example, if your application looks at t
### SSL Port Exposure
When your app is served from port `80` then the `/home/dokku/APP/nginx.conf` file will automatically be updated to instruct nginx to respond to ssl on port 443 as a new cert is added. If your app uses a non-standard port (perhaps you have a dockerfile deploy exposing port `99999`) you may need to manually expose an ssl port via `dokku proxy:ports-add <APP> https:443:99999`.
When your app is served from port `80` then the `/home/dokku/APP/nginx.conf` file will automatically be updated to instruct nginx to respond to ssl on port 443 as a new cert is added. If your app uses a non-standard port (perhaps you have a dockerfile deploy exposing port `99999`) you may need to manually expose an ssl port via `dokku proxy:ports-add <APP> https:443:99999`.
> Note: This walkthrough uses the hostname `dokku.me` in commands. When deploying to your own server, you should set the `DOKKU_DOMAIN` value in the `Vagrantfile` before you initialize the Vagrant VM.
## Deploy tutorial
Once Dokku has been configured with at least one user, applications can be deployed via a`git push` command. To quickly see Dokku deployment in action, you can use the Heroku Ruby on Rails example app.
Once you have configured Dokku with at least one user, you can deploy applications using`git push`. To quickly see Dokku deployment in action, try using [the Heroku Ruby on Rails "Getting Started" app](https://github.com/heroku/ruby-getting-started).
```shell
# from your local machine
# SSH access to github must be enabled on this host
Create the application on the Dokku host. You will need to ssh onto the host to run this command.
SSH into the Dokku host and create the application as follows:
```shell
# on your Dokku host
dokku apps:create ruby-rails-sample
# on the Dokku host
dokku apps:create ruby-getting-started
```
### Create the backing services
When you create a new app, Dokku by default *does not* provide any datastores such as MySQL or PostgreSQL. You will need to install plugins to handle that, but fortunately [Dokku has official plugins](/dokku/community/plugins/#official-plugins-beta) for common datastores. Our sample app requires a PostgreSQL service:
Dokku by default **does not** provide datastores (e.g. MySQL, PostgreSQL) on a newly created app. You can add datastore support by installing plugins, and the Dokku project [provides official plugins](/docs/community/plugins.md#official-plugins-beta) for common datastores.
The Getting Started app requires a PostgreSQL service, so install the plugin and create the related service as follows:
```shell
# on your Dokku host
# on the Dokku host
# install the postgres plugin
# plugin installation requires root, hence the user change
> You can link a single service to multiple applications or use one service per application.
Dokku supports linking a single service to multiple applications as well as linking only one service per application.
### Deploy the app
Now you can deploy the `ruby-rails-sample` app to your Dokku server. All you have to do is add a remote to name the app. Applications are created on-the-fly on the Dokku server.
> Warning: Your app should respect the `PORT` environment variable, otherwise it may not respond to web requests. You can find more information in the [port management documentation](/docs/networking/port-management.md).**
Now you can deploy the `ruby-getting-started` app to your Dokku server. All you have to do is add a remote to name the app. Applications are created on-the-fly on the Dokku server.
```shell
# from your local machine
# the remote username *must* be dokku or pushes will fail
> Note: Some tools may not support the short-upstream syntax referenced above, and you may need to prefix
> the upstream with the scheme `ssh://` like so: `ssh://dokku@dokku.me:ruby-getting-started`
> Please see the [Git](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) documentation for more details.
> Note: Your private key should be registered with `ssh-agent` in your local development environment. If you get a `permission denied` error when pushing, you can register your private key as follows: `ssh-add -k ~/<your private key>`.
After running `git push dokku master`, you should have output similar to this in your terminal:
When the deploy finishes, the application's URL will be shown as seen above.
Once the deploy is complete, the application's web URL will be generated as above.
Dokku supports deploying applications via [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) with [Herokuish](https://github.com/gliderlabs/herokuish#buildpacks) or using a project's [dockerfile](https://docs.docker.com/reference/builder/).
Dokku supports deploying applications via [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) with [Herokuish](https://github.com/gliderlabs/herokuish#buildpacks), as well as by using a project's [Dockerfile](https://docs.docker.com/reference/builder/).
### Deploying non-master branch
Dokku only supports deploying from its master branch, so if you'd like to deploy a different local branch use: ```git push dokku <local branch>:master```
An alternative is to use the `DOKKU_DEPLOY_BRANCH` application config value to specify a branch that should be deployed. The implicit default is master, and this can be modified both at the app and global level:
You can also support pushing multiple branches using the [receive-branch](/dokku/development/plugin-triggers/#receive-branch) plugin trigger in a custom plugin.
### Skipping deployment
If you only want to rebuild and tag a container, you can skip the deployment phase by setting `$DOKKU_SKIP_DEPLOY` to `true` by running:
See the [process scaling documentation](/dokku/deployment/process-management) for more information.
See the [process scaling documentation](/docs/deployment/process-management.md) for more information.
### Deploying with private git submodules
### Deploying with private Git submodules
Dokku uses git locally (i.e. not a docker image) to build its own copy of your app repo, including submodules. This is done as the `dokku` user. Therefore, in order to deploy private git submodules, you'll need to drop your deploy key in `/home/dokku/.ssh/` and potentially add github.com (or your VCS host key) into `/home/dokku/.ssh/known_hosts`. The following test should help confirm you've done it correctly.
Dokku uses Git locally (i.e. not a Docker image) to build its own copy of your app repo, including submodules, as the `dokku` user. This means that in order to deploy private Git submodules, you need to put your deploy key in `/home/dokku/.ssh/` and potentially add `github.com` (or your VCS host key) into `/home/dokku/.ssh/known_hosts`. You can use the following test to confirm your setup is correct:
Dokku is, at its core, a docker container manager. Thus, it does not necessarily play well with other out-of-band processes interacting with the docker daemon. One thing to note as in [issue #1220](https://github.com/dokku/dokku/issues/1220), dokku executes a cleanup function prior to every deployment.
Dokku is, at its core, a Docker container manager. Thus, it does not necessarily play well with other out-of-band processes interacting with the Docker daemon.
As of 0.5.x, this function removes all containers with the label `dokku` where the status is either `dead` or `exited`, as well as all `dangling` images. Previous versions would remove `dead` or `exited` containers, regardless of their label.
Prior to every deployment, Dokku will execute a cleanup function. As of 0.5.x, the cleanup removes all containers with the `dokku` label where the status is either `dead` or `exited` (previous versions would remove _all_ `dead` or `exited` containers). The cleanup function also removes all images with `dangling` status.
## Adding deploy users
See the [user management documentation](/dokku/deployment/user-management).
See the [user management documentation](/docs/deployment/user-management.md).
## Default vhost
See the [nginx documentation](/dokku/configuration/nginx/#default-site).
See the [nginx documentation](/docs/configuration/nginx.md#default-site).
## Deploying non-master branch
See the [Git documentation](/docs/deployment/methods/git.md#changing-the-deploy-branch).
## Dockerfile deployment
See the [dockerfile documentation](/dokku/deployment/methods/dockerfiles/).
## Specifying a custom buildpack
See the [buildpack documentation](/dokku/deployment/methods/buildpacks/).
See the [Dockerfile documentation](/docs/deployment/methods/dockerfiles.md).
## Image tagging
See the [image tagging documentation](/dokku/deployment/methods/images/).
See the [image tagging documentation](/docs/deployment/methods/images.md).
## Specifying a custom buildpack
See the [buildpack documentation](/docs/deployment/methods/buildpacks.md).
## Removing a deployed app
See the [application management documentation](/dokku/deployment/application-management/#removing-a-deployed-app).
See the [application management documentation](/docs/deployment/application-management.md#removing-a-deployed-app).
### Renaming a deployed app
## Renaming a deployed app
See the [application management documentation](/dokku/deployment/application-management/#renaming-a-deployed-app).
See the [application management documentation](/docs/deployment/application-management.md#renaming-a-deployed-app).
## Zero downtime deploy
See the [zero-downtime deploy documentation](/dokku/deployment/zero-downtime-deploys/).
See the [zero-downtime deploy documentation](/docs/deployment/zero-downtime-deploys.md).
apps:locked <app> # Checks if an app is locked for deployment
apps:rename <old-app> <new-app> # Rename an app
apps:report [<app>] [<flag>] # Display report about an app
apps:unlock <app> # Unlocks an app for deployment
```
## Usage
### Listing Applications
### Listing applications
> New as of 0.8.1. Use the `apps` command for older versions.
@@ -29,7 +33,7 @@ node-js-app
python-app
```
Note that you can easily hide extra output from Dokku commands by using the `--quiet` flag, which makes it easier to parse on the command-line.
Note that you can easily hide extra output from Dokku commands by using the `--quiet` flag, which makes it easier to parse on the commandline.
```shell
dokku --quiet apps:list
@@ -40,6 +44,20 @@ node-js-app
python-app
```
### Checking if an application exists
For CI/CD pipelines, it may be useful to see if an application exists before creating a "review" application for a specific branch. You can do so via the `apps:exists` command:
```shell
dokku apps:exists node-js-app
```
```
App does not exist
```
The `apps:exists` command will return non-zero if the application does not exist, and zero if it does.
### Manually creating an application
A common pattern for deploying applications to Dokku is to configure an application before deploying it. You can do so via the `apps:create` command:
@@ -54,9 +72,9 @@ Creating node-js-app... done
Once created, you can configure the application as normal, and deploy the application whenever ready. This is useful for cases where you may wish to do any of the following kinds of tasks:
Destroying an application will unlink all linked services and destroy any config related to the application. Note that linked services will retain their data for later use (or removal).
### Renaming a deployed app
@@ -119,9 +136,9 @@ This will copy all of your app's contents into a new app directory with the name
### Cloning an existing app
> New as of 0.8.1
> New as of 0.11.5
You can clone an existing app using the `apps:clone` command. Note that the application *must* have been deployed at least once, or the rename will not complete successfully:
You can clone an existing app using the `apps:clone` command. Note that the application *must* have been deployed at least once, or cloning will not complete successfully:
This will copy all of your app's contents into a new app directory with the name of your choice and then rebuild the new version of the app and deploy it. All of your config variables, including database urls, will be preserved.
This will copy all of your app's contents into a new app directory with the name of your choice and then rebuild the new version of the app and deploy it with the following caveats:
> Warning: If you have exposed specific ports via docker-options, added generic domains, or performed anything that cannot be done against multiple applications, `apps:clone` may result in errors.
- All of your environment variables, including database urls, will be preserved.
- Custom domains are not applied to the new app.
- SSL certificates will not be copied to the new app.
- Port mappings with the scheme `https` and host-port `443` will be skipped.
> Warning: If you have exposed specific ports via `docker-options` plugin, or performed anything that cannot be done against multiple applications, `apps:clone` may result in errors.
By default, Dokku will deploy this new application, though you can skip the deploy by using the `--skip-deploy` flag:
@@ -141,7 +163,61 @@ By default, Dokku will deploy this new application, though you can skip the depl
Finally, if the application already exists, you may wish to ignore errors resulting from attempting to clone over it. To do so, you can use the `--ignore-existing` flag. A warning will be emitted, but the command will return `0`.
If you wish to disable deploying for a period of time, this can be done via deploy locks. Normally, deploy locks exist only for the duration of a deploy so as to avoid deploys from colliding, but a deploy lock can be created by running the `apps:lock` command.
```shell
dokku apps:lock node-js-app
```
```
-----> Deploy lock created
```
### Unlocking app deploys
> New as of 0.11.6
In some cases, it may be necessary to remove an existing deploy lock. This can be performed via the `apps:unlock` command.
> Warning: Removing the deploy lock *will not* stop in progress deploys. At this time, in progress deploys will need to be manually terminated by someone with server access.
```shell
dokku apps:unlock node-js-app
```
```
! A deploy may be in progress.
! Removing the app lock will not stop in progress deploys.
-----> Deploy lock removed.
```
### Checking lock status
> New as of 0.13.0
In some cases, you may wish to inspect the state of an app lock. To do so, you can issue an `apps:lock` command. This will exit non-zero if there is no app lock in place.
```shell
dokku apps:locked node-js-app
```
```
Deploy lock does not exist
```
### Displaying reports for an app
> New as of 0.8.1
@@ -154,16 +230,16 @@ dokku apps:report
```
=====> node-js-app
App dir: /home/dokku/node-js-app
Git sha: dbddc3f
App cid: 7b18489c98be
Status: running
Git sha: dbddc3f
Deploy source:git
Locked: false
=====> python-sample
not deployed
=====> ruby-sample
App dir: /home/dokku/ruby-sample
Git sha: a2d477c
App cid: 78a44d71012a
Status: running
Deploy source: git
Locked: false
```
You can run the command for a specific app also.
@@ -175,9 +251,9 @@ dokku apps:report node-js-app
```
=====> node-js-app
App dir: /home/dokku/node-js-app
Git sha: dbddc3f
App cid: 7b18489c98be
Status: running
Git sha: dbddc3f
Deploy source:git
Locked: false
```
You can pass flags which will output only the value of the specific information you want. For example:
logs:failed [<app>] # Shows the last failed deploy logs
```
## Usage
### Application Logs
You can easily get logs of an application using the `logs` command:
### Application logs
You can easily get logs of an app using the `logs` command:
```shell
dokku logs node-js-app
```
## Behavioral modifiers
#### Behavioral modifiers
Dokku also supports certain command-line arguments that augment the `log` command's behavior.
@@ -26,8 +28,26 @@ Dokku also supports certain command-line arguments that augment the `log` comman
You can use these modifiers as follows:
```shell
dokku logs node-js-app -t -p web
```
will show logs continually from the web process.
### Failed deploy logs
> Warning: The default `docker-local` scheduler will "store" these until the next deploy or until the old containers are garbage collected - whichever runs first. If you require the logs beyond this point in time, please ship the logs to a centralized log server.
In some cases, it may be useful to retrieve the logs from a previously failed deploy.
You can retrieve these logs by using the `logs:failed` command
```shell
dokku logs:failed node-js-app
```
You can also retrieve the failed logs for each app:
Dokku normally defaults to using [heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, though this may be overridden by committing a valid `Dockerfile` to the root of your repository and pushing the repository to your Dokku installation. To avoid this automatic `Dockerfile` deployment detection, you may do one of the following:
> Subcommands new as of 0.15.0
- Use `dokku config:set` to set the `BUILDPACK_URL` environment variable.
- Add `BUILDPACK_URL` to a committed `.env` file in the root of your repository.
- See the [environment variable documentation](/dokku/configuration/environment-variables/) for more details.
```
buildpacks:add [--index 1] <app> <buildpack> # Add new app buildpack while inserting into list of buildpacks if necessary
buildpacks:clear <app> # Clear all buildpacks set on the app
buildpacks:list <app> # List all buildpacks for an app
buildpacks:remove <app> <buildpack> # Remove a buildpack set on the app
buildpacks:report [<app>] [<flag>] # Displays a buildpack report for one or more apps
buildpacks:set [--index 1] <app> <buildpack> # Set new app buildpack at a given position defaulting to the first buildpack if no index is specified
```
> Warning: If using the `buildpacks` plugin, be sure to unset any `BUILDPACK_URL` and remove any such entries from a committed `.env` file. A specified `BUILDPACK_URL` will always override a `.buildpacks` file or the buildpacks plugin.
Dokku normally defaults to using [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, though this may be overridden by committing a valid `Dockerfile` to the root of your repository and pushing the repository to your Dokku installation. To avoid this automatic `Dockerfile` deployment detection, you may do one of the following:
- Set a `BUILDPACK_URL` environment variable
- This can be done via `dokku config:set` or via a committed `.env` file in the root of the repository. See the [environment variable documentation](/docs/configuration/environment-variables.md) for more details.
- Create a `.buildpacks` file in the root of your repository.
- This can be via a committed `.buildpacks` file or managed via the `buildpacks` plugin commands.
## Specifying a custom buildpack
This page will cover usage of the `buildpacks` plugin.
In certain cases you may want to specify a custom buildpack. While Dokku uses herokuish to support all the [official heroku buildpacks](https://github.com/gliderlabs/herokuish#buildpacks), it is possible that the buildpack detection does not work well for your application. As well, you may wish to use a custom buildpack to handle specific application logic.
## Usage
To use a specific buildpack, you can run the following Dokku command:
### Listing Buildpacks in Use
The `buildpacks:list` command can be used to show buildpacks that have been set for an app. This will omit any auto-detected buildpacks.
```shell
# replace REPOSITORY_URL with your buildpack's url
Please check the documentation for your particular buildpack as you may need to include configuration files (such as a Procfile) in your project root.
```
-----> test buildpack urls
```
## Using multiple buildpacks
You can only set a single buildpack using the `BUILDPACK_URL`, though there may be times when you wish to use multiple buildpacks. To do so, simply create a `.buildpacks` file in the base of your repository. This file should list all the buildpacks, one-per-line. For instance, if you wish to use both the `nodejs` and `ruby` buildpacks, your `.buildpacks` file should contain the following:
> Please check the documentation for your particular buildpack as you may need to include configuration files (such as a Procfile) in your project root.
To add a custom buildpack, use the `buildpacks:add` command:
In some cases, it may be necessary to swap out a given buildpack. Rather than needing to re-specify each buildpack, the `buildpacks:set` command can be used to overwrite a buildpack at a given position.
By default, this will overwrite the _first_ buildpack specified. To specify an index, the `--index` flag may be used. This flag is specified starting at a 1-index value, and defaults to `1`.
> Always remember to pin your buildpack versions when using the multi-buildpacks method, or you may find deploys changing your deployed environment.
You may also choose to set just a single buildpack in this file, though that is up to you.
Please check the documentation for your particular buildpack(s) as you may need to include configuration files (such as a Procfile) in your project root.
## Using a specific buildpack version
As Dokku pins all buildpacks via herokuish releases, there may be occasions where a local buildpack version is out of date. If you wish to use a more recent version of the buildpack, you may use any of the above methods to specify a buildpack **without** the git sha attached like so:
By default, Dokku uses the [gliderlabs/herokuish](https://github.com/gliderlabs/herokuish/) project, which pins all of it's vendored buildpacks. There may be occasions where the pinned version results in a broken deploy, or does not have a particular feature that is required to build your project. To use a more recent version of a given buildpack, the buildpack may be specified *without* a Git commit SHA like so:
You may also wish to use a **specific** version of a buildpack, which is also simple
This will use the latest commit on the `master` branch of the specified buildpack. To pin to a newer version of a buildpack, a sha may also be specified by using the form `REPOSITORY_URL#COMMIT_SHA`, where `COMMIT_SHA` is any tree-ish git object - usually a git tag.
While many buildpacks have a default command that is run when a detected repository is pushed, it is possible to override this command via a Procfile. A Procfile can also be used to specify multiple commands, each of which is subject to process scaling. See the [process scaling documentation](/dokku/deployment/process-management/) for more details around scaling individual processes.
While many buildpacks have a default command that is run when a detected repository is pushed, it is possible to override this command via a Procfile. A Procfile can also be used to specify multiple commands, each of which is subject to process scaling. See the [process scaling documentation](/docs/deployment/process-management.md) for more details around scaling individual processes.
A Procfile is a file named `Procfile`. It should be named `Procfile` exactly, and not anything else. For example, `Procfile.txt` is not valid. The file should be a simple text file.
The `web` process type holds some significance in that it is the only process type that is automatically scaled to `1` on the initial application deploy. See the [process scaling documentation](/dokku/deployment/process-management/) for more details around scaling individual processes.
The `web` process type holds some significance in that it is the only process type that is automatically scaled to `1` on the initial application deploy. See the [process scaling documentation](/docs/deployment/process-management.md) for more details around scaling individual processes.
## Curl Build Timeouts
Certain buildpacks may time out in retrieving dependencies via curl. This can happen when your network connection is poor or if there is significant network congestion. You may see a message similar to `gzip: stdin: unexpected end of file` after a curl command.
### `curl` build timeouts
If you see output similar this when deploying , you may need to override the curl timeouts to increase the length of time allotted to those tasks. You can do so via the `config` plugin:
Certain buildpacks may time out in retrieving dependencies via `curl`. This can happen when your network connection is poor or if there is significant network congestion. You may see a message similar to `gzip: stdin: unexpected end of file` after a `curl` command.
If you see output similar this when deploying , you may need to override the `curl` timeouts to increase the length of time allotted to those tasks. You can do so via the `config` plugin:
While Dokku normally defaults to using [heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, you can also use docker's native `Dockerfile` system to define a container.
While Dokku normally defaults to using [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, you can also use Docker's native `Dockerfile` system to define a container.
> Dockerfile support is considered a **Power User** feature. By using Dockerfile-based deployment, you agree that you will not have the same comfort as that enjoyed by Buildpack users, and Dokku features may work differently. Differences between the two systems will be documented here.
> Dockerfile support is considered a *power user* feature. By using Dockerfile-based deployment, you agree that you will not have the same comfort as that enjoyed by buildpack users, and Dokku features may work differently. Differences between the two systems will be documented here.
To use a dockerfiles for deployment, commit a valid `Dockerfile` to the root of your repository and push the repository to your Dokku installation. If this file is detected, Dokku will default to using it to construct containers **except** in the following two cases:
To use a Dockerfile for deployment, commit a valid `Dockerfile` to the root of your repository and push the repository to your Dokku installation. If this file is detected, Dokku will default to using it to construct containers *except* in the following two cases:
- The application has a `BUILDPACK_URL` environment variable set via the `dokku config:set` command or in a committed `.env` file. In this case, Dokku will use your specified buildpack.
- The application has a `.buildpacks` file in the root of the repository. In this case, Dokku will use your specified buildpack(s).
## Exposed ports
## Switching from buildpack deployments
> Changed as of 0.5.0
If an application was previously deployed via buildpacks, the following commands should be run before a Dockerfile deploy will succeed:
Dokku will extract all tcp ports exposed using the `EXPOSE` directive (one port per line) and setup nginx to proxy the same port numbers to listen publicly. If you would like to change the exposed port, you should do so within your `Dockerfile` and app.
> Note: Nginx does not support proxying UDP. UDP ports can be exposed by disabling the nginx proxy with `dokku proxy:disable myapp`
## Build-time configuration variables
If you do not explicitly `EXPOSE` a port in your `Dockerfile`, Dokku will configure the nginx proxy to listen on port 80 (and 443 for TLS) and forward traffic to your app listening on port 5000 inside the container. Just like buildpack apps, you can also use the `$PORT` environment variable in your app to maintain portability.
For security reasons - and as per [Docker recommendations](https://github.com/docker/docker/issues/13490) - Dockerfile-based deploys have variables available only during runtime.
When ports are exposed through the default nginx proxy, they are proxied externally as HTTP ports. At this time, in no case do we proxy plain TCP or UDP ports. If you would like to investigate alternative proxy methods, please refer to our [proxy management documentation](/dokku/advanced-usage/proxy-management/).
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):
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.
Once set, the Dockerfile usage would be as follows:
```Dockerfile
FROMdebian:jessie
# set the argument default
ARGNODE_ENV=production
# use the argument
RUNecho$NODE_ENV
```
You may also set the argument as an environment variable
```Dockerfile
FROMdebian:jessie
# set the argument default
ARGNODE_ENV=production
# assign it to an environment variable
# we can wrap the variable in brackets
ENV NODE_ENV ${NODE_ENV}
# or omit them completely
# use the argument
RUNecho$NODE_ENV
```
## Customizing the run command
By default no arguments are passed to `docker run` when deploying the container and the `CMD` or `ENTRYPOINT` defined in the `Dockerfile` are executed. You can take advantage of docker ability of overriding the `CMD` or passing parameters to your `ENTRYPOINT` setting `$DOKKU_DOCKERFILE_START_CMD`. Let's say for example you are deploying a base nodejs image, with the following `ENTRYPOINT`:
By default no arguments are passed to `docker run` when deploying the container and the `CMD` or `ENTRYPOINT` defined in the `Dockerfile` are executed. You can take advantage of docker ability of overriding the `CMD` or passing parameters to your `ENTRYPOINT` setting `$DOKKU_DOCKERFILE_START_CMD`. Let's say for example you are deploying a base Node.js image, with the following `ENTRYPOINT`:
Setting `$DOKKU_DOCKERFILE_CACHE_BUILD` to `true` or `false` will enable or disable docker's image layer cache. Lastly, for more granular build control, you may also pass any `docker build` option to `docker`, by setting `$DOKKU_DOCKER_BUILD_OPTS`.
Setting `$DOKKU_DOCKERFILE_CACHE_BUILD` to `true` or `false` will enable or disable Docker's image layer cache. Lastly, for more granular build control, you may also pass any `docker build` option to `docker`, by setting `$DOKKU_DOCKER_BUILD_OPTS`.
### Procfiles and Multiple Processes
### Procfiles and multiple processes
> New as of 0.5.0
You can also customize the run command using a `Procfile`, much like you would on Heroku or
with a buildpack deployed app. The `Procfile` should contain one or more lines defining [process
types and associated commands](https://devcenter.heroku.com/articles/procfile#declaring-process-types).
When you deploy your app a Docker image will be built, the `Procfile` will be extracted from the image
with a buildpack deployed app. The `Procfile` should contain one or more lines defining [process types and associated commands](https://devcenter.heroku.com/articles/procfile#declaring-process-types).
When you deploy your app, a Docker image will be built. The `Procfile` will be extracted from the image
(it must be in the folder defined in your `Dockerfile` as `WORKDIR` or `/app`) and the commands
in it will be passed to `docker run` to start your process(es). Here's an example `Procfile`:
@@ -72,3 +113,7 @@ a worker container for this app, you can run `dokku ps:scale worker=1` and a new
started by running `docker run bin/run-worker.sh` (the actual `docker run` commands are a bit more
complex, but this is the basic idea). If you use an `ENTRYPOINT` in your `Dockerfile`, the lines
in your `Procfile` will be passed as arguments to the `ENTRYPOINT` script instead of being executed.
## Exposed ports
See the [port management documentation](/docs/networking/port-management.md).
git:initialize <app> # Initialize a git repository for an app
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-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 both [Buildpack](/docs/deployment/methods/buildpacks.md) and [Dockerfile](/docs/deployment/methods/dockerfiles.md).
## Usage
### Initializing an application
When an application is created via `git push`, Dokku will create the proper `pre-receive` hook in order to execute the build pipeline. In certain cases - such as when fronting deploys with the [`git-http-backend`](https://git-scm.com/docs/git-http-backend) - this may not be correctly created. As an alternative, the `git:initialize` command can be used to trigger this creation:
```shell
# on the Dokku host
# overrides any existing pre-receive hook
dokku git:initialize node-js-app
```
In order for the above command to succeed, the application *must* already exist.
> Warning: If the `pre-receive` hook was customized in any way, this will overwrite that hook with the current defaults for Dokku.
### Changing the deploy branch
By default, Dokku will deploy code pushed to the `master` branch. In order to quickly deploy a different local branch, the following Git command can be used:
```shell
# on the local machine
# where `SOME_BRANCH_NAME` is the name of the branch
git push dokku SOME_BRANCH_NAME:master
```
In `0.12.0`, the correct way to change the deploy branch is to use the `git:set` Dokku command.
Pushing multiple branches can also be supported by creating a [receive-branch](/docs/development/plugin-triggers.md#receive-branch) plugin trigger in a custom plugin.
### Configuring the `GIT_REV` environment variable
> New as of 0.12.0
Application deployments will include a special `GIT_REV` environment variable containing the current deployment sha being deployed. For rebuilds, this SHA will remain the same.
To configure the name of the `GIT_REV` environment variable, run the `git:set` command as follows:
The Dokku tags plugin allows you to add docker image tags to the currently deployed app image for versioning and subsequent deployment.
The Dokku tags plugin allows you to add Docker image tags to the currently deployed app image for versioning and subsequent deployment.
> When triggering `dokku ps:rebuild APP` on an application deployed via the `tags` plugin, the following may occur:
>
> - Applications previously deployed via another method (`git`/`tar`): The application may revert to a state before the latest custom image tag was deployed.
> - Applications that were only ever deployed via the `tags` plugin: No action will be taken against your application.
>
> Please use the `tags:deploy` command when redeploying an application deployed via docker image.
> Please use the `tags:deploy` command when redeploying an application deployed via Docker image.
## Usage
### Exposed ports
See the [port management documentation](/docs/networking/port-management.md).
### Listing tags for an application
For example, you can list all tags for a given application:
@@ -36,7 +40,7 @@ dokku/node-js-app latest 936a42f25901 About a minute ago
### Creating a tag
You can also create new tags for that app using the `tags:create` function. Tags should conform to the docker tagging specification for your docker version. As of 1.10, that specification is available [here](https://github.com/docker/docker/blob/master/image/spec/v1.1.md), while users of older versions can check the documentation [here](https://github.com/docker/docker/blob/master/image/spec/v1.md).
You can also create new tags for that app using the `tags:create` function. Tags should conform to the Docker tagging specification for your Docker version. As of 1.10, that specification is available [here](https://github.com/docker/docker/blob/master/image/spec/v1.1.md), while users of older versions can check the documentation [here](https://github.com/docker/docker/blob/master/image/spec/v1.md).
```shell
dokku tags:create node-js-app v1
@@ -61,7 +65,9 @@ dokku/node-js-app v1 936a42f25901 About a minute ago
### Deploying an image tag
Finally, you can also deploy a local image using the `tags:deploy` command.
Finally, you can also deploy a local image using the `tags:deploy` command. When specifying a tag that is not `latest`, the released image will be retagged as the `latest` image tag for the app.
> Warning: For images based on Herokuish, using the `tags:deploy` command will reset environment variables written into the image, causing a retag to occur. This will - on average - add two extra layers to your deployed image. Note that this does not affect Dockerfile-based images, which are the majority of images deployed via the `tags` command.
You can alternatively add image pulled from a docker Registry and deploy app from it by using tagging feature. In this example, we are deploying from Docker Hub.
You can alternatively add image pulled from a Docker registry and deploy from it by using tagging feature. In this example, we are deploying from Docker Hub.
1. Create Dokku app as usual
1. Create Dokku app as usual.
```shell
dokku apps:create test-app
```
2. Pull image from Docker Hub
2. Pull image from Docker Hub.
```shell
docker pull demo-repo/some-image:v12
```
3. Retag the image to match the created app
3. Retag the image to match the created app.
```shell
docker tag demo-repo/some-image:v12 dokku/test-app:v12
```
4. Deploy tag
4. Deploy tag.
```shell
dokku tags:deploy test-app v12
```
> Note: When deploying an image, we will use `docker inspect` to extract the `ExposedPorts` configuration and if defined, use that to populate `DOKKU_DOCKERFILE_PORTS`. If this behavior is not desired, you can override that configuration variable with the `config:set` command.
@@ -18,7 +18,7 @@ tar:in <app> # Reads an tarball containing the
### Deploying from a tarball
In some cases, it may be useful to deploy an application from a tarball. For instance, if you implemented a non-git based deployment plugin, tarring the generated artifact may be an easier route to interface with the existing Dokku infrastructure.
In some cases, it may be useful to deploy an application from a tarball. For instance, if you implemented a non-Git based deployment plugin, tarring the generated artifact may be an easier route to interface with the existing Dokku infrastructure.
You can place the tarball on an external webserver and deploy via the `tar:from` command.
@@ -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 the environment of an application
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:
@@ -61,7 +64,7 @@ dokku --rm run node-js-app some-command
dokku --rm-container run node-js-app some-command
```
For tasks that should not be interrupted, run is the **preferred** method of handling cron tasks, as the container will continue running even during a deploy or scaling event. The trade-off is that there will be an increase in memory usage if there are multiple concurrent tasks running.
For tasks that should not be interrupted, run is the *preferred* method of handling cron tasks, as the container will continue running even during a deploy or scaling event. The trade-off is that there will be an increase in memory usage if there are multiple concurrent tasks running.
## Entering existing containers
@@ -79,7 +82,7 @@ dokku enter node-js-app web.1
dokku enter node-js-app --container-id ID
```
Additionally, you can run `enter` with no container-type. If only a single container-type is defined in your app, you will be dropped into the only running container. This behavior is not supported when specifying a custom command; as described below.
Additionally, you can run `enter` with no `<container-type>`. If only a single `<container-type>` is defined in your app, you will be dropped into the only running container. This behavior is not supported when specifying a custom command; as described below.
By default, it runs a `/bin/bash`, but can also be used to run a custom command:
@@ -93,7 +96,7 @@ dokku enter node-js-app web python script/background-worker.py
### Using `enter` for cron tasks
Your procfile can have the following entry:
Your Procfile can have the following entry:
```Procfile
cron: sleep infinity
@@ -113,34 +116,34 @@ dokku enter node-js-app cron some-command
Note that you can also run multiple commands at the same time to reduce memory usage, though that may result in polluting the container environment.
For tasks that will properly resume, you **should** use the above method, as running tasks will be interrupted during deploys and scaling events, and subsequent commands will always run with the latest container. Note that if you scale the cron container down, this may interrupt proper running of the task.
For tasks that will properly resume, you *should* use the above method, as running tasks will be interrupted during deploys and scaling events, and subsequent commands will always run with the latest container. Note that if you scale the cron container down, this may interrupt proper running of the task.
## General Cron Recommendations
## General cron recommendations
Regularly scheduled tasks can be a bit of a pain with dokku. The following are general recommendations to follow to help ensure successful task runs.
Regularly scheduled tasks can be a bit of a pain with Dokku. The following are general recommendations to follow to help ensure successful task runs.
- Use the `dokku` user's crontab
- If you do not, the `dokku` binary will attempt to execute with `sudo` dokku, and your cron run with fail with `sudo: no tty present and no askpass program specified`
- Use the `dokku` user's crontab.
- If you do not, the `dokku` binary will attempt to execute with `sudo`, and your cron run with fail with `sudo: no tty present and no askpass program specified`.
- Add a `MAILTO` environment variable to ship cron emails to yourself.
- Add a `PATH` environment variable or specify the full path to binaries on the host.
- Add a `SHELL` environment variable to specify bash when running commands.
- Add a `SHELL` environment variable to specify Bash when running commands.
- Keep your cron tasks in time-sorted order.
- Keep your server time in UTC so you don't need to translate daylight saving's time when reading the cronfile.
- Keep your server time in UTC so you don't need to translate daylight savings time when reading the cronfile.
- Run tasks at the lowest traffic times if possible.
- Use cron to **trigger** jobs, not run them. Use a real queuing system such as rabbitmq to actually process jobs.
- Use cron to *trigger* jobs, not run them. Use a real queuing system such as rabbitmq to actually process jobs.
- Try to keep tasks quiet so that mails only send on errors.
- Do not silence standard error or standard out. If you silence the former, you will miss failures. Silencing the latter means you should actually make application changes to handle log levels.
- Use a service such as [Dead Man's Snitch](https://deadmanssnitch.com) to verify that cron tasks completed successfully.
- Add lots of comments to your cronfile, including what a task is doing, so that you don't spend time deciphering the file later.
- Place your cronfiles in a pattern such as `/etc/cron.d/APP`.
- Do not use non-ascii characters in your cronfile names. Cron is finicky.
- Remember to have trailing newlines in your cronfile! Cron is finicky.
- Do not use non-ASCII characters in your cronfile names. cron is finicky.
- Remember to have trailing newlines in your cronfile! cron is finicky.
The following is a sample cronfile that you can use for your applications:
By default, Dokku will only start a single `web` process - if defined - though process scaling can be managed by the `ps` plugin or [via a custom `DOKKU_SCALE` file](/dokku/deployment/process-management/#manually-managing-process-scaling).
By default, Dokku will only start a single `web` process - if defined - though process scaling can be managed by the `ps` plugin or [via a custom `DOKKU_SCALE` file](/docs/deployment/process-management.md#manually-managing-process-scaling).
> The `web` proctype is the only proctype that will invoke custom checks as defined by a CHECKS file. It is also the only process type that will be launched in a container that is either proxied via nginx or bound to an external port.
> The `web` proctype is the only proctype that will invoke custom checks as defined by a `CHECKS` file. It is also the only process type that will be launched in a container that is either proxied via nginx or bound to an external port.
## Usage
@@ -30,9 +33,21 @@ To find out if your application's containers are running the commands you expect
dokku ps node-js-app
```
### Inspecting app containers
> New as of 0.13.0
A common administrative task to perform is calling `docker inspect` on the containers that are running for an application. This can be an error-prone task to perform, and may also reveal sensitive environment variables if not done correctly. Dokku provides a wrapper around this command via the `ps:inspect` command:
```shell
dokku ps:inspect node-js-app
```
This command will gather all the running container IDs for your application and call `docker inspect`, sanitizing the output data so it can be copy-pasted elsewhere safely.
### Rebuilding applications
There are some Dokku commands which will not automatically rebuild an application's environment, or which can be told to skip a rebuild. For instance, you may wish to run multiple `config:set` commands without a restart so as to speed up configuration. In these cases, you can ultimately trigger an application rebuild using `ps:rebuild`
There are some Dokku commands which will not automatically rebuild an application's environment, or which can be told to skip a rebuild. For instance, you may wish to run multiple `config:set` commands without a restart so as to speed up configuration. In these cases, you can ultimately trigger an application rebuild using `ps:rebuild`
```shell
dokku ps:rebuild node-js-app
@@ -45,13 +60,13 @@ dokku ps:rebuildall
```
> The `ps:rebuild` and `ps:rebuildall` commands only work for applications for which there is a source, and thus
> will only always work deterministically for git-deployed application. Please see
> the [images documentation](/dokku/deployment/methods/images/) and [tar documentation](/dokku/deployment/methods/tar/)
> will only always work deterministically for Git-deployed application. Please see
> the [images documentation](/docs/deployment/methods/images.md) and [tar documentation](/docs/deployment/methods/tar.md)
> in for more information concerning rebuilding those applications.
### Restarting applications
Applications can be restarted, which is functionally identical to calling the `release_and_deploy` function on an application. Please not that any linked containers *must* be started before the application in order to have a successful boot.
Applications can be restarted, which is functionally identical to calling the `release_and_deploy` function on an application. Please note that any linked containers *must* be started before the application in order to have a successful boot.
```shell
dokku ps:restart node-js-app
@@ -93,12 +108,18 @@ dokku ps:scale node-js-app
### Stopping applications
Deployed applications can be stopped using the `ps:stop` command. This turns all running containers for an application, and will result in a `502 Bad Gateway` response for the default nginx proxy implementation.
Deployed applications can be stopped using the `ps:stop` command. This turns off all running containers for an application, and will result in a **502 Bad Gateway** response for the default nginx proxy implementation.
```shell
dokku ps:stop node-js-app
```
You may also stop all applications at once:
```shell
dokku ps:stopall
```
### Starting applications
All stopped containers can be started using the `ps:start` command. This is similar to running `ps:restart`, except no action will be taken if the application containers are running.
@@ -107,7 +128,17 @@ All stopped containers can be started using the `ps:start` command. This is simi
dokku ps:start node-js-app
```
## Restart Policies
### Starting all applications
In some cases, it may be necessary to start all applications from scratch - e.g. if all Docker containers have been manually stopped. This can be executed via the `ps:startall` command, which supports parallelism in the same manner `ps:rebuildall`, `ps:restartall`, and `ps:stopall` do.
Be aware that no action will be taken if the application containers are running.
```shell
dokku ps:startall
```
## Restart policies
> New as of 0.7.0
@@ -115,7 +146,7 @@ By default, Dokku will automatically restart containers that exit with a non-zer
### Showing the current restart policy
THe `ps:restart-policy` command will show the currently configured restart policy for an application. The default policy is `on-failure:10`
The `ps:restart-policy` command will show the currently configured restart policy for an application. The default policy is `on-failure:10`
```shell
dokku ps:restart-policy node-js-app
@@ -179,7 +210,7 @@ Restart policies have no bearing on server reboot, and Dokku will always attempt
## Manually managing process scaling
You can optionally _commit_ a `DOKKU_SCALE` file to the root of your repository - *not* to the /home/dokku/APP directory. Dokku expects this file to contain one line for every process defined in your Procfile.
You can optionally *commit* a `DOKKU_SCALE` file to the root of your repository - *not* to the `/home/dokku/APP` directory. Dokku expects this file to contain one line for every process defined in your Procfile.
Example:
@@ -190,4 +221,4 @@ worker=2
If it is not committed to the repository, the `DOKKU_SCALE` file will otherwise be automatically generated based on your `ps:scale` settings.
> *NOTE*: Dokku will always use the DOKKU_SCALE file that ships with the repo to override any local settings.
> *NOTE*: Dokku will always use the `DOKKU_SCALE` file that ships with the repo to override any local settings.
Dokku commands can be run over ssh. Anywhere you would run `dokku <command>`, just run `ssh -t dokku@dokku.me <command>`
Dokku commands can be run over SSH. Anywhere you would run `dokku <command>`, just run `ssh -t dokku@dokku.me <command>`
The `-t` is used to request a pty. It is highly recommended to do so.
To avoid the need to type the `-t` option each time, simply create/modify a section in the `.ssh/config` on the client side, as follows:
@@ -11,8 +11,8 @@ Host dokku.me
## Behavioral modifiers
Dokku also supports certain command-line arguments that augment it's behavior. If using these over ssh, you must use the form `ssh -t dokku@dokku.me -- <command>`
in order to avoid ssh interpretting Dokku arguments for itself.
Dokku also supports certain commandline arguments that augment its behavior. If using these over SSH, you must use the form `ssh -t dokku@dokku.me -- <command>`
in order to avoid SSH interpretting Dokku arguments for itself.
```
--quiet suppress output headers
@@ -25,4 +25,4 @@ in order to avoid ssh interpretting Dokku arguments for itself.
You may optionally use a client to connect to your Dokku server. Most clients use the configured `git remote` to locate the Dokku server, though some allow for overriding this via an environment variable or flag.
Please refer to the [clients](/dokku/community/clients/) list for more details.
Please refer to the [clients](/docs/community/clients.md) list for more details.
@@ -8,17 +8,17 @@ ssh-keys:list # List of all authorized Dokku pu
ssh-keys:remove <name> # Remove SSH public key by name
```
When pushing to Dokku, ssh keybased authorization is the preferred authentication method, for ease of use and increased security.
When pushing to Dokku, SSH key-based authorization is the preferred authentication method, for ease of use and increased security.
Users in Dokku are managed via the `~/dokku/.ssh/authorized_keys` file. It is **highly** recommended that you follow the steps below to manage users on a Dokku server.
Users in Dokku are managed via the `~/dokku/.ssh/authorized_keys` file. It is *highly* recommended that you follow the steps below to manage users on a Dokku server.
> Users of older versions of Dokku may use the `sshcommand` binary to manage keys instead of the `ssh-keys` plugin. Please refer to the Dokku documentation for your version for more details.
## Usage
### Listing SSH Keys
### Listing SSH keys
You can use the `ssh-keys:list` command to show all configured ssh keys. Any key added via the `dokku-installer` will be associated with the `admin` key name.
You can use the `ssh-keys:list` command to show all configured SSH keys. Any key added via the `dokku-installer` will be associated with the `admin` key name.
```shell
dokku ssh-keys:list
@@ -32,11 +32,11 @@ The output contains the following information:
- SSH Key Fingerprint.
- The `KEY_NAME`.
- A comma separated list of ssh options under the `SSHCOMMAND_ALLOWED_KEYS` name.
- A comma separated list of SSH options under the `SSHCOMMAND_ALLOWED_KEYS` name.
### Adding SSH Keys
### Adding SSH keys
You can add your public key to Dokku with the `ssh-keys:add` command. The output will be the fingerprint of the ssh key:
You can add your public key to Dokku with the `ssh-keys:add` command. The output will be the fingerprint of the SSH key:
`KEY_NAME` is the username prefer to use to refer to this particular key. Including the word `admin` in the name will grant the user privileges to add additional keys remotely.
`KEY_NAME` is the name you want to use to refer to this particular key. Including the word `admin` in the name will grant the user privileges to add additional keys remotely.
> `KEY_NAME` is a unique name which is used to identify public keys. Attempting to re-use a key name will result in an error. The ssh (git) user is *always* `dokku`, as this is the system user that the `dokku` binary uses to perform all it's actions.
> `KEY_NAME` is a unique name which is used to identify public keys. Attempting to re-use a key name will result in an error. The SSH (Git) user is *always* `dokku`, as this is the system user that the `dokku` binary uses to perform all its actions.
Admin users and root can also add keys remotely:
Admin users and root can add keys remotely by specifying the `dokku` bin on their `ssh` command:
Finally, if you are using the vagrant installation, you can also use the `make vagrant-acl-add` target to add your public key to Dokku (it will use your host username as the `USER`):
If you are using the Vagrant installation, you can also use the `make vagrant-acl-add` target to add your public key to Dokku (it will use your host username as the `USER`):
```shell
cat ~/.ssh/id_rsa.pub | make vagrant-acl-add
```
### Removing SSH Keys
### Removing SSH keys
As key names are unique, they can be used to remove a public ssh key.
As key names are unique, they can be used to remove a public SSH key.
Keys are given unique names, which can be used in conjunction with the [user-auth](/dokku/development/plugin-triggers/#user-auth) plugin trigger to handle command authorization. Please see the documentation on that trigger for more information.
Keys are given unique names, which can be used in conjunction with the [user-auth](/docs/development/plugin-triggers.md#user-auth) plugin trigger to handle command authorization. Please see the documentation on that trigger for more information.
## Granting other Unix user accounts Dokku access
Any Unix user account which belongs to the 'sudo' Unix group can run Dokku. However, you may want to give them Dokku access but not full sudo privileges.
Any Unix user account which belongs to the `sudo` Unix group can run Dokku. However, you may want to give them Dokku access but not full sudo privileges.
To allow other Unix user accounts to be able to run Dokku commands, without giving them full sudo access, modify your sudoers configuration.
@@ -11,17 +11,25 @@ checks:run <app> [process-type(s)] Runs zero-downtime checks for all proce
checks:skip <app> [process-type(s)] Skip zero-downtime checks for all processes (or comma-separated process-type list)
```
By default, Dokku will wait `10` seconds after starting each container before assuming it is up and proceeding with the deploy. Once this has occurred for all containers started by for an application, traffic will be switched to point to your new containers. Dokku will also wait a further `60` seconds _after_ the deploy is complete before terminating old containers in order to give time for long running connections to terminate. In either case, you may have more than one container running for a given application.
By default, Dokku will wait `10` seconds after starting each container before assuming it is up and proceeding with the deploy. Once this has occurred for all containers started by for an application, traffic will be switched to point to your new containers. Dokku will also wait a further `60` seconds *after* the deploy is complete before terminating old containers in order to give time for long running connections to terminate. In either case, you may have more than one container running for a given application.
You may both create user-defined checks for web processes using a `CHECKS` file, as well as customize any and all parts of this experience using the checks plugin.
## Configuring Check Settings using the `config` plugin
> Web checks are performed via `curl` on Dokku host. Some application code - such
> as the Django framework - checks for specific hostnames or header values, these
> checks will fail. To avoid this:
>
> - Remove such checks from your code: Modify your application to remove the hostname check completely.
> - Allow checks from all hostnames: Modify your application to accept a dynamically provided hostname.
> - Specify the domain within the check: See below for further documentation.
## Configuring check settings using the `config` plugin
There are certain settings that can be configured via environment variables:
-`DOKKU_DEFAULT_CHECKS_WAIT`: (default: `10`) If no user-defined checks are specified - or if the process being checked is not a `web` process - this is the period of time Dokku will wait before checking that a container is still running.
-`DOKKU_DOCKER_STOP_TIMEOUT`: (default: `10`) Configurable grace period given to the `docker stop` command. If a container has not stopped by this time, a `kill -9` signal or equivalent is sent in order to force-terminate the container. Both the `ps:stop` and `apps:destroy` commands _also_ respect this value. If not specified, the docker defaults for the [docker stop command](https://docs.docker.com/engine/reference/commandline/stop/) will be used.
-`DOKKU_WAIT_TO_RETIRE`: (default: `60`) 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.
-`DOKKU_DOCKER_STOP_TIMEOUT`: (default: `10`) Configurable grace period given to the `docker stop` command. If a container has not stopped by this time, a `kill -9` signal or equivalent is sent in order to force-terminate the container. Both the `ps:stop` and `apps:destroy` commands *also* respect this value. If not specified, the Docker defaults for the [`docker stop` command](https://docs.docker.com/engine/reference/commandline/stop/) will be used.
-`DOKKU_WAIT_TO_RETIRE`: (default: `60`) 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.
The following settings may also be specified in the `CHECKS` file, though are available as environment variables in order to ease application reuse.
Zero-downtime checks can also be disabled completely. This will stop old containers **before** new ones start, which may result in broken connections and downtime if your application fails to boot properly.
Zerodowntime checks can also be disabled completely. This will stop old containers *before* new ones start, which may result in broken connections and downtime if your application fails to boot properly.
If your application needs a longer period to boot up - perhaps to load data into memory, or because of slow boot time - you may also use dokku's `checks` functionality to more precisely check whether an application can serve traffic or not.
If your application needs a longer period to boot up - perhaps to load data into memory, or because of slow boot time - you may also use Dokku's `checks` functionality to more precisely check whether an application can serve traffic or not.
Checks are run against the detected `web` process from your application's `Procfile`. For non-web processes, Dokku will fallback to the aforementioned process uptime check.
To specify checks, add a `CHECKS` file to the root of your project directory. The `CHECKS` file should be plain text and may contain:
-Check instructions
-Settings (NAME=VALUE)
-Comments (lines starting with #)
-Empty lines
-check instructions
-settings (NAME=VALUE)
-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-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.
### Check Instructions
### Check instructions
The format of a check instruction is a path or relative URL, optionally followed by the expected content:
@@ -137,20 +145,20 @@ The `CHECKS` file can contain multiple checks:
To check an application that supports multiple hostnames, use relative URLs that include the hostname:
```
//admin.example.com Admin Dashboard
//static.example.com/logo.png
//admin.dokku.me Admin Dashboard
//static.dokku.me/logo.png
```
You can also specify the protocol to explicitly check HTTPS requests:
```
https://admin.example.com Admin Dashboard
https://static.example.com/logo.png
https://admin.dokku.me Admin Dashboard
https://static.dokku.me/logo.png
```
While a full url may be used in order to invoke checks, if you are using relative urls, the port *must* be omitted.
While a full URL may be used in order to invoke checks, if you are using relative URLs, the port *must* be omitted.
### Check Settings
### Check settings
The default behavior is to wait for `5` seconds before running the checks, to timeout the checks after `30` seconds, and to attempt the checks `5` times. If the checks fail `5` times, the deployment is considered failed and the old container will continue serving traffic.
@@ -164,7 +172,7 @@ ATTEMPTS=10 # Attempt checks 10 times
/ My Amazing App
```
## Manually Invoking Checks
## Manually invoking checks
Checks can also be manually invoked via the `checks:run` command. This can be used to check the status of an application via cron to provide integration with external healthchecking software.
In this example, a Rails application is successfully deployed to dokku. The initial round of checks fails while the server is starting, but once it starts they succeed and the deployment is successful. `WAIT` is set to `10` because our application takes a while to boot up. `ATTEMPTS` is set to `6`, but the third attempt succeeds.
In this example, a Rails application is successfully deployed to Dokku. The initial round of checks fails while the server is starting, but once it starts they succeed and the deployment is successful. `WAIT` is set to `10` because our application takes a while to boot up. `ATTEMPTS` is set to `6`, but the third attempt succeeds.
### CHECKS file
### `CHECKS` file
```
WAIT=10
@@ -268,9 +276,9 @@ For this check to work, we've added a line to `config/routes.rb` that simply ret
get '/check.txt', to: proc {[200, {}, ['simple_check']]}
```
### Deploy Output
### Deploy output
> Note: The output has been trimmed for brevity
> Note: The output has been trimmed for brevity.
```shell
git push dokku master
@@ -278,7 +286,7 @@ git push dokku master
```
-----> Cleaning up...
-----> Building myapp from herokuish...
-----> Building node-js-app from herokuish...
-----> Adding BUILD_ENV to build environment...
-----> Ruby app detected
-----> Compiling Ruby/Rails
@@ -288,8 +296,8 @@ git push dokku master
-----> Discovering process types
Procfile declares types -> web
-----> Releasing myapp...
-----> Deploying myapp...
-----> Releasing node-js-app...
-----> Deploying node-js-app...
-----> Running pre-flight checks
-----> Attempt 1/6 Waiting for 10 seconds ...
CHECKS expected result:
@@ -307,7 +315,7 @@ curl: (7) Failed to connect to 172.17.0.155 port 5000: Connection refused
CHECKS expected result:
http://localhost/check.txt => "simple_check"
-----> All checks successful!
=====> myapp container output:
=====> node-js-app container output:
=> Booting Thin
=> Rails 4.2.0 application starting in production on http://0.0.0.0:5000
=> Run `rails server -h` for more startup options
@@ -315,24 +323,24 @@ curl: (7) Failed to connect to 172.17.0.155 port 5000: Connection refused
Thin web server (v1.6.3 codename Protein Powder)
Maximum connections set to 1024
Listening on 0.0.0.0:5000, CTRL+C to stop
=====> end myapp container output
=====> end node-js-app container output
-----> Running post-deploy
-----> Configuring myapp.dokku.example.com...
-----> Configuring myapp.dokku.me...
-----> Creating http nginx.conf
-----> Running nginx-pre-reload
Reloading nginx
-----> Shutting down old container in 60 seconds
=====> Application deployed:
http://myapp.dokku.example.com
http://myapp.dokku.me
```
## Example: Failing Rails Deployment
## Example: Failing Rails deployment
In this example, a Rails application fails to deploy. The reason for the failure is that the postgres database connection fails. The initial checks will fail while we wait for the server to start up, just like in the above example. However, once the server does start accepting connections, we will see an error 500 due to the postgres database connection failure.
In this example, a Rails application fails to deploy. The reason for the failure is that the PostgreSQL database connection fails. The initial checks will fail while we wait for the server to start up, just like in the above example. However, once the server does start accepting connections, we will see an error 500 due to the PostgreSQL database connection failure.
Once the attempts have been exceeded, the deployment fails and we see the container output, which shows the Postgres connection errors.
Once the attempts have been exceeded, the deployment fails and we see the container output, which shows the PostgreSQL connection errors.
### CHECKS file
### `CHECKS` file
```
WAIT=10
@@ -340,11 +348,11 @@ ATTEMPTS=6
/
```
> The check to the root url '/' would normally access the database.
> The check to the root url `/` would normally access the database.
### Deploy Output
### Deploy output
> Note: The output has been trimmed for brevity
> Note: The output has been trimmed for brevity.
```shell
git push dokku master
@@ -352,7 +360,7 @@ git push dokku master
```
-----> Cleaning up...
-----> Building myapp from herokuish...
-----> Building node-js-app from herokuish...
-----> Adding BUILD_ENV to build environment...
-----> Ruby app detected
-----> Compiling Ruby/Rails
@@ -362,8 +370,8 @@ git push dokku master
Discovering process types
Procfile declares types -> web
Releasing myapp...
Deploying myapp...
Releasing node-js-app...
Deploying node-js-app...
Running pre-flight checks
-----> Attempt 1/6 Waiting for 10 seconds ...
CHECKS expected result:
@@ -402,7 +410,7 @@ curl: (22) The requested URL returned error: 500 Internal Server Error
curl: (22) The requested URL returned error: 500 Internal Server Error
Could not start due to 1 failed checks.
! Check attempt 6/6 failed.
=====> myapp container output:
=====> node-js-app container output:
=> Booting Thin
=> Rails 4.2.0 application starting in production on http://0.0.0.0:5000
=> Run `rails server -h` for more startup options
@@ -423,9 +431,9 @@ Could not start due to 1 failed checks.
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.
1. Take a look at the plugins shipped with Dokku and hack away!
2. Check out the [list of triggers](/dokku/development/plugin-triggers) your plugin can implement.
3.Upload your plugin to github with a repository name in form of `dokku-<name>` (e.g. `dokku-mariadb`)
4.Edit [this page](/dokku/community/plugins/) and add a link to it.
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) 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.)
### Sample plugin
The below plugin is a dummy `dokku hello` plugin.
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.
hello/subcommands/default
## 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
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" 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" 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:
[[ -z $2]]&& dokku_log_fail "Please specify an app to run the command on"
verify_app_name "$2"
localAPP="$2";
echo"Hello world"
}
@@ -68,11 +272,12 @@ hello_world_cmd() {
hello_world_cmd "$@"
```
hello/commands
`hello/commands`
```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)
@@ -107,53 +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:
- Don't forget to `chmod +x` your executable files.
- You should always support `DOKKU_TRACE` as specified on the 2nd line of the plugin.
- If your command requires that an application exists, ensure you check for it's existence in the manner prescribed above.
- A `help` command is required, though it is allowed to be empty. Also, the command syntax will need to separated by `, ` in order to maintain columnar output alignment.
- Commands *should* be namespaced.
- As of 0.3.3, a catch-all should be implemented which exits with a `DOKKU_NOT_IMPLEMENTED_EXIT` code. This allows Dokku to output a `command not found` message.
- Be sure you want 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
```
In the case where the "user/repo" is not installed, Dokku exits just before the awk command,
you will never see the message printed with echo. You just want "set -e" in this case.
Here is the documentation of the 'set -eo pipefail' option:
```
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
```
- As some plugins require access to set app config settings and do not want/require the default Heroku-style behavior of a restart, we have the following "internal" commands that provide this functionality :
- From time to time you may 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. Consider all functions in that file to be publicly accessible by other plugins. Any functions not wished to be made "public" should reside within your plugin trigger or commands files.
- As of 0.4.0, we allow image tagging and deployment of said tagged images. Therefore, hard-coding of `$IMAGE` as `dokku/$APP` is no longer sufficient. Instead, for non `pre/post-build-*` plugins, use `get_running_image_tag()` & `get_app_image_name()` as sourced from common/functions. See the [plugin triggers](/dokku/development/plugin-triggers) doc for examples.
- As of 0.5.0, we use container labels to help cleanup intermediate containers with `dokku cleanup`. If manually calling `docker run`, include `$DOKKU_GLOBAL_RUN_ARGS`. This will ensure you intermediate containers labeled correctly.
- As of 0.6.0, we advise you to *not* call the `dokku` binary directly from within plugins. Clients using the `--app` argument are potentially broken, amongst other issues, when doing so. Instead, please source the `functions` file for a given plugin when attempting to call Dokku internal functions
@@ -4,60 +4,22 @@ Dokku is released in intervals *at most* three weeks apart, though may be releas
To propose a release, the following tasks need to be performed:
- Update all blockquote references of `not yet released and only available in master` to point to release version.
- The installable version must be changed in the `contrib/dokku-installer.py` file.
- The installable version must be changed in the `debian/control` file.
- The installable version must be changed in the `docs/home.html` file
- The installable version must be changed in the `docs/installation.md` file.
- The installable version must be changed in the `docs/template.html` file.
- The installable version must be changed in the `README.md` file.
- The embedded css should be cleared in the `docs/template.html` file.
- The versioned links should be updated in the `docs/assets/favicons/browserconfig.xml` file.
- The versioned links should be updated in the `docs/assets/favicons/manifest.json` file.
- The versioned links should be updated in the `docs/assets/style.css` file.
- The versioned links should be updated in the `docs/home.html` file.
- The versioned links should be updated in the `docs/template.html` file.
- The versioned links should be updated or added to the `docs/assets/versions.json` file.
- A list of changes must be made in the `HISTORY.md`.
- A tag must be created locally with your release version
- Debian and RPM packages *must* be created via `vagrant up build`
- The packages should be uploaded to packagecloud.io
- All changes are pushed to master and the tag should be turned into a release which will contain the changelog.
- ArchLinux package description *must* be updated via `vagrant up build-arch` (needs to be done after the tag is pushed to GitHub, because it is based on that)
```shell
exportPACKAGECLOUD_TOKEN=SOME_TOKEN
# supports major/minor/patch/betafish
contrib/release-dokku
```
> If you are a maintainer and need the PACKAGECLOUD_TOKEN in order to make a release, please contact @josegonzalez to get this information.
As well, the ArchLinux package description *must* be updated via `vagrant up build-arch` (needs to be done after the tag is pushed to GitHub, because it is based on that)
## Versioning
Dokku follows semver standards. As we are not yet at a stable release, breaking changes will require *only* a minor release, while all other changes only require a patch release. Once we hit stable, breaking changes will require a major release.
Tags should be created via the following method:
```shell
git tag v0.9.9
```
At the moment, tags need not be signed, though that may change in the future.
## Debian and RPM packages
The `build` target in the Dokku `Vagrantfile` creates debian and rpm packages for Dokku at a point in time. The version will be based upon the latest local tag - you may create your own, internal tags/releases if that is so desired.
Debian package information is held in the `debian` directory of the Dokku project.
For the public project, releases should be pushed to packagecloud.io *after* a tag is created but *before* said tag is pushed to github. The following may be the release workflow:
If new versions of other packages were created, these should also be pushed at this time.
> If you are a maintainer and need the PACKAGECLOUD_TOKEN in order to make a release, please contact @josegonzalez to get this information.
## ArchLinux Packages
ArchLinux packages are not really build, because all that is needed for an Arch User Repo (AUR) package is the description of how to build the package. To make this process as easy as possible there is a vagrant box called `build-arch` that updates the version of this build description (a file called `PKGBUILD`), then runs some helper scripts to fill all additional information and does test if the package could be build. Then only those changes need to be pushed to the AUR repo and an updated version of the package is ready for usage for our ArchLinux users. For detailed information see the section below.
@@ -67,7 +29,7 @@ The workflow looks like this:
```shell
# having dokku-arch in ../dokku-arch
vagrant up build-arch
# wait for "==> build-arch: ==> Finished making: dokku 0.8.2-2 (Mon Feb 22 23:20:37 CET 2016)"
# wait for "==> build-arch: ==> Finished making: dokku 0.18.5-2 (Mon Feb 22 23:20:37 CET 2016)"
cd ../dokku-arch
git add PKGBUILD .SRCINFO
git commit -m 'Update to dokku 0.9.9'
@@ -76,29 +38,7 @@ git push aur master
> If you are a maintainer and need access to the AUR repositories in order to make a release, please contact @morrisjobke or @josegonzalez to get this co-maintainership.
## Changelog format
The `HISTORY.md` should be added to based on the changes made since the previous release. This can be done by reviewing all merged pull requests to the master branch on github. The format is as follows:
```
## 0.9.9
Some description concerning major changes in this release, or potential incompatibilities.
### New Features
- #SOME_ID: @pull-request-creator Description
### Bug Fixes
- #SOME_ID: @pull-request-creator Description
### Docs Changes
- #SOME_ID: @pull-request-creator Description
```
## Detailed information for ArchLinux packages
### Detailed information for ArchLinux packages
All of the information to build the ArchLinux package is in the AUR git repository (see [dokku AUR page](https://aur.archlinux.org/packages/dokku/)). The release of a AUR package only consists of pushing the package information into the AUR git repo. Then users could use that information to build the package on their machines.
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](/dokku/getting-started/install/vagrant)
- 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:
```shell
@@ -46,3 +56,39 @@ make deploy-test-nodejs-express
```
For a full list of test make targets check out `tests.mk` in the root of the Dokku repository.
## Executing a single test suite
When working on a particular plugin, it may be useful to run _only_ a particular test suite. This can be done by specifying the test suite path:
```shell
bats tests/unit/10_apps.bats
```
It is also possible to target multiple test suites at a time.
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.
If you plan on developing dokku, the easiest way to install from your own repository is cloning the repository and calling the install script. Example:
If you plan on developing Dokku, the easiest way to install from your own repository is cloning the repository and calling the install script. Example:
Dokku ships with a pre-built version of version of the [herokuish](https://github.com/gliderlabs/herokuish) component by default. If you want to build your own version you can specify that with an env variable.
Dokku ships with a pre-built version of version of the [Herokuish](https://github.com/gliderlabs/herokuish) component by default. If you want to build your own version you can specify that with an environment variable.
```shell
git clone https://github.com/dokku/dokku.git
@@ -44,25 +44,29 @@ cd dokku
sudo BUILD_STACK=trueSTACK_URL=https://github.com/gliderlabs/herokuish.git make install
```
## Configuring
## Skipping Herokuish installation
Once Dokku is installed, if you are not using the web-installer, you'll want to configure a the virtualhost setup as well as the push user. If you do not, your installation will be considered incomplete and you will not be able to deploy applications.
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.
## Configuring an unattended installation
Once Dokku is installed, if you are not using the web-installer, you'll want to configure the virtualhost setup as well as the push user. If you do not, your installation will be considered incomplete and you will not be able to deploy applications.
For Debian, unattended installation is described [Debian installation guide](/docs/getting-started/install/debian.md).
*You should also stop and disable the `dokku-installer` service to remove public access to adding SSH keys.*
Set up a domain and a wildcard domain pointing to that host. Make sure `/home/dokku/VHOST` is set to this domain. By default it's set to whatever hostname the host has. This file is only created if the hostname can be resolved by dig (`dig +short $(hostname -f)`). Otherwise you have to create the file manually and set it to your preferred domain. If this file still is not present when you push your app, Dokku will publish the app with a port number (i.e. `http://example.com:49154` - note the missing subdomain).
Set up a domain using your preferred vendor and a wildcard domain pointing to the host running Dokku. You can manage this global domain using the [domains plugin](/docs/configuration/domains.md).
Follow the [user management documentation](/dokku/deployment/user-management/) in order to add users to Dokku, or to give other Unix accounts access to Dokku.
Follow the [user management documentation](/docs/deployment/user-management.md) in order to add SSH keys for users to Dokku, or to give other Unix accounts access to Dokku.
That's it!
## VMs with less than 1 GB of memory
## VMs with less than 1GB of memory
Having less than 1GB of system memory available for Dokku and its containers may result in unexpected errors, such as `! [remote rejected] master -> master (pre-receive hook declined)` during installation of NPM dependencies (https://github.com/npm/npm/issues/3867).
Having less than 1GB of system memory available for Dokku and its containers, for example Digital Ocean's small 512MB machines, might result in unexpected errors, such as **! [remote rejected] master -> master (pre-receive hook declined)** during installation of NPM dependencies (https://github.com/npm/npm/issues/3867).
To work around this issue, it might suffice to augment the Linux swap file size to a maximum of twice the physical memory size.
To work around this issue, it might suffice to augment the linux swap file size to a maximum of twice the physical memory size.
To resize the swap file of a 512MB machine to 1GB, follow these steps while in SSH within your machine:
To resize the swap file of a 512 MB machine to 1 GB, follow these steps while in SSH within your machine:
- If you don't already have one [generate an SSH key pair](https://help.github.com/articles/generating-ssh-keys/).
1. If you don't already have one [generate an SSH key pair](https://help.github.com/articles/generating-ssh-keys/).
- Go to the [Dokku on azure deployment page](https://github.com/azure/azure-quickstart-templates/tree/master/dokku-vm) and click **Deploy to Azure**.
2. Go to the [Dokku on Azure deployment page](https://github.com/azure/azure-quickstart-templates/tree/master/dokku-vm) and click **Deploy to Azure**.
- You'll be prompted to enter a few parameters, including a unique storage account name and a unique name for the sub-domain used for your public IP address. For the `sshKeyData` parameter, copy and paste the contents of the **public** key file you just created. After a few minutes the Dokku instance will be deployed.
3. You'll be prompted to enter a few parameters, including a unique storage account name and a unique name for the subdomain used for your public IP address. For the `sshKeyData` parameter, copy and paste the contents of the *public* key file you just created. After a few minutes the Dokku instance will be deployed.
- In your browser of choice, navigate to `http://[[dnsNameForPublicIP]].[[location]].cloudapp.azure.com`. Where `[[dnsNameForPublicIP]]` and `[[location]]` are template parameters you used to deploy the template.
4. In your browser of choice, navigate to `http://[dnsNameForPublicIP].[location].cloudapp.azure.com`. Where `[dnsNameForPublicIP]` and `[location]` are template parameters you used to deploy the template.
- Finish your Dokku setup like you normally would by creating a **new** public/private key pair for your deployments using `ssh-keygen` (don't use the same one as you created in the first step). You should select 'Use Virtual Host Naming' and set the `Hostname` to a **public dns name** that you own such as one you would purchase from [namecheap](http://namecheap.com). Alternatively thanks to [xip.io](http://xip.io/) you can just use yourAzurePublicIP.xip.io for free. For example, if your public IP is `44.44.44.44` then you would set it to `44.44.44.44.xip.io`.
5. Finish your Dokku setup like you normally would by creating a *new* public/private key pair for your deployments using `ssh-keygen` (don't use the same one as you created in the first step). You should select **Use Virtual Host Naming** and set the **Hostname** to a *public DNS name* that you own such as one you would purchase from [Namecheap](http://namecheap.com). Alternatively thanks to [xip.io](http://xip.io/) you can just use `[yourAzurePublicIP].xip.io` for free. For example, if your public IP is `44.44.44.44` then you would set it to `44.44.44.44.xip.io`.
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:
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:
echo"deb https://packagecloud.io/dokku/dokku/ubuntu/ ${OS_ID} main"| sudo tee /etc/apt/sources.list.d/dokku.list
sudo apt-get update -qq >/dev/null
sudo apt-get install -qq -y dokku
sudo dokku plugin:install-dependencies --core
```
## Unattended installation
In case you want to perform an unattended installation of dokku, this is made possible through [debconf](https://en.wikipedia.org/wiki/Debconf_%28software_package%29), which allows you to configure a package before installing it.
In case you want to perform an unattended installation of Dokku, this is made possible through [debconf](https://en.wikipedia.org/wiki/Debconf_%28software_package%29), which allows you to configure a package before installing it.
You can set any of the below options through the `debconf-set-selections` command, for example to enable vhost-based deployments:
@@ -35,7 +37,8 @@ After setting the desired options, proceed with the installation as described ab
| dokku/hostname | string | dokku.me | Hostname, used as vhost domain and for showing app URL after deploy |
| dokku/skip_key_file| boolean | false | Don't check for the existence of the dokku/key_file. Warning: This setting this to true, will require you to manually add an SSH key later on. |
| dokku/skip_key_file| boolean | false | Don't check for the existence of the dokku/key_file. Warning: Setting this to true, will require you to manually add an SSH key later on. |
| dokku/key_file | string | /root/.ssh/id_rsa.pub | Path on disk to an SSH key to add to the Dokku user (Will be ignored on `dpkg-reconfigure`) |
On DigitalOcean, there is a pre-made image that can be run for Dokku. You can choose to run this image on any sized droplet, though larger droplets will allow you to run larger applications.
[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.
When choosing your Droplet configuration, please disable IPv6 on the droplet. There are known issues with IPv6 on DigitalOcean and Docker, and many have been reported to the Dokku issue tracker.
> **Please disable IPv6**. There are known issues with IPv6 on DigitalOcean and Docker. If you would like to run Dokku on an IPv6 DigitalOcean Droplet, please consult [this guide](https://jeffloughridge.wordpress.com/2015/01/17/native-ipv6-functionality-in-docker/).
If you would like to run Dokku on an IPv6 DigitalOcean Droplet, please consult [this guide](https://jeffloughridge.wordpress.com/2015/01/17/native-ipv6-functionality-in-docker/) for modifying Docker to run under the Digital Ocean IPv6 configuration.
Once Dokku is installed, you can then proceed to the ip address or domain name associated with your server to complete the web-based installation.
If you wish for a more unattended installation method, see [these](http://dokku.viewdocs.io/dokku/getting-started/install/debian/#unattended-installation) docs.
1. Login to your [DigitalOcean](https://m.do.co/c/fe06b043a083) account.
2. Click **Create a Droplet**.
3. Under **Choose an image > One-click apps**, choose the latest **Dokku** release for 16.04 _(version numbers may vary)_.
4. Under **Choose a size**, select your machine spec.
5. Under **Choose a datacenter region**, select your region.
6. Add an SSH Key.
* New Keys
1. Under **Add your SSH keys** click **New SSH Key**_(this opens a dialog)_.
2. From your terminal, execute `cat $HOME/.ssh/id_rsa.pub`.
3. Copy the output and paste it into the **New SSH Key** dialog, provide a name and click **Add SSH Key**.
* Existing Keys
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.
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.
