This hook will allow users to modify the repo in use for deployed applications. An example use case would be one where the image being deployed is from a remote docker registry where the `dokku` username is taken and the app will be deployed from a separate username.
- Ensure we document all commands being run
- Highlight that we are mapping the same port twice
- Clarify how dokku binds containers to listening interfaces
[ci skip]
Fixesdokku/dokku-letsencrypt#67
Change the certs:add command to use a file import without trying to
detect a piped-in tarball if server.crt and server.key files were passed
in as arguments and those files exist.
Fixes hangs on certificate imports by filename when the check for a
STDIN pipe fails e.g. when running dokku remotely using a SSH command.
- note that the port changes on every deploy when the proxy is disabled
- make it clear that the proxy is being disabled for the app
- note that the nginx-vhosts plugin supports the proxy plugin mapping
- minor formatting changes
[ci skip]
This allows users to specify port 80 after an application has had domain added. Normally, when we first add an extra domain, the following tuple is added:
http:80:5000
A user might then want to remap port 80 to another port, such as port 8080:
dokku proxy:ports-add APP http:80:8080
The application would then have the following proxy map:
http:80:5000 http:80:8080
As nginx vhosts are resolved in FIFO order, the "correct" upstream of 8080 would basically be ignored. The workaround would be to remove the original port mapping, but the following:
dokku proxy:ports-remove APP 80
Would remove *both* entries and then re-add the default of `http:80:5000`. Thus it was not possible to use the porcelain to correct the port mapping and a user would have to fall back to using the following hack to fix their mapping:
dokku config:set APP DOKKU_PROXY_PORT_MAP='http:80:8080'
You can now use the previous syntax *as well as* the following to remove a port mapping:
dokku proxy:ports-remove APP http:80:5000
Newer versions of nginx drop spdy support in favor of http2, and thus the nginx config that we bundle with dokku causes nginx to fail to reload in certain cases. This change drops spdy support in favor of http2 for versions of nginx greater than 1.9.5.
Closes#2216
These are helper plugins that mimic the repo plugin: https://github.com/heroku/heroku-repo
The following commands will remain unimplemented:
- `clone`: not useful for the host client to clone
- `download`: currently not possible for us to "host" a tarball of the repo
- `reset`: we still store files in the repo (though we shouldn't) so we cannot easily reinitialize the repository.
Also fixes a potential race condition if two separate processes create an application's `$CACHE_DIR`.
Closes#1570
In at least one case a customer of ours added a domain including
a schema, as in “http://domain.tld/”. That is obviously incorrect, but
then they couldn't remove it using the dokku command:
$ dokku domains:remove app7 http://domain.tld/
sed: -e expression #1, char 9: unknown command: `/'
This patch changes the sed command to use the "\CregexpC" syntax. The
character used is a vertical pipe, which is far less likely to be used
in a URL. After the change:
$ dokku domains:remove app7 http://domain.tld/
-----> Removed http://domain.tld/ from app7
Signed-off-by: Michael Hanselmann <hansmi@vshn.ch>
When rebooting a Dokku host the init process tries to restore all apps
using `dokku ps:restore`, alphabetically. If an app is defined but not
deployed, the function `ps_start` called by `dokku ps:restore` will
exit 0 and stop trying to restore the other apps later in the alphabet.
This change fixes the restore behaviour.
Currently we exit when trying to add a duplicated domain, even if we give a list
of domain names. This behaviour is not as it suppose to work.
**Expected behaviour**
When adding a domain, and the domain already exists, just skip that domain, and
continue with the world. This is no problem since we are already in the state we
want to be in.
**New behaviour**
When you try to add a domain that is already added, we notify the user of this
by showing a log message: `Skipping: example.com already added to example app`,
and then we continue with the list of domain names.
Fixes#2165
Clearly stress the fact, that there are more steps than only running the bash commands. You also have to navigate to the website and finish the configuration.
- unified css between home and template layouts
- use same version of bootstrap everywhere
- add our cute whale sushi logo to the homepage
- use fewer styles
- add a better installation section to point out different installation methods
- add navigation bar items
[ci skip]
- Tone down "new as of version" boxes
- Replace all "New as of 0.5" with "yet to be released" text
- Use strong red only for "yet to be released" boxes
Fixes#1989
- Briefly cover sshcommand internals
- Show several examples for using sshcommand
- Split out docs onto a new page and relink to it where necessary
- Refer to user-auth plugin trigger for scoping commands to specific users.
[ci skip]
This will allow a user to browse the documentation as it was at any point in time. In doing so, this allows us to more easily deprecate/remove features without worrying about having to duplicate old documentation in the future.
[ci skip]
- Refer to checks plugin in zero-downtime deploy link
- Refer to cron in one off processes link
- Add an "Advanced Usage" section
- Add links to proxy management and deployment tasks
- Move container options and persistent storage to advanced usage
[ci skip]
This change sets a DOKKU_APP_NAME env var, which can be used by plugins as a replacement for the `app` param if specified. Note that each plugin will have to manually shift it's arguments if necessary
* fix rsyslog handling
* don't hardcode dokku path
* add documentation for ArchLinux package build
* add vagrant machine to run the ArchLinux specific steps
* add step in release process for ArchLinux
* enhance docs for easy ArchLinux steps
This pr makes it slightly easier to support dockerfile installations
- "simplifies" the bootstrap process by dividing it into distinct chunks
- Allows specifying `--no-install-recommends` when a dockerfile installation is detected
- Uses functions everywhere
- Removes global variables where possible
- Fixes shellcheck issues
- Allows specifying debconf via the command-line
[ci skip]
There are cases where we don't want the check for keyfile, this will add a
config option, that allows you to skip this particular check.
Fixes#1851
Signed-off-by: Jeroen van Baarsen <jeroenvanbaarsen@gmail.com>
OSX creates hidden files: `./._server.key` and `./._server.crt`. The Dokku cert
plugin is choking on those files. We should probably just ignore them, and go on
with our lives
Signed-off-by: Jeroen van Baarsen <jeroenvanbaarsen@gmail.com>
I was running into issues with the IP addresses, and it seems
that it's using an incorrect/outdated syntax for retrieving
the container's IP Address. In multi-host networking
`NetworkSettings.IPAddress` is empty.
The docker documentation at https://docs.docker.com/engine/reference/commandline/inspect/
uses a different syntax which I've tested to work both on multi-host and
standard bridge networking.
If you're interested in the other issues and the work/hacks I've been doing related
to #1795, let me know. In the meantime, I think this fix is needed.
- remove deployed applications during dpkg purge
- disable all core plugins during dpkg purge
- ensure init files are removed
- ensure motd is removed
- remove all core plugins, dokku config files (including tls/sshcommand entries etc.) during purge
- remove all empty directories and broken symlinks in the DOKKU_ROOT and DOKKU_LIB_ROOT directories during purge
Note that we do not delete the dokku user itself as there might be other data we don't know about in this directory.
We previously assumed that systemd was detectable by the existence of certain directories. Unfortunately, it seems 14.04 already has these directories, so we need to handle this case separately.
One other note is that dokku-installer will fail to "start" if already started on certain systems, thus the previous grep was more accurate in it's running.
- Use the nginx.conf file's existence as a check for whether we should start the service or not
- Create the init files with the dokku-installer.py file. This adds actual systemd support.
- Also ensure we *always* start the service, regardless of it's status. This fixes an issue with processing systemd output
Fixes the following warning:
```
dpkg: warning: parsing file '/var/lib/dpkg/tmp.ci/control' near line 6 package 'dokku':
`Depends' field, reference to `lxc-docker':
`>' is obsolete, use `>=' or `>>' instead
```
Refs #1776
The python version should allow us to remove any ruby dependencies and should also slightly speed up dokku installation. All LSB-compliant distributions should have python, so we should be okay depending upon it.
Closes#1783Closes#1786
It's not possible to checkout a specific commit into a new repository
using ``git fetch`` and so a temporary tag is added to the host
repository, then fetched.
This adds a hook that will send in the $APP, action name and config vars.
By adding this, we allow plugin creators to handle this kind of events as well.
Signed-off-by: Jeroen van Baarsen <jeroenvanbaarsen@gmail.com>
The version of docker.io in jessie-backports is 1.6.2~dfsg1-1~bpo8+1.
This is regarded as lower than 1.6.2 by dpkg because `~` has a special meaning
in regards to version sort in dpkg.
This leads to:
```
The following packages have unmet dependencies:
dokku : Depends: docker-engine-cs but it is not installable or
docker-engine but it is not installable or
lxc-docker (>= 1.6.2) but it is not installable or
docker.io (>= 1.6.2) but 1.6.2~dfsg1-1~bpo8+1 is to be installed
Recommends: herokuish but it is not going to be installed
```
By changing the contraints the version in backports will be accepted by dpkg.
Add this point you only get information that "something" happend on the given
hook. By adding more information to the hook, plugin creators can do more
interesting stuff.
* The first params remains the $APP name (to maintain backwards compatability)
* The second params sends in the action that happend, for domain this can be:
"add", "clear" or "remove"
* The third param sends in the argument that was passed to the original
function, for domain that would be a list of all the domains that was given.
One reason this addition would be great for plugin owners, is that when you have
a web tool over Dokku, and someone creates a domain over the CLI, we a plugin
can send back information about the event to the webapp over an API. That way
the webapp is always up-to-date with the Dokku installation.
Signed-off-by: Jeroen van Baarsen <jeroenvanbaarsen@gmail.com>
In order to be one step closer to lintian compliance, lets remove the shebang
from this file so it doesn;t have to be executable
See #1641
Signed-off-by: Jeroen van Baarsen <jeroenvanbaarsen@gmail.com>
Changing the herokuish package to Recommends instead of Depends allows users to skip the installation of that package by specifying --no-install-recommends. Herokuish will still be installed by default using apt-get
Adds unit test for new apps:rename function.
Add example in the docs for new apps:rename function.
Add apps:rename command to help command.
Delete cache directory before copying old app directory to new app directory.
deploy_app instead of create_app for apps:rename testing.
Change app url to match new name. Fix unit tests.
Add some more tests, plugn triggers.
As of 15.10, we are graced with a relatively recent version of nginx, and thus no longer need access to the ppa. Assuming this is the only such issue, this should also allow us to support Ubuntu 16.04 without any future changes.
I have created a plugin for installing a specific library that is not working properly when installed using dokku-apt.
It took me a lot of time to figure out how to properly install it and therefore I wanted to share it.
- Add note to avoid problems with shared volumes permissions
- Restructure the doc to help comprehension
- Make command examples consistent
- Improve wording in some places
- Advanced usage: remove "avoid if possible". It made little sense.
- docker (project) --> Docker
- dokku (project) --> Dokku
- dokku (command) --> `dokku`
- add `shell` to code blocks
This should consolidate a lot of knowledge around how dokku deals with buildpacks, as well as clears up a few misconceptions - mainly that dokku doesn't support multiple/custom buildpacks.
By bringing this information front-and-center, we can avoid a lot of questions by users trying to use dokku.
[ci skip]
This plugin trigger should allow users to pair down the available commands for a given user. While this does not affect help output - or any output at all - this is a good first step in allowing administrative access to certain commands while still allowing users to deploy/manage given applications.
Note that because of how dokku works, all parsing of commands must be done within the pluginhook, and we cannot give visibility into the actual command or application that will be affected by a given run.
* Bump `Version` field.
* Set minimum nginx version to 1.4.6, per #1654
* Depend on both `rubygem-foo` (Ubuntu) and `ruby-foo` (Debian).
* Add distro-default `docker.io (>= 1.6.2)` as an alternative.
Version 1.6.2 is in both `trusty-updates` and `jessie-backports`,
while `trusty` itself has `0.9.1`. We seriously want to avoid that.
This also updates the docs so people don't forget to bump the version
field in the future. Even though we really do that for them with sed.
In this case, Bats sets $status, $output, and $lines, but ShellCheck
doesn't statically know that. Therefore, we ignore SC2154 when those
variables are first introduced in ./tests/unit/test_helper.bash
https://github.com/koalaman/shellcheck/wiki/SC2154
New version of the logs plugin broke compatibility (as reported in #1534).
So options have been added to handle display:
* -t/--tail to tail logs (already existed)
* -n/--num NUM to display only this number of lines
* -p/--ps PS to display logs only from provided process
* -q/--quiet to display raw logs without color, time and names
This should close#1534
Which is quite useful in some situations, for example when you want each app to point to a DB with the same name as the app (reducing the amount of app-specific config).
I've not yet tested with 0.4.x but asap we upgrade our environment I'll ensure it's compatible (should be super simple since it's a super simple plugin).
This ensures that we can call apt-get update after adding a new apt source. Debian needs a bit more time to refresh it's own caches, so we just force it's cache to be clean before calling apt-get update again.
This package is the version we use for as a dokku dependency, and thus there is no need to specify a *specific* version when building the deb packages.
Refs #976
Blockquote elements that call out a new feature are given a "pink" background, whereas all others are given a "blue" background. This is to help avoid cases where users expect a feature to work for their version when they are several versions behind when a feature was introduced.
Fixes#1495
Log user name and fingerprint in events
Clarify bootstrap installation documentation
We actually have the reverse situation where the bootstrap.sh uses the web installer by default.
[ci skip]
dokku-apt compatibility
Fix for issue #1487:
Created a separated VM environments for developers and users.
Changing default to linux users
Fix for issue #1487:
Created a separated VM environments for developers and users.
Adjusting space
Clarify bootstrap installation documentation
We actually have the reverse situation where the bootstrap.sh uses the web installer by default.
[ci skip]
dokku-apt compatibility
Fix for issue #1487:
Created a separated VM environments for developers and users.
Changing default to linux users
Fix for issue #1487:
Created a separated VM environments for developers and users.
Changing default to linux users
Making dokku the default
Adjusting space
Because of how plugin commands are implemented, their output can be incredibly verbose. Rather than executing even the `set -eo pipefail` parts of a plugin, we immediately check if the command is implemented by a plugin. If it is not, then we continue on as normal.
One side-effect of this change is that plugin commands need to be duplicated again:
- once in the command array
- once for the actual body of the command
- once in the help output
This is also quite hackish, and probably not the best way to decrease trace output. Note that we drop approximately 2k lines worth of logs with this change.
This reduces deploy output by moving `config:get` calls out of the main loop. Since the values are the same for each iteration, it does not make sense to re-retrieve them each time.
Previously a crashed container would stay down, regardless of exit status. In some cases, it may be useful to restart the container. For example, an application may not be correctly implementing their error handling, or the crash may be caused by a transient error.
By setting the restart policy to `on-failure:N` - where N is a number of max restarts - we can help developers guard against crashing applications. Note that this is not a replacement for proper error handling, nor does this include notifications to a developer when a container is restarted. Those patterns should be implemented application side, or via a feature request to docker.
The value is configurable at the app-level by setting DOKKU_RESTART_LIMIT to a number. By default, containers will be restarted a max of 10 times. If a container crashes during the check-deploy plugin trigger, then the deploy will be marked as a failure.
Closes#216Closes#398Closes#1327
This will allow developers to run an `upgrade` on existing installations without breaking because docker-engine isn't yet in their apt lists...
[ci skip]
Rather than having a one-off hack for "blessed" containers, we should solve the issue properly. As that would take a bit more work, reverting to the previous state is preferred.
Better that we solve a problem problem than with a hack that we'll need to roll back in the future.
Refs #1220
[ci skip]
We had an issue with third party plugins installing things via apt while
already installing dokku itself via apt.
To resolve this, `plugins-install` and `plugins-install-dependencies`
now can take a `--core` flag allowing to execute the install hook only
on core plugins and not on third party plugins.
Another feature with this modification is the ability to disable/enable
plugins. Two new commands now exist:
* `plugins:enable <name>` to enable a previously disabled plugin
* `plugins:disable <name>` to disable an installed plugin. This won’t
work on core plugins.
Rather than having a one-off hack for "blessed" containers, we should solve the issue properly. As that would take a bit more work, reverting to the previous state is preferred.
Better that we solve a problem problem than with a hack that we'll need to roll back in the future.
Refs #1220
[ci skip]
This can be used as an alternative to importing via stdin, which may be preferred when working directly on a server, or via scripted installation/deployments.
This should theoretically be safe, as "--export" forces the `dokku config` command to return 0 in all cases, and it should only output lines that are "valid" environment variables
This function - `is_container_status` - can be used to inspect whether a container is any of the following:
- Dead
- OOMKilled
- Paused
- Restarting
- Running
It can be useful for deeper inspection as to plugin state
As briefly discussed in #1425, source the `common/functions` file via an
absolute path, rather than determining the relative path by using
`dirname`. 3rd-party plugins should follow suit and use the new
`$PLUGIN_PATH` convention too.
This will allow users to inspect the underlying environment and conditionally run different commands based upon the `DYNO_TYPE_NUMBER`. The values will be set in the following format:
web.1
web.2
worker.1
worker.2
clock.1
Users of process managing plugins and dockerfiles can check the `DYNO_TYPE_NUMBER` and set a specific command to run.
Closes#1350
This command can be used to enter a running container. The following variations of the command exist:
dokku enter api web
dokku enter api web.1
dokku enter api --container-id ID
By default, it runs a `/bin/bash`, but can also be used to run a custom command:
# just echo hi
dokku enter api web echo hi
# run a long-running command, as one might for a cron task
dokku enter api web python script/background-worker.py
Closes#1332
You can now use the following to narrow down the search for a container id:
get_app_container_ids app web
get_app_container_ids app worker
You can also specify a specific type "id" like so:
get_app_container_ids app web.1
get_app_container_ids app worker.3
Specifying an invalid type or id will result in an empty response
This should allow installation of the dokku packages on debian jessie. Upstream docker created this package in response to an issue where `cgroup-bin` could not be installed at the same time as lxc.
Closes#1236
Refs #1076
[ci skip]
This reverts commit 1bf30bdcb1.
Commit was reverted as this breaks installs of core plugins. It is also a hack around broken plugins that don't use the `dependencies` pluginhook.
This was a big documentation release with a minor bugfix to the `app.json` functionality introduced in 0.5.0.
Thanks to all the contributors who helped with this release!
## 0.6.5
### Bug Fixes
-#2301:@michaelshobbs Fix app.json extraction in dockerfile apps not using /app
### New Features
-#2297:@josegonzalez Add plugin trigger to override the image repository
### Documentation
-#2296:@josegonzalez Add an example plugin trigger for cache busting Dockerfile builds
-#2295:@josegonzalez Add documentation for the apps, repo, and tar plugin
-#2292:@josegonzalez General documentation cleanup
-#2291:@josegonzalez Clean up documentation surrounding persistent storage
-#2289:@PeterDaveHello Optimize png images using zopflipng
-#2282:@prodicus Fixed link to sponsors doc
## 0.6.4
Included in this release are a couple of bug fixes for existing features.
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#2275:@sseemayer Prefer file import in certs:add if files given
-#2279:@michaelshobbs Only attempt to stop a checks-disabled container if it is actually running
### New Features
-#2270:@guillaumewuip Allow apps:destroy when not in a project
-#2271:@josegonzalez Handle purging the dokku user, group, and logs directory during `apt-get purge`
### Documentation
-#2272:@josegonzalez Add documentation surrounding when the /app/.env file is populated
## 0.6.3
This release is mostly a documentation release.
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#2258:@michaelshobbs Support domains that start with digits per RFC1123
### New Features
-#2260:@josegonzalez Add ability to remove a specific port mapping tuple
-#2261:@josegonzalez Drop apparmor requirement to support systemd systems
### Documentation
-#2262:@josegonzalez Document that REV is optional in the receive-app trigger
-#2264:@troy Use Markdown for sponsors page, so it's clickable from GitHub
-#2266:@michaelshobbs Add documentation surrounding proxy port mapping
## 0.6.2
This release is a minor bugfix for the web setup, and also reverts a previous addition to the persistent storage. Please see the pull requests for more details.
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#2256:@michaelshobbs Revert automatically binding storage mounts in build phase
-#2259:@andrewsomething Don't run DeleteInstallerThread() until after set_debconf_selection
## 0.6.1
This release is a minor bugfix to fix an issue with ssl support for spdy-enabled nginx servers. Users are encouraged to upgrade if they have an older version of nginx installed.
### Bug Fixes
-#2250:@michaelshobbs Fix missing $ sign in default nginx template
## 0.6.0
The big-six-o. This release is largely comprised of new features that should allow for easier management of dokku. The highlights of this release are:
- The proxy plugin has been enhanced to allow users to map container ports to host ports. In the 0.5.0 release, we changed the semantics of how Dockerfile `EXPOSE` calls work to better follow Docker's lead, which ended up breaking how some applications were deployed to dokku. Please read our documentation surrounding [port management](http://dokku.viewdocs.io/dokku/proxy/) for more details.
- Zero-downtime deploys can be disabled on a per-app and per-process basis. This can be used to speed up deploys when there are non-web processes being deployed, or when a user wishes to completely avoid any such waiting period. Please see the [checks documentation](http://dokku.viewdocs.io/dokku/checks-examples/) for further information.
Thanks to all the contributors who helped with this release, and a special thanks to @michaelshobbs for ferrying the majority of our new functionality to it's current state!
### Bug Fixes
-#2241:@josegonzalez Set debconf selections from dokku-installer.py
-#2242:@michaelshobbs Avoid calling dokku binary
-#2243:@josegonzalez Nginx 1.9.5+ support
### New Features
-#2018:@pascalw Support running Procfile commands using `dokku run`
-#2050:@josegonzalez Implement repo:gc and repo:purge-cache
-#2109:@josegonzalez Allow user to modify the repository and tag when deploying an app
-#2168:@michaelshobbs Allow zero-downtime deploys to be completely disabled
-#2248:@michaelshobbs Allow users to map container ports to host ports via the proxy plugin
### Documentation
-#2209:@piamancini Added backers and sponsors from OpenCollective
-#2244:@basgys Add InfluxDB to plugins
## 0.5.8
This release is the last release in the `0.5.x` series, and as such is mainly a bugfix release. Users are highly encouraged to upgrade to this release *before* moving to the upcoming `0.6.x` release, as we will be removing deprecated features at that point.
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#2214:@michaelshobbs Remove git push from client
-#2220:@josegonzalez Remove DOKKU_PROCFILE before attempting to extract it
-#2227:@michaelshobbs Pass image tag from release_and_deploy down through extract_procfile
-#2228:@michaelshobbs Support WORKDIR location for DOKKU_SCALE
-#2229:@hansmi Fix removal of domains with schema
-#2234:@michaelshobbs Cleanup container state files when a process type is removed from app
-#2236:@michaelshobbs Hide unnecessary output from is_image_herokuish_based()
-#2233:@josegonzalez Lintian cleanup
### New Features
-#2205:@josegonzalez Fix lintian errors in built debian packages
-#2237:@michaelshobbs Reject invalid domains in domains:add
-#2238:@michaelshobbs Mount storage mounts on build for buildpack deploys
### Documentation
-#2212:@jbothma Warn and instruct users about unsafe publicly-accessible web installer
-#2222:@michaelshobbs Move nginx upstream blocks to the bottom in docs examples
## 0.5.7
0.5.7 includes quite a few documentation updates, and a few minor changes in how we handle certain edge-cases in day-to-day dokku tasks.
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#2157:@michaelshobbs test detached container is running
-#2170:@jvanbaarsen Do not fail domains:add when adding a duplicated domain
-#2171:@tobru Continue to restore applications during boot when any given application does not start
-#2173:@michaelshobbs Add test for ps:restore with undeployed app
-#2202:@michaelshobbs Attempt to bypass inconsistencies in nginx start behavior
### New Features
-#2155:@josegonzalez Add the ability to run containers in detached mode
-#2163:@michaelshobbs Support deployment of arbitrary docker images not built by dokku build
-#2175:@michaelshobbs Show available types and ids on dokku enter error
-#2193:@josegonzalez Upgrade herokuish version built via deb packaging
-#2203: Allow specifying NO_INSTALL_RECOMMENDS via DOKKU_NO_INSTALL_RECOMMENDS in bootstrapped installs
### Documentation
-#2164:@iloveitaly Adding longtimeout and hostname to dokku plugin list
-#2167:@iloveitaly Adding link to rollbar plugin
-#2182:@cu12 Add link to FakeSNS plugin
-#2183:@Epigene Update nginx docs to mirror generated nginx.conf from core
-#2187:@pltchuong Add missing trigger to plugin triggers documentation
-#2190:@cu12 Add ElasticMQ plugin to documentation
-#2191:@josegonzalez Clarify upgrade docs for bootstrap.sh installations
-#2192:@josegonzalez Clarify that the checks are only run against the web process
-#2194:@josegonzalez Clarify the role of process types for buildpack deployment
-#2195:@josegonzalez Clarify when certain plugin triggers are invoked
## 0.5.6
Release 0.5.6 is mostly a documentation release. Please note, however, that we now inject application environment variables into sigil-generated nginx configurations. You can use this to further improve your generated nginx configuration files.
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#2120:@u2mejc Add apex help_content for certs,nginx,storage,tar plugins
-#2122:@michaelshobbs Add 10.0.0.2 so *.dokku.me works
-#2145:@michaelshobbs Fix dockerfile-procfile test
### New Features
-#2150:@michaelshobbs export app config vars into sigil environment for use in nginx templates
### Documentation
-#2099:@ojosdegris Added clarification on configuration via separate files
-#2107:@simenbrekken Add CI deployment recipe
-#2112:@josegonzalez Alphabetize triggers
-#2114:@josegonzalez Add table of contents to sidebar when there is a table of contents
-#2136:@josegonzalez Use `sleep infinity` for enter cron task
-#2142:@Aluxian Add dokku-nginx-cache to the list of plugins
## 0.5.5
Release 0.5.5 is mostly a documentation release, further clarifying how our default proxy implementation (nginx) interacts with Dockerfiles. Note that we also updated how ssl certificates interact with application domains, so please check out our domains and ssl documentation.
We've also added a small section to the [dokku homepage](http://dokku.viewdocs.io/dokku/) that lists the current core team. Feel free to look at their beautiful faces and imagine yourself contributing to Dokku and joining our core team. There are [quite a few ways to contribute](https://github.com/dokku/dokku/blob/master/CONTRIBUTING.md) - even without code/documentation - so feel more than free to jump on the bandwagon!
Finally, we've started an [Official Dokku Blog](https://dokku.github.io/), where we will post about dokku internals, roadmaps, potential use-cases, etc. An rss feed is available [here](https://dokku.github.io/feed.xml).
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#2094:@josegonzalez Create storage directories on install. Closes #2091
-#2102:@josegonzalez Only strip .git directory from end of url
### New Features
-#2088:@josegonzalez Upgrade herokuish package
-#2089:@michaelshobbs Update how ssl and multiple domains interact
### Documentation
-#2076:@josegonzalez Add a note to dockerfile deploys concerning ports being exposed as http
-#2080:@michaelshobbs Clarify the need for contents of dockerfile when debugging
-#2082:@michaelshobbs Add use case example for ssl redirect
-#2083:@louisbl Clarify 0.5.0 migration guide about `EXPOSE`
-#2084:@louisbl Clarify where to put nginx custom template without `WORKDIR`
-#2093:@fwolfst Fix path in storage example
-#2098:@josegonzalez Add a blog link to the header area
-#2100:@kane-c Fix docs navigation link to domain configuration
-#2104:@crisward Added new clone plugin
-#2105:@josegonzalez Add a note about how disabling the proxy affects the host port an application is deployed to
## 0.5.4
This release continues on our tradition of making bugfixes in patch releases. Also note that we now release dokku with `sshcommand` version `0.4.0`, which should increase usability of that package quite a bit.
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#2055:@tobru Move nginx include to server section
-#2060:@michaelshobbs Filter restart policies from exec-app-json containers
-#2061:@znz Fix ignored settings in the CHECKS file
-#2065:@michaelshobbs Fix pre/post deploy support for dockerfile apps
### New Features
-#2052:@josegonzalez Use upstream releases when creating deb packages. Closes #2048
-#2068:@josegonzalez Use latest sshcommand when installing via debian
-#2070:@josegonzalez Upgrade sshcommand to 0.4.0
### Documentation
-#2049:@mmlkrx Fix typo in deployment-tasks.md
-#2051:@plieningerweb Clarify installation instructions in docs
-#2058:@michaelshobbs Remove references to global TLS certs
-#2072:@michaelshobbs Note that we only support one EXPOSE port per line in dockerfiles
## 0.5.3
This release sorts out a few minor bugs introduced in the 0.5.0 release.
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#2030:@josegonzalez Fix setting of APPS in checks command when $1 is left unspecified
-#2035:@stesie Fix ps_restart to not exit early
-#2042:@michaelshobbs Ensure CHECKS file has trailing newline
-#2046:@michaelshobbs Strip inline comments and trailing whitespace from CHECKS and Procfile
-#2047:@michaelshobbs Remove deprecated mktemp args and name vars more clearly
### Documentation
-#2032:@josegonzalez Fix upstream positioning in docs. Closes #2031
-#1922:@josegonzalez Link to our new ISSUE_TEMPLATE.md
## 0.4.13
We lied. *This* is the final 0.4.x release. This specific release fixes support for bash `4.2`, which may be the only bash version available for certain testing environments.
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#1871:@michaelshobbs Support bash 4.2 so we don't have to modify all plugin test envs
-#1872:@kenips Update log to better reflect what's going on with CHECKS
## 0.4.12
This is a small bugfix release, which will be the final release before the 0.5.x line. You can follow along on bugs/features we hope to cleanup for 0.5.x [here](https://github.com/dokku/dokku/milestones/v0.5.0).
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#1868:@alessio Prevent dokku to hang on events:help
-#1870:@u2mejc Remove arg check from docker-options/functions, global var cleanup
## 0.4.11
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#1840:@alessio Append trailing slash '/' to $PLUGIN_DIR
-#1841:@michaelshobbs Don't build nginx config if the app has not been deployed
-#1844:@michaelshobbs Handle multiple old containers and don't attempt to rename a dead container
-#1845:@michaelshobbs Update nodejs in test apps
-#1849:@floriangosse Fix logrotate file for debian system
-#1862:@michaelshobbs Install bash 4.3.x on circleci
-#1863:@znz Fix a typo in IPV6 detection
### New Features
-#1842:@michaelshobbs skip cleanup in ci to speed up tests
-#1848:@u2mejc Move docker-options functions to functions file, rework phase_file_path
-#1855:@jvanbaarsen Add skip_keyfile option for deb package
-#1864:@znz Remove nullglob from ps commands
### Documentation
-#1838:@Epigene Fixed typo in installation documentation
-#1843:@sseemayer Move let's encrypt plugin to official plugins
-#1854:@fedosov Update year in footer (2013-2016)
-#1856:@madflow Fixed dead documentation link
-#1859:@dhinus Fix command for debconf-set-selections
## 0.4.10
This release is mostly a bugfix release, though we have a few important changes:
-`dokku plugin:update` can now be used to update a specific plugin. Previously, this could potentially result in an error a user would have to manually resolve.
- We have started labeling all dokku-managed containers. In a future minor release, triggering a `dokku cleanup` will remove *only* exited containers that are managed by dokku. This change allows users to start containers outside of dokku and be assured that dokku would not inadvertently remove them.
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#1818:@josegonzalez Fix pre-receive git-hook in apps:rename
-#1819:@andrewsomething Write out /home/dokku/HOSTNAME as specified by the web installer.
-#1823:@josegonzalez Fix output formatting of dokku apps
-#1827:@michaelshobbs Use docker 1.9.0 on circleci
-#1834:@jvanbaarsen Make sure we ignore hidden files in the SSL cert check
-#1835:@josegonzalez Add support to herokuish for more versions of docker-engine
-#1837:@michaelshobbs Add back some deploy tests that test dokku functionality
### New Features
-#1826:@michaelshobbs Implement plugn update
-#1828:@michaelshobbs Label all dokku-managed containers
-#1822: --no-restart option after config:set not before
## 0.4.9
This release is significant for two reasons:
- A bugfix for git submodule support that was broken in 0.4.7
- Improved and tested support for modern variants of Ubuntu/Debian. This should also improve support for docker-based deployments of dokku, as well as potential support for the upcoming Ubuntu 16.04 release.
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#1810:@josegonzalez Fix debian packaging for usage inside of docker containers
-#1814:@blackxored Add support for new method of extracting container IP
-#1807:@josegonzalez Allow updating submodules at any revision
### New Features
-#1812:@josegonzalez Fully-tested debian packaging for modern Ubuntu/Debian distributions
### Documentation
-#1811:@josegonzalez Add dokku haproxy to plugins
## 0.4.8
If upgrading to 0.4.8, please note that we have tightened the application naming schema, per docker requirements. Upgrade your dokku installation to 0.4.7 first to take advantage of the `dokku apps:rename` command if you are having issues with the new requirement.
### Bug Fixes
-#1804:@josegonzalez Fix deprecated version constraint usage in debian control file
-#1798:@michaelshobbs Ensure app name begins with lowercase alphanumeric character
-#1808:@josegonzalez Fix path to dokku-installer
### New Features
-#1801:@josegonzalez Allow setting DOKKU_LIB_ROOT env var to modify the lib path on install
-#1803:@michaelshobbs update plugn download url and version
### Documentation
-#1809:@josegonzalez Remove non-zero downtime version of letsencrypt plugin
## 0.4.7
A few notable new features:
- The new `dokku apps:rename` command. It does not update linked containers, but is useful in many other cases.
- Updated git clone methodology to be more performant for large repositories.
- Moved the dokku-installer from Ruby to Python, allowing us to drop Ruby as a dependency. Python comes with the linux standard base, and should therefore be accessible on more systems.
### Bug Fixes
-#1776:@t-8ch Fix docker version constraints on jessie systems
-#1777:@michaelshobbs Format test labels
-#1782:@michaelshobbs make docker cp work on circleci
-#1788:@michaelshobbs Updates for moving of dokku sshcommand and plugn repos
-#1791:@michaelshobbs Don't run app deploy tests and spread out unit tests to 4 containers
-#1793:@michaelshobbs Filter out Procfile comments
### New Features
-#1670:@zachfeldman Add apps:rename
-#1771:@jvanbaarsen Make plugin hooks send out more information
-#1778:@mmerickel Optimize git clone for large repositories
-#1781:@jvanbaarsen Add post config update hook
-#1789:@lvillani Make it possible to skip a deploy
-#1790:@michaelshobbs Use pgup/pgdown for history shortcut in dev env
-#1794:@josegonzalez Replace dokku-installer.rb with dokku-installer.py
-#1797:@michaelshobbs Ensure we run plugin commands as root
-#1799:@josegonzalez Add support for tutum-agent as docker alternative
-#1800:@josegonzalez Respect DOKKU_ROOT in debian/postint
### Documentation
-#1779:@sseemayer Add link to new zero-downtime Let's Encrypt Plugin to docs
-#1780:@jvanbaarsen Add documentation for the new domain plugin hooks
-#1784:@duboff Tiny fix in SSL documentation
## 0.4.6
This is mostly a documentation change. A few notable changes:
- Rebooting dokku servers should properly handle not starting stopped services.
- Better support for newer versions of Debian/Ubuntu.
- Moved the dokku project to the dokku github organization.
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#1717:@josegonzalez Avoid using the PPA for ubuntu versions 15.10 and higher
-#1732:@michaelshobbs do not chown file that doesn't exist
-#1745:@beverku Change herokuish to recommended package
-#1767:@jvanbaarsen Remove shebang from config/functions
-#1775:@Flink Match complete container name in named-containers plugin
### New Features
-#1718:@josegonzalez Add post-create hook
-#1735:@michaelshobbs use ps:restore on instance boot
### Documentation
-#1720:@josegonzalez Add memory usage output as desired data for reporting issues
-#1723:@josegonzalez Add herokuish version to desired debugging info
-#1739:@michaelshobbs clarify location of nginx.conf.template in app repo
-#1747:@josegonzalez Add Lets Encrypt plugin
-#1748:@byrnedo Added unofficial Nats plugin to plugins.md
-#1750:@jlachowski New graphite & statsd plugin with grafana frontend added
-#1751:@josegonzalez Use flat-square style on image badges
-#1752:@byrnedo Moved dokku-nats into official plugins section
-#1753:@hhff Add .ca-bundle information to SSL docs
-#1754:@josegonzalez Update all links to dokku repo
-#1757:@josegonzalez Add DigitalOcean as a sponsor
-#1761:@josegonzalez Fix link to docker-options documentation
## 0.4.5
This release is mostly a bugfix release. Two notable changes:
- It is now possible to build complex authentication layers around dokku using the new user auth plugin trigger introduced in #1671.
- We have a Code of Conduct in our repository. Please refer to this document if you have any questiosn regarding what is acceptable in the Dokku community.
Thanks to all the contributors who helped with this release!
### Bug Fixes
-#1666:@michaelshobbs Revert dokku group changes and add dokku user to adm group
-#1667:@u2mejc Fix dokku certs:add file input bug
-#1682:@michaelshobbs Aet nullglob when looking for PORT files
-#1684:@u2mejc Cause certs:remove to return non zero on error
-#1690:@u2mejc Fix "App tls has not been deployed" error
-#1696:@michaelshobbs chown plugins paths to dokku:dokku
-#1698:@pmvieira Ensure curl is installed inside of source-based installations
-#1700:@michaelshobbs copy nginx.ssl.template from app container
-#1677:@ignlg Added dokku-builders-plugin to plugins page
-#1681:@josegonzalez Fix email in code of conduct
-#1694:@MarcDiethelm Improve docker-options doc
-#1713:@mbriskar Wkhtmltopdf plugin
## 0.4.4
This release adds a few interesting changes:
- The `dokku logs` command now roughly maps to the `heroku logs` command, and supports most available options.
- Native Microsoft Azure support is now available!
- Quite a few shellcheck issues were fixed thanks to @callahad!
- Experimental debian installation support. Going forward, we will try and make dokku compatible with all systemd installations, as well as investigate dockerfile-based deployment to continue simplifying installation.
Thanks to all our contributors for making this release great!
### Bug Fixes
-#1606:@josegonzalez Install plugn 0.2.0 in Makefile installs
-#1643:@Flink Fix generated nginx config when NO_VHOST=1
-#1644:@mmerickel Watch dokku events through a logrotate
-#1647:@callahad Resolve SC2115: 'Use "${var:?}" to ensure this never expands to /'
-#1648:@callahad Resolve SC2154: 'variable is referenced but not assigned'
-#1649:@callahad Resolve SC2164: 'Use cd ... || exit in case cd fails.'
-#1650:@callahad Resolve SC2148: 'target shell is unknown'
-#1651:@callahad Resolve SC2029: 'this expands on client side'
-#1652:@callahad Resolve SC2143: 'Instead of [ -n $(foo | grep bar) ], use foo | grep -q bar'
-#1653:@callahad Resolve SC2145: 'Argument mixes string and array.'
-#1655:@callahad Resolve SC2162: 'read without -r mangles backslashes'
-#1656:@callahad Resolve SC2001: 'See if you can use ${var//search/replace} instead'
-#1660:@callahad Fixup debian/control for Debian
-#1662:@xadh00m Only return users of group 'adm'
### New Features
-#1607:@josegonzalez Dokku support for Debian Jessie installation
-#1610:@kdomanski Add post-stop plugn trigger
-#1612:@Flink Add multiple options to the logs plugin
-#1613:@kdomanski Add ps:restore to start applications which weren't manually stopped
-#1628:@michaelshobbs Move RESTORE variable to DOKKU_APP namespace
-#1634:@callahad Allow installation of bats via homebrew
-#1645:@rvalyi Add ability to access git repo via ssh
-#1664:@michaelshobbs Add $REV to pre-receive-app call
### Documentation
-#1605:@josegonzalez Make commented output a bit more readable
-#1621:@josegonzalez Document `--force` option for `:destroy` commands
-#1623:@sedouard Add Azure Documentation
-#1624:@u2mejc Add trace to help output
-#1626:@josegonzalez Add official dokku-copy-files-to-image plugin
-#1630:@adamwolf Enabling tracing is actually 'dokku trace on'
-#1633:@elia Add a warning regarding the use of `trace on`
This release was mainly a documentation release/bugfix.
One major removal was is that as of 0.4.3, we no longer restart containers automatically on failure via docker. This feature was introduced in 0.4.0, and caused issues with duplicate containers being started on server reboot. Until the docker api for container restarts stabilizes, we will not be able to provide this functionality within Dokku.
If desired, you may replicate this functionality using the official `docker-options` plugin.
### Bug Fixes
-#1560:@darklow Fixes issue where SSL and non-SSL templates cannot be used at the same time
-#1566:@michaelshobbs Fix logic error in enabling nginx
-#1568:@josegonzalez Remove 'connection closed' messages from dokku ssh client
-#1574:@josegonzalez Ensure the user has a valid hostname set during installation
-#1585:@michaelshobbs Ensure dokku can read nginx logs and don't remove other perms
-#1556:@josegonzalez Use proper cdn link for css asset
-#1557:@josegonzalez Code styling changes
-#1561:@josegonzalez Set dokku-acl compatibility to 0.4.0+
-#1562:@josegonzalez Documentation Overhaul
-#1573:@mateusortiz Add link to license
-#1577:@Flink Add official redirect plugin
-#1587:@josegonzalez Update "reporting other issues" to include `docker inspect`
-#1598:@adamwolf Add missing bootstrap.sh step
-#1599:@ssd532 Fix a few grammatical mistakes
-#1601:@ojacquemart Fix typo
-#1604:@josegonzalez Add every type of favicon to all templates
## 0.4.2
This release was mainly a documentation release, with a few notable features:
- You can now use the commercial version of docker-engine with dokku.
- You can now name your containers using the official `named-containers` plugin
Huge thanks to @Flink for working on our official plugins and adding official [basic auth](https://github.com/dokku/dokku-http-auth), [couchdb](https://github.com/dokku/dokku-couchdb), and [site maintenance](https://github.com/dokku/dokku-maintenance) plugins!
### Bug Fixes
-#1530:@Flink Fix nginx configuration for SSL
### New Features
-#1515:@leonardodino Allow local prebuilt stack sourcing
-#1536#1537:@josegonzalez Add docker-engine-cs as docker-engine alternative
-#1511:@Flink Add `named-containers` as a core plugin
### Documentation
-#1520:@kimausloos Add `dokku` command-prefix to `plugin:install` command
-#1519:@3onyc Fix typos in documentation
-#1521:@edm00se Use correct url to bootstrap.sh in README.md
-#1522:@josegonzalez Avoid redirects and use raw.githubusercontent.com for github links
-#1523#1548:@callahad Make room for the longer bootstrap.sh URL
-#1524:@callahad Document idiosyncracies with Linode
-#1529:@pzula Adds helpful information regarding whitespacing when setting config
-#1525#1550:@josegonzalez Add gratipay shield to readme
-#1544#1545#1547#1551:@josegonzalez@Flink Update compatibility for community plugins
-#1546:@josegonzalez Add missing description to history output in HISTORY.md
-#1552#1553#1555:@josegonzalez Various documentation styling tweaks
## 0.4.1
This release is primarily a bugfix and documentation update. In 0.4.0, we incorrectly handled setting environment variables in certain cases, resulting in misconfigured applications. We recommend that all users upgrade from 0.4.1 as soon as possible.
One new feature is colorized logging output, which should make it easier to debug application logging output when deploying multiple processes.
### Bug Fixes
-#1494:@callahad Correctly install packages for DOKKU_TAG=v0.4.0
-#1496:@callahad Don't prompt users when installing dokku package
-#1514:@michaelshobbs Do not use exit 0 in config functions and fix CURL environment variable setting
### New Features
-#1482:@Flink Strip the `dokku-` part from plugins on install
-#1500:@jazzzz Log user name and fingerprint in events
-#1488:@josegonzalez Update plugins list with compatibility changes
-#1491:@josegonzalez Promote [maintenance](https://github.com/dokku/dokku-maintenance) and [http basic auth](https://github.com/dokku/dokku-http-auth) plugins to official status
-#1492:@josegonzalez Upgrade hostname plugin to 0.4.0+ compatibility
-#1504:@michaelshobbs Change plugin install doc to show one-step method
## 0.4.0
This is our first minor release in almost a year. Many new features and removals have occurred, so here is a neat summary:
- Plugins are now triggered via `plugn`. Notably, you'll need add a `plugin.toml` to describe the plugin as well as use `plugn trigger` instead of `pluginhook` to trigger plugin callbacks. Please see the [plugin creation documentation](http://dokku.viewdocs.io/dokku/development/plugin-creation/) for more details.
- A few new official plugins have been added to the core, including [image tagging](http://dokku.viewdocs.io/dokku/application-deployment/), [certificate management](http://dokku.viewdocs.io/dokku/deployment/ssl-configuration/), a tar-based deploy solution, and much more. Check out the *New Features* section for more details.
- We've removed a few deprecated plugin callbacks. Please see the [plugin triggers documentation](http://dokku.viewdocs.io/dokku/development/plugin-triggers/) to see what is available.
- [Official datastorage plugins](https://github.com/dokku) have been created for the most commonly used datastores. If you previously used/maintained a community contributed plugin, please check these out. We'll be adding more official plugins as time goes on.
Thanks to the *many* contributors for making this release our best release so far, and special thanks to both @michaelshobbs and @Flink for pushing along the `0.4.0` release!
### Deprecations and Removals
-#1372:@SonicHedgehog Do no longer force-install a default nginx.conf
-#1450:@michaelshobbs Rename event plugin buildstep hooks to buildpack
### Bug Fixes
-#1344:@AdamVig Add better error checking on nginx:import-ssl
-#1417:@josegonzalez Expose host and port in vagrant build vm
-#1418:@josegonzalez Use cgroupfs-mount as alternative package to cgroup-lite dependency
-#1419:@u2mejc Fix dokku ps <app> over ssh
-#1422:@josegonzalez Guard against missing VHOST files when listing domains
-#1428:@jimeh Use `$PLUGIN_PATH` instead of `$(dirname $0)/..`
-#1430:@lubert Update vagrant box name to `bento/ubuntu-14.04`
-#1439:@michaelshobbs Fix tar tests by sleeping for 5 seconds
-#1447:@alanjds Properly detect app name in the official cli client
-#1449:@josegonzalez Match herokuish deb with released version number
-#1457:@lukechilds Bashstyle fixes
-#1463:@josegonzalez Update `Xenify Distro` option for linode stackscript
-#1464:@josegonzalez Limit number of log lines when calling `dokku logs -t`
-#1466:@josegonzalez Follow bashstyle conventions where possible
-#1471:@michaelshobbs Make the default scaling logic clearer
-#1475:@josegonzalez Fix issue where restart on failure option overrode existing DOCKER_ARGS
### New features
-#1225:@michaelshobbs Add tags plugin to handle image tagging and deployment of tagged app images
-#1228:@michaelshobbs Use plugn instead of pluginhook to trigger plugin hooks
-#1402:@josegonzalez Consolidate configuration management into config plugin
-#1414:@michaelshobbs Add certs plugin for certificate management
-#1420:@josegonzalez Add `dokku enter` for connecting to an app container
-#1421:@basicer Add tar plugin to manage tar-based deployments
-#1423:@josegonzalez Set `DYNO_TYPE_NUMBER` environment variable for each container
-#1431:@josegonzalez Add helper function for inspecting the state of a container
-#1444:@josegonzalez Extract cleanup command into common function
-#1445:@josegonzalez Create CONTRIBUTING.md
-#1455:@michaelshobbs Continue and log an event if/when container retirement fails
-#1458:@michaelshobbs Set Herokuish `TRACE=true` when `DOKKU_TRACE` is set
-#1460:@michaelshobbs Bump herokuish version to 0.3.3
-#1465:@josegonzalez Set DYNO environment variable to heroku-compatible value
-#1467:@josegonzalez Upgrade dokku installation to use docker-engine
-#1468:@michaelshobbs Clean up semver logic and run install-dependencies after package installation
-#1469:@isundaylee Add nginx:access-logs and nginx:error-logs commands
-#1470:@assaf Add nginx configuration for running behind load balancer
-#1472:@michaelshobbs Use processes defined in `Procfile` when generating `DOKKU_SCALE` file
-#1473:@josegonzalez Handle crashing containers by using restart=on-failure policy
-#1476:@michaelshobbs Support static nginx port when deploying without an application VHOST
-#1476: nginx proxy without VHOST
-#1477:@arthurschreiber Support removing config variables that contain `\n`.
### Documentation
-#1407:@ertrzyiks Correct DOKKU_DOCKERFILE_PORT variable name in docs
-#1408:@josegonzalez Add links to official dokku datastorage plugins
-#1426:@henrik Update memcached link to maintained fork
-#1437:@Flink Update compatibility version for several plugins
-#1446:@johnfraney Correct nginx documentation
-#1478:@eljojo Fix naming of herokuish package in installation docs
## 0.3.26
This release has a few new features, the largest of which is switching from buildstep to herokuish for building containers. Going forward, this should help ensure that built containers are as close to heroku containers as possible, and also allow us to be on the cutting edge of heroku buildpack support. Props to @michaelshobbs for his work on herokuish.
### Bug Fixes
-#1401:@josegonzalez Install apt-transport-https before adding https-backed apt sources
### New Features
-#1128:@michaelshobbs Switch from buildstep to herokuish
-#1399:@basicer Make dokku play nice when there are multiple receive-app hooks
-#1413:@michaelshobbs support comments in DOKKU_SCALE and print contents on deploy
### Documentation
-#1400:@josegonzalez Fix HISTORY.md formatting
-#1410:@josegonzalez Clarify DOKKU_SCALE usage
-#1411:@josegonzalez Clarify `ps:scale` example
## 0.3.25
This release is a bugfix release fixing a broken 0.3.25 apt-get installation.
### Bug Fixes
-#1398@josegonzalez Revert "Remove `dokku plugins-install` from postinst hook
## 0.3.24
This release is a bugfix release covering dokku packaging.
@@ -9,13 +908,13 @@ This release is a bugfix release covering dokku packaging.
-#1397:@josegonzalez Use https docker apt repo
-#1394:@josegonzalez Remove `dokku plugins-install` from postinst hook
### Docs Changes
### Documentation
-#1395:@adrianmoya Adding fqdn requirement
## 0.3.23
This release is a bugfix release mostly covering installation and nginx issues. As well, we launched a nicer documentation site [here](http://progrium.viewdocs.io/dokku/). Thanks to all of our contributors for making this a great release!
This release is a bugfix release mostly covering installation and nginx issues. As well, we launched a nicer documentation site [here](http://dokku.viewdocs.io/dokku/). Thanks to all of our contributors for making this a great release!
### Bug Fixes
@@ -36,7 +935,7 @@ This release is a bugfix release mostly covering installation and nginx issues.
-#1359:@michaelshobbs allow DOKKU_WAIT_TO_RETIRE to be defined per app
-#1365:@michaelshobbs support dockerfile images that don't include bash
### Docs Changes
### Documentation
-#1305:@josegonzalez Updated documentation site
-#1321:@fwolfst Mention alternative to nginx.conf templates: include-dir.
@@ -75,7 +974,7 @@ This release is a general bugfix release, with improvements to handling of nginx
-#1291:@michaelshobbs Refactored interface for managing global/local app configuration
-#1299:@SonicHedgehog Set X-Forwarded-Proto header if TLS is enabled when running checks
### Docs Changes
### Documentation
-#1273:@alessio Add docs for the events plugin
-#1276:@josegonzalez Reorder and deprecate a few plugins
@@ -116,7 +1015,7 @@ This release pegs Dokku to Docker 1.6.2. Docker 1.7.0 introduced changes in `doc
-#1251:@josegonzalez Fallback to using /etc/init.d/nginx reload directly to restart nginx
-#1264:@josegonzalez Require lxc-docker-1.6.2
### Docs Changes
### Documentation
-#1252:@josegonzalez Fix ssh port for vagrant installation. Closes #1139. [ci skip]
-#1250:@josegonzalez SSL documentation is misleading
@@ -143,7 +1042,7 @@ This release pegs Dokku to Docker 1.6.2. Docker 1.7.0 introduced changes in `doc
-#1227:@Flink Use --no-cache when building Dockerfile
-#1246:@josegonzalez Ensure we call apt-get before installing packages
### Docs Changes
### Documentation
-#1168:@cjblomqvist [docs] Update git-rev plugin to point to maintained version
-#1180:@sherbondy [docs] Clarify usage around official dokku `docker-options` plugin
@@ -420,9 +1319,10 @@ This release pegs Dokku to Docker 1.6.2. Docker 1.7.0 introduced changes in `doc
- 969aed87: @jfrazelle Fix double brackets issue in nginx-vhosts install
-`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):
- Link to the exact repository being deployed (if possible/applicable):
- If a deploy is failing or behaving unexpectedly:
- Application name
- The type of application being deployed (node, php, python, ruby, etc.)
- 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 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 XXXXXXX):
[View the docs for upgrading](http://progrium.viewdocs.io/dokku/upgrading) from an older version of Dokku.
[View the docs for upgrading](http://dokku.viewdocs.io/dokku/getting-started/upgrading/) from an older version of Dokku.
## Documentation
Full documentation - including advanced installation docs - are available online at [docs](http://progrium.viewdocs.io/dokku/)
Full documentation - including advanced installation docs - are available online at [docs](http://dokku.viewdocs.io/dokku/)
## Support
You can use [Github Issues](https://github.com/progrium/dokku/issues), check [Troubleshooting](http://progrium.viewdocs.io/dokku/troubleshooting) in the documentation, or join us on [freenode in #dokku](https://webchat.freenode.net/?channels=%23dokku)
You can use [Github Issues](https://github.com/dokku/dokku/issues), check [Troubleshooting](http://dokku.viewdocs.io/dokku/getting-started/troubleshooting/) in the documentation, or join us on [freenode in #dokku](https://webchat.freenode.net/?channels=%23dokku)
## Contribution
After checking [Github Issues](https://github.com/progrium/dokku/issues), the [Troubleshooting Guide](http://progrium.viewdocs.io/dokku/troubleshooting) or having a chat with us on [freenode in #dokku](https://webchat.freenode.net/?channels=%23dokku), feel free to fork and create a Pull Request.
After checking [Github Issues](https://github.com/dokku/dokku/issues), the [Troubleshooting Guide](http://dokku.viewdocs.io/dokku/getting-started/troubleshooting/) or having a chat with us on [freenode in #dokku](https://webchat.freenode.net/?channels=%23dokku), feel free to fork and create a Pull Request.
While we may not merge your PR as is, they serve to start conversations and improve the general dokku experience for all users.
## Sponsors
Dokku is currently sponsored by the enterprise grade, multi-host PaaS project [Deis](http://deis.io/).
See our list of past sponsors in the [SPONSORS](https://github.com/dokku/dokku/blob/master/SPONSORS.md) file.
Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/dokku#sponsor)]
<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>
<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>
# <UDF name="hostname" default="" label="Hostname for dokku instance" example="example.com">
# <UDF name="ssh_key" default="" label="Public SSH Key for root user" example="Sets the root user's public ssh key, which is also automatically imported into the dokku installer">
# <UDF name="notify_email" default="" Label="Send Finish Notification To" example="Email address to send notification to when finished." />
function logit {
# Simple logging function that prepends an easy-to-find marker '=> ' and a timestamp to a message
TIMESTAMP=$(date -u +'%m/%d %H:%M:%S')
MSG="=> ${TIMESTAMP}$1"
echo${MSG}
}
function set_ssh_key {
if[ -n "${SSH_KEY}"];then
logit "Setting root ssh key"
mkdir -p /root/.ssh
chmod 700 /root/.ssh
echo"$SSH_KEY" > /root/.ssh/authorized_keys
chmod 600 /root/.ssh/authorized_keys
chown -R root:root /root/.ssh
fi
}
function set_passwordless_ssh {
logit "Turn off password authentication and root login for SSH"
#/usr/sbin/postconf -e "local_transport = error:local delivery is disabled"
touch /tmp/restart-postfix
}
function notify_install_via_email {
if[ -n "${NOTIFY_EMAIL}"];then
logit "Sending notification email to ${NOTIFY_EMAIL}"
/usr/sbin/sendmail "${NOTIFY_EMAIL}" <<EOD
To: ${NOTIFY_EMAIL}
Subject: Dokku installation is complete
From: Dokku StackScript <no-reply@${HOSTNAME}>
Your Dokku installation is complete and now ready to be configured: http://$(system_primary_ip) . Please visit this url to complete the setup of your Dokku instance.
Enjoy using Dokku!
EOD
fi
}
function notify_restart_via_email {
if[ -n "${NOTIFY_EMAIL}"];then
logit "Sending notification email to ${NOTIFY_EMAIL} of required restart"
Then click "Edit" next to the selected configuration profile and make the following changes:
- Change the "Kernel" option to the current "pv-grub" release
- Set the "Xenify Distro" option to "no"
Then save your changes. Next, reboot the instance from the Linode Dashboard. You'll receive an email once the instance is available to continue the dokku installation.
> The backup plugin was deprecated in 0.4.x, below are backup recommendations for 0.5.x and later.
## Backup and Migration Tutorial
Because Dokku is git based, rebuilding a deployed app is as easy as pushing from git. You can push to a new server by updating the dokku remote in you local app's repo.
```shell
git remote rm dokku
git remote add dokku dokku@[dokku.me:dokku.me]
git push dokku [master]
```
## Databases
Some plugins, like the official [dokku-postgres](https://github.com/dokku/dokku-postgres) plugin, have built-in commands that allow non-volatile data be exported and imported.
For [dokku-postgres](https://github.com/dokku/dokku-postgres), use:
```shell
dokku postgres:export [db_name] > [db_name].dump
dokku postgres:import [db_name] < [db_name].dump
```
## Volumes and Static Assets
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.
## Disaster Recovery
The best plan for disaster recovery is to always keep multiple (remote) copies of your local repo, static assets and periodic database dumps. In case of an emergency when your git repo and backups are completely lost, you can recover the last pushed copy from your remote dokku server (assuming you still have the ssh key).
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 initialised
* Running database migrations
* Any commands required to set up the server (e.g. something like a Django `collectstatic`)
## `app.json` and `scripts.dokku`
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`.
>NOTE: postdeploy changes are *NOT* committed to the app image.
### Example app.json
```json
{
"name": "barebones nodejs",
"description": "A barebones Node.js app using Express 4.",
dokku docker-options:add myapp run "-v /home/dokku/logs/myapp:/app/logs"
```
> Note: When [mounting a host directory](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems) in a Dokku app you should first create that directory as user `dokku` and then mount the directory under `/app` in the container using `docker-options` as above. Otherwise the app will lack write permission in the directory.
### Output Docker options
```shell
dokku docker-options myapp
```
```
Deploy options:
-v /home/dokku/logs/myapp:/app/logs
Run options:
-v /home/dokku/logs/myapp:/app/logs
```
### Remove a Docker option
```shell
dokku docker-options:remove myapp run "-v /home/dokku/logs/myapp:/app/logs"
```
## Advanced usage
In your applications folder `/home/dokku/app_name` create a file called `DOCKER_OPTIONS_RUN` (or `DOCKER_OPTIONS_BUILD` or `DOCKER_OPTIONS_DEPLOY`).
Inside this file list one Docker option per line. For example:
```shell
--link container_name:alias
-v /host/path:/container/path
-v /another/container/path
```
The above example will result in the following options being passed to Docker during `dokku run`:
Docker provides an _events_ command to show system's real time events. Likewise, Dokku can record events as syslog entries and also provides a plugin to display the last ones.
```
events [-t] Show the last events (-t follows)
events:list List logged events
events:on Enable events logger
events:off Disable events logger
events [-t] # Show the last events (-t follows)
events:list # List logged events
events:on # Enable events logger
events:off # Disable events logger
```
## Usage
Enable the plugin:
```shell
dokku events:on
```
```
$ dokku events:on
Enabling dokku events logger
```
Dokku will then write log entries to ``/var/log/syslog`` as well as a Dokku-specific logs sub-directory ``/var/log/dokku/events.log``, which can be easily displayed with the command `dokku events`:
Dokku will then write log entries to `/var/log/syslog` as well as a Dokku-specific logs sub-directory `/var/log/dokku/events.log`, which can be easily displayed with the command `dokku events`:
The preferred method to mount external containers to a dokku managed container, is to use the dokku storage plugin.
```
storage:list <app> # List bind mounts for app's container(s) (host:container)
storage:mount <app> <host-dir:container-dir> # Create a new bind mount
storage:unmount <app> <host-dir:container-dir> # Remove an existing bind mount
```
## Ideology and Background
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.
## Usage
This example demonstrates how to mount the recommended directory to `/storage` inside the container:
Dokku will then mount the shared contents of `/var/lib/dokku/data/storage` to `/storage` inside the container.
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.
```shell
# creating storage for the app 'ruby-rails-sample'
You can mount one or more directories as desired by following the above pattern.
## Use Cases
### Persistent storage
Dokku is powered by Docker containers, which recommends in their [best practices](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/#containers-should-be-ephemeral) that containers be treated as ephemeral. In order to manage persistent storage for web applications, like user uploads or large binary assets like images, a directory outside the container should be mounted.
### Shared storage between containers
When scaling your app, you may require a common location to access shared assets between containers, a storage mount can be used in this situation.
### Shared storage across environments
Your app may be used in a cluster that requires containers or resources not running on the same host access your data. Mounting a shared file service (like S3FS or EFS) inside your container will give you great flexibility.
### Backing up
Your app may have services that are running in memory and need to be backed up locally (like a key store). Mount a non ephemeral storage mount will allow backups that are not lost when the app is shut down.
### Build phase
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.
NOTE: **This can cause data loss** if you bind a mount under `/app` in buildpack apps as herokuish will attempt to remove the original app path during the build phase.
## Docker-Options Note
The storage plugins is compatible with storage mounts created with the docker-options. The storage plugin will only list mounts from the deploy phase.
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: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.
## 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
```
## 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.
repo:gc <app> # Runs 'git gc --agressive' against the application's repo
repo:purge-cache <app> # Deletes the contents of the build cache stored in the repository
```
The repository plugin is meant to allow users to perform management commands against a repository.
# Git Garbage Collection
This will run a git gc --agressive against the applications repo. This is performed on the Dokku host, and not within an application container.
```shell
dokku repo:gc node-js-app
```
```
Counting objects: 396, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (365/365), done.
Writing objects: 100% (396/396), done.
Total 396 (delta 79), reused 315 (delta 0)
```
## Clearing Application cache
Building containers with buildpacks currently results in a persistent `cache` directory between deploys. If you need to clear this cache directory for any reason, you may do so by running the following shell command:
- You can now **actually** disable zero-downtime deployments per-app and per-process-type
- Some config variables have been moved around
- `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
## 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.
- 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
- 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
## calling the dokku binary
- Plugins should *not* call the dokku binary directly. Clients using the `--app` argument are potentially broken, amongst others, when doing so. Instead, please source the `functions` file for a given plugin when attempting to call dokku internal functions. As a result, the following dokku commands are no longer publicly exposed:
Now you can deploy apps on your Dokku. Let's deploy the [Heroku Node.js sample app](https://github.com/heroku/node-js-sample). All you have to do is add a remote to name the app. It's created on-the-fly.
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```
Right now Buildstep supports buildpacks for Node.js, Ruby, Python, [and more](https://github.com/progrium/buildstep#supported-buildpacks). It's not hard to add more, [go add more](https://github.com/progrium/buildstep#adding-buildpacks)!
Please check the documentation for your particular build pack as you may need to include configuration files (such as a Procfile) in your project root.
## Deploying to server over SSH
Pushing to the dokku remote may prompt you to input a password for the dokku user. It's preferable, however, to use key-based authentication, and you can add your public key to the dokku user's authorized_keys file with:
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 `~dokku/.ssh` and potentially add github.com (or your VCS host key) into `~dokku/.ssh/known_hosts`. A decent test like this should help confirm you've done it correctly.
If buildpack detection isn't working well for you or you want to specify a custom buildpack for one repository you can create & commit a file in the root of your git repository named `.env` containing `export BUILDPACK_URL=<repository>` before pushing. This will tell buildstep to fetch the specified buildpack and use it instead of relying on the built-in buildpacks & their detection methods.
## Dockerfile deployment
Deployment of `Dockerfile` repos is supported as of v0.3.15. Simply place a Dockerfile in the root of your repo and push to dokku. If you are converting from a heroku/dokku buildpack deployment, ensure you are not setting `$BUILDPACK_URL` or including a `.buildpacks` file in the root of your repo.
By default, we will extract the first `EXPOSE` port and tell nginx to proxy your app to that port. Alternatively, you can set `$DOCKERFILE_PORT` in your app's dokku configuration.
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`:
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`.
## Default vhost
You might notice the default vhost for Nginx will be one of the apps. If an app doesn't exist, it will use this vhost and it may be confusing for it to go to another app. You can create a default vhost using a configuration under `sites-enabled`. You just have to change one thing in the main nginx.conf:
Swap both conf.d include line and the sites-enabled include line. From:
```
include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;
```
to
```
include /etc/nginx/sites-enabled/*;
include /etc/nginx/conf.d/*.conf;
```
Alternatively, you may push an app to your dokku host with a name like "00-default". As long as it lists first in `ls /home/dokku/*/nginx.conf | head`, it will be used as the default nginx vhost.
## Deploying to subdomains
The name of remote repository is used as the name of application to be deployed, as for example above:
$ git remote add dokku dokku@dokku.me:node-js-app
$ git push dokku master
Is deployed to,
remote: -----> Application deployed:
remote: http://node-js-app.dokku.me
You can also specify fully qualified names, say `app.dokku.me`, as
So, after deployment the application will be available at,
remote: -----> Application deployed:
remote: http://app.dokku.me
This is in particular useful, then you want to deploy to root domain, as
$ git remote add dokku dokku@dokku.me:dokku.me
$ git push dokku master
... deployment ...
remote: -----> Application deployed:
remote: http://dokku.me
# Zero downtime deploy
Following a deploy, dokku will now wait `DOKKU_DEFAULT_CHECKS_WAIT` seconds (default: `10`), and if the container is still running, then route traffic to the new container.
This can be problematic for applications whose boot up time can vary and can lead to `502 Bad Gateway` errors.
Dokku provides a way to run a set of more precise checks against the new container, and only switch traffic over if all checks complete successfully.
To specify checks, add a `CHECKS` file to the root of your project directory. This is a text file with one line per check. Empty lines and lines starting with `#` are ignored.
A check is a relative URL and may be followed by expected content from the page, for example:
```
/about Our Amazing Team
```
Dokku will wait `DOKKU_CHECKS_WAIT` seconds (default: `5`) before running the checks to give server time to start. For shorter/longer wait, change the `DOKKU_CHECKS_WAIT` environment variable. This can also be overridden in the CHECKS file by setting WAIT=nn.
Dokku will wait `DOKKU_WAIT_TO_RETIRE` seconds (default: `60`) before stopping the old container such that no existing connections to it are dropped.
Dokku will retry the checks DOKKU_CHECKS_ATTEMPTS times until the checks are successful or DOKKU_CHECKS_ATTEMPTS is exceeded. In the latter case, the deployment is considered failed. This can be overridden in the CHECKS file by setting ATTEMPTS=nn.
Checks can be skipped entirely by setting `DOKKU_SKIP_ALL_CHECKS` to `true` either globally or per application. You can choose to skip only default checks by setting `DOKKU_SKIP_DEFAULT_CHECKS` to `true` either globally or per application.
See [checks-examples.md](checks-examples.md) for examples and output.
# Removing a deployed app
SSH onto the server, then execute:
```shell
dokku apps:destroy myapp
```
# Dokku/Docker Container Management Compatibility
Dokku is, at it's 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/progrium/dokku/issues/1220), dokku executes a cleanup function prior to every deployment. This function removes all exited containers and all 'unattached' images.
The CHECKS file may contain empty lines, comments (lines starting with #),
settings (NAME=VALUE) and check instructions.
The format of a check instruction is a path, optionally followed by the
expected content. For example:
/ My Amazing App
/stylesheets/index.css .body
/scripts/index.js $(function()
/images/logo.png
To check an application that supports multiple hostnames, use relative URLs
that include the hostname, for example:
//admin.example.com Admin Dashboard
//static.example.com/logo.png
You can also specify the protocol to explicitly check HTTPS requests.
The default behavior is to wait for 5 seconds before running the first check,
and timeout each check to 30 seconds.
By default, checks will be attempted 5 times. (Retried 4 times)
You can change these by setting WAIT, TIMEOUT and ATTEMPTS to different values, for
example:
WAIT=30 # Wait 1/2 minute
TIMEOUT=60 # Timeout after a minute
ATTEMPTS=10 # attempt checks 10 times
# Example: Successful Rails Deployment
In this example, a rails applicaiton 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.
ATTEMPTS is set to 6, but the third attempt succeeds.
## CHECKS file
````
WAIT=5
ATTEMPTS=6
/check.txt simple_check
````
> check.txt is a text file returning the string 'simple_check'
## Deploy Output
> Note: The output has been trimmed for brevity
````
git push dokku master
-----> Cleaning up...
-----> Building myapp from buildstep...
-----> Adding BUILD_ENV to build environment...
-----> Ruby app detected
-----> Compiling Ruby/Rails
-----> Using Ruby version: ruby-2.0.0
.....
-----> Discovering process types
Procfile declares types -> web
-----> Releasing myapp...
-----> Deploying myapp...
-----> Running pre-flight checks
-----> Attempt 1/6 Waiting for 5 seconds ...
CHECKS expected result:
http://localhost/check.txt => "simple_check"
!
curl: (7) Failed to connect to 172.17.0.155 port 5000: Connection refused
! Check attempt 1/6 failed.
-----> Attempt 2/6 Waiting for 5 seconds ...
CHECKS expected result:
http://localhost/check.txt => "simple_check"
!
curl: (7) Failed to connect to 172.17.0.155 port 5000: Connection refused
! Check attempt 2/6 failed.
-----> Attempt 3/6 Waiting for 5 seconds ...
CHECKS expected result:
http://localhost/check.txt => "simple_check"
-----> All checks successful!
=====> myapp 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
=> Ctrl-C to shutdown server
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
-----> Running post-deploy
-----> Configuring myapp.dokku.example.com...
-----> Creating http nginx.conf
-----> Running nginx-pre-reload
Reloading nginx
-----> Shutting down old container in 60 seconds
=====> Application deployed:
http://myapp.dokku.example.com
````
# 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.
Once the attempts have been exceeded, the deployment fails and we see the container output, which shows the Postgres connection errors.
## CHECKS file
````
WAIT=5
ATTEMPTS=6
/
````
> The check to the root url '/' would normally access the database.
## Deploy Output
> Note: The output has been trimmed for brevity
````
git push dokku master
-----> Cleaning up...
-----> Building myapp from buildstep...
-----> Adding BUILD_ENV to build environment...
-----> Ruby app detected
-----> Compiling Ruby/Rails
-----> Using Ruby version: ruby-2.0.0
.....
Discovering process types
Procfile declares types -> web
Releasing myapp...
Deploying myapp...
Running pre-flight checks
-----> Attempt 1/6 Waiting for 5 seconds ...
CHECKS expected result:
http://localhost/ => ""
!
curl: (7) Failed to connect to 172.17.0.188 port 5000: Connection refused
! Check attempt 1/6 failed.
-----> Attempt 2/6 Waiting for 5 seconds ...
CHECKS expected result:
http://localhost/ => ""
!
curl: (7) Failed to connect to 172.17.0.188 port 5000: Connection refused
! Check attempt 2/6 failed.
-----> Attempt 3/6 Waiting for 5 seconds ...
CHECKS expected result:
http://localhost/ => ""
!
curl: (22) The requested URL returned error: 500 Internal Server Error
! Check attempt 3/6 failed.
-----> Attempt 4/6 Waiting for 5 seconds ...
CHECKS expected result:
http://localhost/ => ""
!
curl: (22) The requested URL returned error: 500 Internal Server Error
! Check attempt 4/6 failed.
-----> Attempt 5/6 Waiting for 5 seconds ...
CHECKS expected result:
http://localhost/ => ""
!
curl: (22) The requested URL returned error: 500 Internal Server Error
! Check attempt 5/6 failed.
-----> Attempt 6/6 Waiting for 5 seconds ...
CHECKS expected result:
http://localhost/ => ""
!
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:
=> 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
=> Ctrl-C to shutdown server
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
Started GET "/" for 172.17.42.1 at 2015-03-26 21:36:47 +0000
Is the server running on host "172.17.42.1" and accepting
TCP/IP connections on port 5431?
PG::ConnectionBad (could not connect to server: Connection refused
Is the server running on host "172.17.42.1" and accepting
# optional: make sure that the dokku_client.sh version matches your dokku version
cd ~/.dokku
git checkout <tag/branch>
# add the following to either your
# .bashrc, .bash_profile, or .profile file
@@ -33,6 +37,8 @@ alias dokku 'bash $HOME/.dokku/contrib/dokku_client.sh'
Configure the `DOKKU_HOST` environment variable or run `dokku` from a repository with a git remote named dokku pointed at your dokku host in order to use the script as normal.
You can also configure a `DOKKU_PORT` environment variable if you are running ssh on a non-standard port. This defaults to `22`.
## (nodejs) dokku-toolbelt
Dokku-toolbelt is a node-based cli wrapper that proxies requests to the dokku command running on remote hosts. You can install it via the following shell command (assuming you have nodejs and npm installed):
Dokku itself is built out of plugins and uses [pluginhook](https://github.com/progrium/pluginhook) for its plugin system. In essence a plugin is a collection of scripts that will be run based on naming convention.
Dokku itself is built out of plugins and uses [plugn](https://github.com/dokku/plugn) for its plugin system. In essence a plugin is a collection of scripts that will be run based on naming convention.
Let's take a quick look at the current dokku nginx plugin that's shipped with dokku by default.
nginx-vhosts/
├── plugin.toml # plugin metadata
├── commands # contains additional commands
├── install # runs on dokku installation
└── post-deploy # runs after an app is deployed
@@ -12,49 +13,96 @@ Let's take a quick look at the current dokku nginx plugin that's shipped with do
## Installing a plugin
```shell
# This command requires `root` permissions as the `install` and `install-dependencies`
# plugin triggers may utilize commands such as `apt-get`. For non-core plugins, please
# inspect those plugins before running the following command as `root` user.
# previous versions (0.3.x and below) of dokku require a manual process to install plugins
cd /var/lib/dokku/plugins
git clone <git url>
dokku plugins-install
```
## Creating your own plugin
[See the full documentation](http://progrium.viewdocs.io/dokku/development/plugin-creation).
[See the full documentation](/dokku/development/plugin-creation/).
## Official Plugins (Beta)
The following plugins are available and provided by dokku maintainers. Where noted, these plugins should be considered beta software and may not have been used as thoroughly as community plugins. Please file issues against their respective issue trackers.
| [PostgreSQL](https://github.com/Kloadut/dokku-pg-plugin) | [Kloadut][] | Compatible with 0.2.0 |
| [PostgreSQL](https://github.com/jlachowski/dokku-pg-plugin) | [jlachowski][] | IP & PORT available directly in linked app container env variables (requires link plugin)|
| [PostgreSQL (single container)](https://github.com/jeffutter/dokku-postgresql-plugin) | [jeffutter][] | This plugin creates a single postgresql container that all your apps can use. Thus only one instance of postgresql running (good for servers without a ton of memory). |
| [PostgreSQL (single container)](https://github.com/Flink/dokku-psql-single-container) | [Flink][] | Single Postgresql container with official Postgresql docker image. Compatible with 0.3.16 |
| [Memcached](https://github.com/jlachowski/dokku-memcached-plugin) | [jlachowski][] | IP & PORT available directly in linked app container env variables (requires link plugin)|
| [Redis](https://github.com/sekjun9878/dokku-redis-plugin) | [sekjun9878][] | A better Redis plugin with automatic instance creation and Dokku Link support
| [RabbitMQ](https://github.com/jlachowski/dokku-rabbitmq-plugin) | [jlachowski][] | IP & PORT available directly in linked app container env variables (requires link plugin)|
| [RabbitMQ (single container)](https://github.com/jlachowski/dokku-rabbitmq-single-plugin) | [jlachowski][] | IP & PORT available directly in linked app container env variables (requires link plugin)|
<sup>1</sup> On Heroku similar functionality is offered by the [heroku-labs pipeline feature](https://devcenter.heroku.com/articles/labs-pipelines), which allows you to promote builds across multiple environments (staging -> production)
<sup>2</sup> Adds the possibility to add SSH deployment keys to receive private hosted packages
<sup>2</sup> Extends app.json support to include creating volumes and creating / linking databases on push
<sup>3</sup> Adds the ability to add custom hosts to the containers known_hosts file to be able to ssh them easily (useful with deployment keys)
<sup>3</sup> Adds the possibility to add SSH deployment keys to receive private hosted packages
<sup>4</sup> Adds the ability to add custom hosts to the containers known_hosts file to be able to ssh them easily (useful with deployment keys)
<sup>1</sup> Forked from [jezdez/dokku-elasticsearch-plugin](https://github.com/jezdez/dokku-elasticsearch-plugin): uses Elasticsearch 1.2 (instead of 0.90), doesn't depend on dokku-link, runs as elasticsearch user instead of root, and turns off multicast autodiscovery for use in a VPS environment.
@@ -212,7 +263,10 @@ The following plugins have been removed as their functionality is now in Dokku C
| [PostgreSQL (single container)](https://github.com/jeffutter/dokku-postgresql-plugin) | [jeffutter][] | This plugin creates a single postgresql container that all your apps can use. Thus only one instance of postgresql running (good for servers without a ton of memory). |
| [RiakCS (single container)](https://github.com/jeffutter/dokku-riakcs-plugin) | [jeffutter][] | Incompatible with 0.2.0 (checked at [dccee02][]) |
Typically an application will require some configuration to run properly. Dokku supports application configuration via environment variables. Environment variables may contain private data, such as passwords or API keys, so it is not recommended to store them in your application's repository.
The `config` plugin provides the following commands to manage your variables:
```
config <app> - display the config vars for an app
config:get <app> KEY - display a config value for an app
config:set <app> KEY1=VALUE1 [KEY2=VALUE2 ...] - set one or more config vars
config:unset <app> KEY1 [KEY2 ...] - unset one or more config vars
```
The variables are available both at run time and during the application build/compilation step. You no longer need a `user-env` plugin as Dokku handles this functionality in a way equivalent to how Heroku handles it.
> Note: Global `BUILD_ENV` files are currently migrated into a global `ENV` file and sourced before app-specific variables. This means that app-specific variables will take precedence over global variables. Configuring your global `ENV` file is manual, and should be considered potentially dangerous as configuration applies to all applications.
@@ -14,39 +14,36 @@ Because there are so many different DNS server packages out there as well as a t
* We assume you have a passing familiarity with DNS. If not, you can read an [in-depth article](http://www.diaryofaninja.com/blog/2012/03/03/devops-dns-for-developers-ndash-now-therersquos-no-excuse-not-to-know) on DNS. But basically you need to know that DNS changes names (like example.tld) into addresses (like 127.0.0.1)
* We assume you already have a domain name registered and pointed to your favorite Managed DNS Provider or have your own BIND DNS server running.
* You have a server on the internet and are about to follow the instructions in the [README](https://github.com/progrium/dokku/blob/master/README.md) to get dokku installed. Don't do the install just yet though.
* You have a server on the internet and are about to follow the instructions in the [README](https://github.com/dokku/dokku/blob/master/README.md) to get dokku installed. Don't do the install just yet though.
## Caching
Please remember that DNS relies heavily on _caching_. Changes you make to DNS could take anywhere from a few seconds to a few *days* to propagate. If you tried surfing to example.tld, then changed the IP address in DNS, it could be a while before your computer picks up on the changes.
## HELP!
Don't be afraid to ask if you need help. Create a [new issue](https://github.com/progrium/dokku/issues) and someone will be glad to assist you.
Don't be afraid to ask if you need help. Create a [new issue](https://github.com/dokku/dokku/issues) and someone will be glad to assist you.
# Getting started
## Getting started
For the examples, we will use the domain name 'example.tld' and the IP address '127.0.0.1'.
For the examples, we will use the domain name `example.tld` and the IP address `127.0.0.1`.
Dokku uses a DNS to differentiate between apps on your dokku-powered server. If you are using the domain 'example.tld', and you have two apps 'myapp1' and 'myapp2', dokku will make them available at 'myapp1.example.tld' and 'myapp2.example.tld'.
Dokku uses DNS to differentiate between apps on your dokku-powered server. If you are using the domain `example.tld`, and you have two apps `myapp1` and `myapp2`, dokku will make them available at `myapp1.example.tld` and `myapp2.example.tld`.
To get started, you need to know the IP address of your dokku server. Connect in to it and run 'ifconfig' or 'ip addr' to see the IP address.
To get started, you need to know the IP address of your dokku server. Connect to it and run `ifconfig` or `ip addr` to see the IP address.
# Caching
Now you have to make a decision about your domain. Do you want everything and anything at `example.tld` to go to your dokku server, or would you rather use a 'sub domain' for your dokku server?
Please remember that DNS relies heavily on _caching_. Changes you make to DNS could take anywhere from a few seconds to a few *days* to 'propagate'. If you tried surfing to example.tld, then changed the IP address in DNS, it could be a while before your computer picks up on the changes.
In other words, do you want your applications on your dokku server accessible via `myapp.example.tld` or via `myapp.myserver.example.tld`?
## The two methods
#### Using a sub-domain (myapp.myserver.example.tld)
Now you have to make a decision about your domain. Do you want everything and anything at example.tld to go to your dokku server, or would you rather use a 'sub domain' for your dokku server?
Using a sub-domain is easy. When you set up your server, you probably gave it a name like `myserver.example.tld`.
In other words, do you want your applications on your dokku server accessible via myapp.example.tld or via myapp.myserver.example.tld?
Go in to your Managed DNS provider and create an `A` record named `myserver` and put in the IP address you got from your server a few moments ago.
### Using a sub-domain (myapp.myserver.example.tld)
Using a sub-domain is easy. When you set up your server, you probably gave it a name like myserver.example.tld.
Go in to your Managed DNS provider and create an 'A' record named 'myserver' and put in the IP address you got from your server a few moments ago.
Hopefully your managed DNS provider also supports wildcards. Create a second 'A' record named '*.myserver' along with the IP address you got from your server a few moments ago.
Hopefully your managed DNS provider also supports wildcards. Create a second `A` record named `*.myserver` along with the IP address you got from your server a few moments ago.
If you are using BIND, your zone file will look similar to this:
@@ -55,34 +52,31 @@ $ORIGIN example.tld
$TTL 5m
myserver IN A 127.0.0.1
*.myserver IN A 127.0.0.1
*.myserver IN A 127.0.0.1
```
You can verify your changes in Linux by trying one or more of the following commands:
* host myserver.example.tld
* dig -t A myserver.example.tld
* nslookup myserver.example.tld
* `host myserver.example.tld`
* `dig -t A myserver.example.tld`
* `nslookup myserver.example.tld`
Now is a good time to remind you that the answers you get MAY BE CACHED.
If everything is working correctly, you should also be able to query for any other name 'under' myserver.example.tld and get back the IP address of your server. Try:
If everything is working correctly, you should also be able to query for any other name under `myserver.example.tld` and get back the IP address of your server. Try:
* host test.myserver.example.tld
* `host test.myserver.example.tld`
* `host xyzzy.myserver.example.tld`
* host xyzzy.myserver.example.tld
If they all return your IP address, you have set DNS up properly for dokku. You should also be able to `ssh root@myserver.example.tld` and access your server.
If they all return your IP address, you have set DNS up properly for dokku. You should also be able to 'ssh root@myserver.example.tld' and access your server.
Proceed with the setup instructions in the [installation documentation](/dokku/getting-started/installation/)
Proceed with the setup instructions in the [README](https://github.com/progrium/dokku/blob/master/README.md)
### Using the root of your domain (myapp.example.tld)
#### Using the root of your domain (myapp.example.tld)
This section is a work in progress. It is incomplete.
Using the 'root' of your domain is nearly identical to the previous example.
* hostname is under example.tld, still needs A record
* Need to modify /home/dokku/HOSTNAME and /home/dokku/VHOST
* hostname is under `example.tld`, still needs `A` record
* Need to modify `/home/dokku/HOSTNAME` and `/home/dokku/VHOST`
domains:remove <app> DOMAIN # Remove a domain from app
domains:set-global <domain> # Set global domain name
```
## Customizing hostnames
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:set-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`.
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:
```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` 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
```
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.)
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.
```shell
# where `myapp` is the name of your app
# add a domain to an app
dokku domains:add myapp example.com
# list custom domains for app
dokku domains myapp
# clear all custom domains for app
dokku domains:clear myapp
# remove a custom domain from app
dokku domains:remove myapp example.com
```
## Default site
By default, dokku will route any received request with an unknown HOST header value to the lexicographically first site in the nginx config stack. If this is not the desired behavior, you may want to add the following configuration to the global nginx configuration. This will catch all unknown HOST header values and return a `410 Gone` response. You can replace the `return 410;` with `return 444;` which will cause nginx to not respond to requests that do not match known domains (connection refused).
```nginx
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name _;
return 410;
log_not_found off;
}
```
You may also wish to use a separate vhost in your `/etc/nginx/sites-enabled` directory. To do so, create the vhost in that directory as `/etc/nginx/sites-enabled/00-default.conf`. You will also need to change two lines in the main `nginx.conf`:
```nginx
# Swap both conf.d include line and the sites-enabled include line. From:
include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;
# to the following
include /etc/nginx/sites-enabled/*;
include /etc/nginx/conf.d/*.conf;
```
Alternatively, you may push an app to your dokku host with a name like "00-default". As long as it lists first in `ls /home/dokku/*/nginx.conf | head`, it will be used as the default nginx vhost.
Typically an application will require some configuration to run properly. Dokku supports application configuration via environment variables. Environment variables may contain private data, such as passwords or API keys, so it is not recommended to store them in your application's repository.
The `config` plugin provides the following commands to manage your variables:
```
config (<app>|--global) Display all global or app-specific config vars
config:get (<app>|--global) KEY Display a global or app-specific config value
config:set (<app>|--global) KEY1=VALUE1 [KEY2=VALUE2 ...] Set one or more config vars
config:unset (<app>|--global) KEY1 [KEY2 ...] Unset one or more config vars
```
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).
For buildpack deploys, Dokku will create a `/app/.env` file that can be used for legacy buildpacks. Note that this is *not* updated when `config:set` or `config:unset` is called, and is only written during a `deploy` or `ps:rebuild`. Developers are encouraged to instead read from the application environment directly, as the proper values will be available then.
> Note: Global `ENV` files are sourced before app-specific `ENV` files. This means that app-specific variables will take precedence over global variables. Configuring your global `ENV` file is manual, and should be considered potentially dangerous as configuration applies to all applications.
You can set multiple environment variables at once:
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:
Dokku uses nginx as its server for routing requests to specific applications. By default, access and error logs are written for each app to `/var/log/nginx/${APP}-access.log` and `/var/log/nginx/${APP}-error.log` respectively
```
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)
```
## Customizing the nginx configuration
> New as of 0.5.0
Dokku uses a templating library by the name of [sigil](https://github.com/gliderlabs/sigil) to generate nginx configuration for each app. If you'd like to provide a custom template for your application, there are a couple options:
- Copy the following example template to a file named `nginx.conf.sigil` and either:
- 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`.
include {{ .DOKKU_ROOT }}/{{ .APP }}/nginx.conf.d/*.conf;
}
upstream {{ .APP }} {
{{ range .DOKKU_APP_LISTENERS | split " " }}
server {{ . }};
{{ end }}
}
```
### Available template variables
```
{{ .APP }} Application name
{{ .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)
{{ .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)
{{ .RAW_TCP_PORTS }} List of exposed tcp ports as defined by Dockerfile `EXPOSE` directive (**Dockerfile apps only**)
{{ .SSL_INUSE }} Boolean set when an app is SSL-enabled
{{ .SSL_SERVER_NAME }} List of SSL VHOSTS
```
> 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`
```go
server {
listen [::]:80;
listen 80;
server_name {{ .NOSSL_SERVER_NAME }};
access_log /var/log/nginx/{{ .APP }}-access.log;
error_log /var/log/nginx/{{ .APP }}-error.log;
return 301 https://$host:443$request_uri;
}
server {
listen [::]:443 ssl spdy;
listen 443 ssl spdy;
{{ if .SSL_SERVER_NAME }}server_name {{ .SSL_SERVER_NAME }}; {{ end }}
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.
## Domains plugin
See the [domain configuration documentation](/dokku/configuration/domains/).
## Customizing hostnames
See the [customizing hostnames documentation](/dokku/configuration/domains/#customizing-hostnames).
## Disabling VHOSTS
See the [disabling vhosts documentation](/dokku/configuration/domains/#disabling-vhosts).
## Default site
See the [default site documentation](/dokku/configuration/domains/#default-site).
## Running behind a load balancer
See the [load balancer documentation](/dokku/configuration/ssl/#running-behind-a-load-balancer).
## HSTS Header
See the [HSTS documentation](/dokku/configuration/ssl/#hsts-header).
## SSL Configuration
See the [ssl documentation](/dokku/configuration/ssl/).
## Disabling Nginx
See the [proxy documentation](/dokku/advanced-usage/proxy-management/).
## Managing Proxy Port mappings
See the [proxy documentation](/dokku/advanced-usage/proxy-management/#proxy-port-mapping).
Dokku supports SSL/TLS certificate inspection and CSR/Self-signed certificate generation via the `certs` plugin. Note that whenever SSL/TLS support is enabled SPDY is also enabled.
```
certs:add <app> CRT KEY # Add an ssl endpoint to an app. Can also import from a tarball on stdin.
certs:generate <app> DOMAIN # Generate a key and certificate signing request (and self-signed certificate)
certs:info <app> # Show certificate information for an ssl endpoint.
certs:remove <app> # Remove an SSL Endpoint from an app.
certs:update <app> CRT KEY # Update an SSL Endpoint on an app. Can also import from a tarball on stdin
```
```shell
# for 0.3.x
dokku nginx:import-ssl <app> < certs.tar
```
## Per-application certificate management
Dokku provides built-in support for managing SSL certificates on a per-application basis. SSL is managed via nginx outside of application containers, and as such can be updated on-the-fly without rebuilding containers. At this time, applications only support a single SSL certificate at a time. To support multiple domains for a single application, wildcard certificate usage is encouraged.
### Certificate setting
The `certs:add` command can be used to push a `tar` containing a certificate `.crt` and `.key` file to a single application. The command should correctly handle cases where the `.crt` and `.key` are not named properly or are nested in a subdirectory of said `tar` file. You can import it as follows:
```shell
tar cvf cert-key.tar server.crt server.key
# replace APP with the name of your application
dokku certs:add <app> < cert-key.tar
```
> Note: If your `.crt` file came alongside a `.ca-bundle`, you'll want to concatenate those into a single `.crt` file before adding it to the `.tar`.
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/).
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/).
### Certificate generation
> Note: Using this method will create a self-signed certificate, which is only recommended for development or staging use, not production environments.
The `certs:generate` command will walk you through the correct `openssl` commands to create a key, csr and a self-signed cert for a given app/domain. We automatically put the self-signed cert in place as well as add the specified domain to the application configuration.
If you decide to obtain a CA signed certficate, you can import that certificate using the aformentioned `dokku certs:add` command.
### Certificate information
The `certs:info` command will simply inspect the install SSL cert and print out details. NOTE: The server-wide certificate will be inspect if installed and no app-specific certificate exists.
```shell
dokku certs:info node-js-app
```
```
-----> Fetching SSL Endpoint info for node-js-app...
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.
## HSTS Header
The [HSTS header](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) is an HTTP header that can inform browsers that all requests to a given site should be made via HTTPS. dokku does not, by default, enable this header. It is thus left up to you, the user, to enable it for your site.
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.
## Running behind a load balancer
Your application has access to the HTTP headers `X-Forwarded-Proto`, `X-Forwarded-For` and `X-Forwarded-Port`. 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)
include {{ .DOKKU_ROOT }}/{{ .APP }}/nginx.conf.d/*.conf;
}
upstream {{ .APP }} {
{{ range .DOKKU_APP_LISTENERS | split " " }}
server {{ . }};
{{ end }}
}
```
Only use this option if:
1. All requests are terminated at the load balancer, and forwarded to Nginx
2. The load balancer is configured to send the `X-Forwarded-` headers (this may be off by default)
If it's possible to make HTTP/S requests directly to Nginx, bypassing the load balancer, or if the load balancer is not configured to set these headers, then it becomes possible for a client to set these headers to arbitrary values.
This could result in security issue, for example, if your application looks at the value of the `X-Forwarded-Proto` to determine if the request was made over HTTPS.
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.
Create the application on the Dokku host. You will need to ssh onto the host to run this command.
```shell
# on your dokku host
dokku apps:create ruby-rails-sample
```
### 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:
```shell
# on your 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.
### 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.
Fetching gem metadata from https://rubygems.org/...........
Fetching version metadata from https://rubygems.org/...
Fetching dependency metadata from https://rubygems.org/..
Using rake 10.4.2
...
=====> Application deployed:
http://ruby-rails-sample.dokku.me
```
When the deploy finishes, the application's URL will be shown as seen 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/).
### 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```
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:
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 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.
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.
## Adding deploy users
See the [user management documentation](/dokku/deployment/user-management).
## Default vhost
See the [nginx documentation](/dokku/configuration/nginx/#default-site).
## Dockerfile deployment
See the [dockerfile documentation](/dokku/deployment/methods/dockerfiles/).
## Specifying a custom buildpack
See the [buildpack documentation](/dokku/deployment/methods/buildpacks/).
## Image tagging
See the [image tagging documentation](/dokku/deployment/methods/images/).
## Removing a deployed app
See the [application management documentation](/dokku/deployment/application-management/#removing-a-deployed-app).
### Renaming a deployed app
See the [application management documentation](/dokku/deployment/application-management/#renaming-a-deployed-app).
## Zero downtime deploy
See the [zero-downtime deploy documentation](/dokku/deployment/zero-downtime-deploys/).
You can easily list all available applications using the `apps` command:
```shell
dokku apps
```
```
=====> My Apps
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.
```shell
dokku --quiet apps
```
```
node-js-app
python-app
```
## 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:
```shell
dokku apps:create node-js-app
```
```
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:
- configure domain names and ssl certificates
- create and link datastores
- set environment variables
## Removing a deployed app
In some cases, you may need to destroy an application, whether it is because the application is temporary or because it was misconfigured. In these cases, you can use the `apps:destroy` command. Performing any destructive actions in Dokku requires confirmation, and this command will ask for the name of the application being deleted before doing so.
```shell
dokku apps:destroy node-js-app
```
```
! WARNING: Potentially Destructive Action
! This command will destroy node-js-app (including all add-ons).
! To proceed, type "node-js-app"
> node-js-app
Destroying node-js-app (including all add-ons)
```
This will prompt you to verify the application's name before destroying it. You may also use the `--force` flag to circumvent this verification process:
```shell
dokku --force apps:destroy node-js-app
```
```
Destroying node-js-app (including all add-ons)
```
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
> New as of 0.4.7
You can rename a deployed app using the `apps:rename` command. Note that the application *must* have been deployed at least once, or the rename will not complete successfully:
```shell
dokku apps:rename node-js-app io-js-app
```
```
Destroying node-js-app (including all add-ons)
-----> Cleaning up...
-----> Building io-js-app from herokuish...
-----> Adding BUILD_ENV to build environment...
-----> Node.js app detected
-----> Creating runtime environment
...
=====> Application deployed:
http://io-js-app.ci.dokku.me
Renaming node-js-app to io-js-app... done
```
This will copy all of your app's contents into a new app directory with the name of your choice, delete your old app, then rebuild the new version of the app and deploy it. All of your config variables, including database urls, will be preserved.
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:
- 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.
- Create a `.buildpacks` file in the root of your repository.
## Specifying a custom buildpack
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.
To use a specific buildpack, you can run the following dokku command:
```shell
# replace APPwith the name of your application
# replace REPOSITORY_URL with your buildpack's url
dokku config:set APP BUILDPACK_URL=REPOSITORY_URL
# example: using a specific ruby buildpack version
Please check the documentation for your particular buildpack as you may need to include configuration files (such as a Procfile) in your project root.
## 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:
> 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:
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.
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 file must be placed in the root directory of your application. It will not function if placed in a subdirectory.
If the file exists, it should not be empty, as doing so may result in a failed deploy.
The syntax for declaring a `Procfile` is as follows. Note that the format is one process type per line, with no duplicate process types.
```
<process type>: <command>
```
If, for example, you have multiple queue workers and wish to scale them separately, the following would be a valid way to work around the requirement of not duplicating process types:
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.
## 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.
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:
```shell
dokku config:set --global CURL_TIMEOUT=600
dokku config:set --global CURL_CONNECT_TIMEOUT=30
```
## Clearing buildpack cache
See the [repository management documentation](/dokku/advanced-usage/repository-management/#clearing-app-cache).
Loaded 100 of 415 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.