github/dokku
0
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Fix documentation directory structure

Browse Source 
Also ensure there is a trailing slash on all urls
This commit is contained in:
Jose Diaz-Gonzalez
2016-07-04 22:59:50 -04:00
parent 8c7a031061
commit edc0961e19
35 changed files with 126 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

213
docs/deployment/application-deployment.md Normal file
View File

@@ -0,0 +1,213 @@
# Deploying to Dokku
## Deploy tutorial
Once Dokku has been configured with at least one user, applications can be deployed via a `git push` command. To quickly see Dokku deployment in action, you can use the Heroku Ruby on Rails example app.
```shell
# from your local machine
git clone git@github.com:heroku/ruby-rails-sample.git
```
### Create the 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
sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git
# create a postgres service with the name rails-database
dokku postgres:create rails-database
```
> Each services may take a few moments to create.
### Linking backing services to applications
Once the service creation is complete, set the `POSTGRES_URL` environment variable by linking the service.
```shell
# on your dokku host
# each official datastore offers a `link` method to link a service to any application
dokku postgres:link rails-database ruby-rails-sample
```
> 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.
```shell
# from your local machine
git remote add dokku dokku@dokku.me:ruby-rails-sample
git push dokku master
```
```
Counting objects: 231, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (162/162), done.
Writing objects: 100% (231/231), 36.96 KiB | 0 bytes/s, done.
Total 231 (delta 93), reused 147 (delta 53)
-----> Cleaning up...
-----> Building ruby-rails-sample from herokuish...
-----> Adding BUILD_ENV to build environment...
-----> Ruby app detected
-----> Compiling Ruby/Rails
-----> Using Ruby version: ruby-2.2.1
-----> Installing dependencies using 1.9.7
Running: bundle install --without development:test --path vendor/bundle --binstubs vendor/bundle/bin -j4 --deployment
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/).
### Removing a deployed app
You can also remove an application from your Dokku installation. This 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).
```shell
# on your dokku host
# replace APP with the name of your application
dokku apps:destroy APP
```
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
# on your dokku host
# replace APP with the name of your application
dokku --force apps:destroy APP
```
### Renaming a deployed app
> New as of 0.4.7
You can rename a deployed app using the `apps:rename` CLI tool:
```shell
# on your dokku host
dokku apps:rename OLD_NAME NEW_NAME
```
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.
### 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:
``` shell
# on your dokku host
dokku config:set ruby-rails-sample DOKKU_SKIP_DEPLOY=true
```
### Deploying with private git submodules
Dokku uses git locally (i.e. not a docker image) to build its own copy of your app repo, including submodules. This is done as the `dokku` user. Therefore, in order to deploy private git submodules, you'll need to drop your deploy key in `/home/dokku/.ssh/` and potentially add github.com (or your VCS host key) into `/home/dokku/.ssh/known_hosts`. The following test should help confirm you've done it correctly.
```shell
# on your dokku host
su - dokku
ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts
ssh -T git@github.com
```
Note that if the buildpack or dockerfile build process require ssh key access for other reasons, the above may not always apply.
## Deploying to subdomains
The name of remote repository is used as the name of application to be deployed, as for example above:
```shell
git remote add dokku dokku@dokku.me:ruby-rails-sample
git push dokku master
```
```
remote: -----> Application deployed:
remote: http://ruby-rails-sample.dokku.me
```
You can also specify fully qualified names, say `app.dokku.me`, as
```shell
git remote add dokku dokku@dokku.me:app.dokku.me
git push dokku master
```
```
remote: -----> Application deployed:
remote: http://app.dokku.me
```
This is in particular useful, then you want to deploy to root domain, as
```shell
git remote add dokku dokku@dokku.me:dokku.me
git push dokku master
```
... deployment ...
remote: -----> Application deployed:
remote: http://dokku.me
## Dokku/Docker Container Management Compatibility
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/dockerfiles/).
## Specifying a custom buildpack
See the [buildpack documentation](/dokku/deployment/buildpacks/).
## Image tagging
See the [image tagging documentation](/dokku/deployment/images/).
## Zero downtime deploy
See the [zero-downtime deploy documentation](/dokku/deployment/zero-downtime-deploys/).

6
docs/deployment/buildpacks.md
View File

@@ -4,7 +4,7 @@ Dokku normally defaults to using [heroku buildpacks](https://devcenter.heroku.co
- 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-management/) for more details.
- 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
@@ -59,7 +59,7 @@ dokku config:set APP BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-no
## Specifying commands via Procfile
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/process-management/) for more details around scaling individual processes.
While many buildpacks have a default command that is run when a detected repository is pushed, it is possible to override this command via a Procfile. A Procfile can also be used to specify multiple commands, each of which is subject to process scaling. See the [process scaling documentation](/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.
@@ -80,7 +80,7 @@ worker: env QUEUE=* bundle exec rake resque:work
importantworker: env QUEUE=important bundle exec rake resque:work
```
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/process-management/) for more details around scaling individual processes.
The `web` process type holds some significance in that it is the only process type that is automatically scaled to `1` on the initial application deploy. See the [process scaling documentation](/dokku/deployment/process-management/) for more details around scaling individual processes.
## Clearing buildpack cache

57
docs/deployment/deployment-tasks.md
View File

@@ -1,57 +0,0 @@
# Deployment Tasks
> New as of 0.5.0
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`.
Simply place an `app.json` file in the root of your repository or for dockerfile apps, `ADD` it to /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.",
"keywords": [
"nodejs",
"express"
],
"repository": "https://github.com/michaelshobbs/node-js-sample",
"scripts": {
"dokku": {
"predeploy": "touch /app/predeploy.test",
"postdeploy": "curl https://some.external.api.service.com/deployment?state=success"
}
},
"env": {
"SECRET_TOKEN": {
"description": "A secret key for verifying the integrity of signed cookies.",
"value": "secret"
},
"WEB_CONCURRENCY": {
"description": "The number of processes to run.",
"generator": "echo 5"
}
},
"image": "gliderlabs/herokuish",
"addons": [
"dokku-postgres",
"dokku-redis"
],
"buildpacks": [
{
"url": "https://github.com/heroku/heroku-buildpack-nodejs"
}
]
}
```

2
docs/deployment/dockerfiles.md
View File

@@ -21,7 +21,7 @@ Dokku will extract all tcp ports exposed using the `EXPOSE` directive (one port
If you do not explicitly `EXPOSE` a port in your `Dockerfile`, dokku will configure the nginx proxy to listen on port 80 (and 443 for TLS) and forward traffic to your app listening on port 5000 inside the container. Just like buildpack apps, you can also use the `$PORT` environment variable in your app to maintain portability.
When ports are exposed through the default nginx proxy, they are proxied externally as HTTP ports. At this time, in no case do we proxy plain TCP or UDP ports. If you'd like to investigate alternative proxy methods, please refer to our [proxy documentation](/dokku/proxy/).
When ports are exposed through the default nginx proxy, they are proxied externally as HTTP ports. At this time, in no case do we proxy plain TCP or UDP ports. If you'd like to investigate alternative proxy methods, please refer to our [proxy management documentation](/dokku/advanced-usage/proxy-management/).
## Customizing the run command

98
docs/deployment/domain-configuration.md
View File

@@ -1,98 +0,0 @@
# Domain Configuration
> New as of 0.3.10
```
domains:add <app> DOMAIN # Add a domain to app
domains [<app>] # List domains
domains:clear <app> # Clear all domains for app
domains:disable <app> # Disable VHOST support
domains:enable <app> # Enable VHOST support
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.

2
docs/deployment/images.md
View File

@@ -57,7 +57,7 @@ dokku tags:deploy node-js-app v1
-----> Deploying node-js-app (dokku/node-js-app:v1)...
-----> Running pre-flight checks
For more efficient zero downtime deployments, create a file CHECKS.
See http://dokku.viewdocs.io/dokku/checks-examples.md for examples
See http://dokku.viewdocs.io/dokku/deployment/zero-downtime-deploys/ for examples
CHECKS file not found in container: Running simple container check...
-----> Waiting for 10 seconds ...
-----> Default container check successful!

46
docs/deployment/process-management.md Normal file
View File

@@ -0,0 +1,46 @@
# Process/Container management
> New as of 0.3.14
Dokku supports rudimentary process (really container) management via the `ps` plugin.
```
ps <app> # List processes running in app container(s)
ps:rebuildall # Rebuild all apps
ps:rebuild <app> # Rebuild an app
ps:restartall # Restart all deployed app containers
ps:restart <app> # Restart app container(s)
ps:scale <app> <proc>=<count> [<proc>=<count>] # Set how many processes of a given process to run
ps:start <app> # Start app container(s)
ps:stop <app> # Stop app container(s)
```
## Scaling
Dokku allows you to run multiple process types at different container counts. For example, if you had an app that contained 1 web app listener and 1 background job processor, dokku can, spin up 1 container for each process type defined in the Procfile. *By default, dokku will only start a single web process (if defined.)* However, if you wanted, for example, 2 job processors running simultaneously, you can modify this behavior in one of the following ways.
### DOKKU_SCALE file
You can optionally create a `DOKKU_SCALE` file in the root of your repository. Dokku expects this file to contain one line for every process defined in your Procfile.
Example:
```Procfile
web=1
worker=2
```
### `ps:scale` command
Dokku can also manage scaling itself via the `ps:scale` command. This command can be used to scale multiple process types at the same time.
```shell
dokku ps:scale app_name web=1 worker=2
```
*NOTE*: Dokku will always use the DOKKU_SCALE file that ships with the repo to override any local settings.
## The web proctype
Like Heroku, we handle the `web` proctype differently from others. The `web` proctype is the only proctype that will invoke custom checks as defined by a CHECKS file. It is also the only proctype that will be launched in a container that is either proxied via nginx or bound to an external port.

28
docs/deployment/remote-commands.md Normal file
View File

@@ -0,0 +1,28 @@
# Remote Commands
Dokku commands can be run over ssh. Anywhere you would run `dokku <command>`, just run `ssh -t dokku@dokku.me <command>`
The `-t` is used to request a pty. It is highly recommended to do so.
To avoid the need to type the `-t` option each time, simply create/modify a section in the `.ssh/config` on the client side, as follows:
```ini
Host dokku.me
RequestTTY yes
```
## Behavioral modifiers
Dokku also supports certain command-line arguments that augment it's behavior. If using these over ssh, you must use the form `ssh -t dokku@dokku.me -- <command>`
in order to avoid ssh interpretting dokku arguments for itself.
```
--quiet suppress output headers
--trace enable DOKKU_TRACE for current execution only
--rm|--rm-container remove docker container after successful dokku run <app> <command>
--force force flag. currently used in apps:destroy and other ":destroy" commands
```
## Clients
You may optionally use a client to connect to your dokku server. Most clients use the configured `git remote` to locate the dokku server, though some allow for overriding this via an environment variable or flag.
Please refer to the [clients](/dokku/community/clients/) list for more details.

129
docs/deployment/ssl-configuration.md
View File

@@ -1,129 +0,0 @@
# SSL Configuration
> New as of 0.4.0
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`.
```shell
cat yourdomain_com.crt yourdomain_com.ca-bundle > server.crt
```
#### SSL and Multiple Domains
When an SSL certificate is associated to an application, the certificate will be associated with *all* domains currently associated with said application. Your certificate _should_ be associated with all of those domains, otherwise accessing the application will result in SSL errors. If you wish to remove one of the domains from the application, refer to the [domain configuration documentation](/dokku/deployment/domain-configuration/).
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/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...
-----> Certificate details:
=====> Common Name(s):
=====> test.dokku.me
=====> Expires At: Aug 24 23:32:59 2016 GMT
=====> Issuer: C=US, ST=California, L=San Francisco, O=dokku.me, CN=test.dokku.me
=====> Starts At: Aug 25 23:32:59 2015 GMT
=====> Subject: C=US; ST=California; L=San Francisco; O=dokku.me; CN=test.dokku.me
=====> SSL certificate is self signed.
```
### Certificate removal
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/nginx/#customizing-the-nginx-configuration)
```go
server {
listen [::]:{{ .NGINX_PORT }};
listen {{ .NGINX_PORT }};
server_name {{ .NOSSL_SERVER_NAME }};
access_log /var/log/nginx/{{ .APP }}-access.log;
error_log /var/log/nginx/{{ .APP }}-error.log;
# set a custom header for requests
add_header X-Served-By www-ec2-01;
location / {
proxy_pass http://{{ .APP }};
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
proxy_set_header X-Forwarded-For $http_x_forwarded_for;
proxy_set_header X-Forwarded-Port $http_x_forwarded_port;
proxy_set_header X-Request-Start $msec;
}
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.

319
docs/deployment/zero-downtime-deploys.md Normal file
View File

@@ -0,0 +1,319 @@
# Zero Downtime Deploys
> New as of 0.5.0
```
checks <app> # Show zero-downtime status
checks:disable <app> [process-type(s)] # Disable zero-downtime deployment for all processes (or comma-separated process-type list) ***WARNING: this will cause downtime during deployments***
checks:enable <app> [process-type(s)] # Enable zero-downtime deployment for all processes (or comma-separated process-type list)
checks:skip <app> [process-type(s)] # Skip zero-downtime checks for all processes (or comma-separated process-type list)
```
Following a deploy, dokku will wait `10` seconds before routing traffic to the new container to give your application time to boot up. If the application is not running after this time, then the deploy is failed and your old container will continue serving traffic. You can modify this value globally or on a per-application basis:
```shell
dokku config:set --global DOKKU_DEFAULT_CHECKS_WAIT=30
dokku config:set node-js-app DOKKU_DEFAULT_CHECKS_WAIT=30
```
You can also choose to skip checks or disable zero-downtime completely on a per-application/per-process basis
> Note that `checks:disable` will now (as of 0.6.0) cause downtime for that process-type during deployments.
```shell
dokku checks:skip node-js-app worker,web
```
```
-----> Skipping zero downtime for app's (node-js-app) proctypes (worker,web)
-----> Unsetting node-js-app
-----> Unsetting DOKKU_CHECKS_DISABLED
-----> Setting config vars
DOKKU_CHECKS_SKIPPED: worker,web
```
Additionally, any given process can only be configured to disable zero-downtime. example:
```shell
dokku checks:disable node-js-app worker
```
```
-----> Disabling zero downtime for app's (node-js-app) proctypes (worker)
-----> Setting config vars
DOKKU_CHECKS_DISABLED: worker
-----> Setting config vars
DOKKU_CHECKS_SKIPPED: web
```
Dokku will wait `60` seconds before stopping the old container so that existing connections are given a chance to complete. You can modify this value globally or on a per-application basis:
```shell
dokku config:set --global DOKKU_WAIT_TO_RETIRE=120
dokku config:set <app> DOKKU_WAIT_TO_RETIRE=120
```
> Note that during this time, multiple containers may be running on your server, which can be an issue for memory-hungry applications on memory-constrained servers.
## Checks
If your application needs a longer period to boot up - perhaps to load data into memory, or because of slow boot time - you may also use dokku's `checks` functionality to more precisely check whether an application can serve traffic or not.
Checks are run against the detected `web` process from your application's `Procfile`. For non-web processes, dokku will fallback to the aforementioned process uptime check.
To specify checks, add a `CHECKS` file to the root of your project directory. The `CHECKS` file should be plain text and may contain:
* Check instructions
* Settings (NAME=VALUE)
* Comments (lines starting with #)
* Empty lines
> For dockerfile-based deploys, the file *must* be in `/app/CHECKS` within the container. `/app` is used by default as the root container directory for buildpack-based deploys.
### Check Instructions
The format of a check instruction is a path or relative URL, optionally followed by the expected content:
```
/about Our Amazing Team
```
The `CHECKS` file can contain multiple checks:
```
/ 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:
```
//admin.example.com Admin Dashboard
//static.example.com/logo.png
```
You can also specify the protocol to explicitly check HTTPS requests:
```
https://admin.example.com Admin Dashboard
https://static.example.com/logo.png
```
### Check Settings
The default behavior is to wait for `5` seconds before running the checks, to timeout the checks after `30` seconds, and to attempt the checks `5` times. If the checks fail `5` times, the deployment is considered failed and the old container will continue serving traffic.
You can change the default behavior by setting `WAIT`, `TIMEOUT`, and `ATTEMPTS` to different values in the `CHECKS` file:
```
WAIT=30 # Wait 1/2 minute
TIMEOUT=60 # Timeout after a minute
ATTEMPTS=10 # Attempt checks 10 times
/ My Amazing App
```
You can also override the default `WAIT`, `TIMEOUT`, and `ATTEMPTS` variables for the global dokku installation:
```shell
dokku config:set --global DOKKU_CHECKS_WAIT=30
dokku config:set --global DOKKU_CHECKS_TIMEOUT=60
dokku config:set --global DOKKU_CHECKS_ATTEMPTS=10
```
If your application runs multiple processes (a background worker configured in your `Procfile`, for example) and you have checks to ensure that your web application has booted up, you may want to disable the default check wait time for that application to avoid the `10` second wait per non-web process:
```shell
dokku config:set <app> DOKKU_DEFAULT_CHECKS_WAIT=0
```
### Configuring docker stop timeout
[By default](https://docs.docker.com/engine/reference/commandline/stop/), docker will wait 10 seconds from the time the `stop` command is passed to a container before it attempts to kill said container. This timeout can be configured on a per-app basis in dokku by setting the `DOKKU_DOCKER_STOP_TIMEOUT` configuration variable. This timeout applies to normal zero-downtime deployments as well as the `ps:stop` and `apps:destroy` commands.
```shell
dokku config:set $APP DOKKU_DOCKER_STOP_TIMEOUT=20
```
## Example: Successful Rails Deployment
In this example, a Rails application is successfully deployed to dokku. The initial round of checks fails while the server is starting, but once it starts they succeed and the deployment is successful. `WAIT` is set to `10` because our application takes a while to boot up. `ATTEMPTS` is set to `6`, but the third attempt succeeds.
### CHECKS file
```
WAIT=10
ATTEMPTS=6
/check.txt simple_check
```
For this check to work, we've added a line to `config/routes.rb` that simply returns a string:
```
get '/check.txt', to: proc {[200, {}, ['simple_check']]}
```
### Deploy Output
> Note: The output has been trimmed for brevity
```shell
git push dokku master
```
```
-----> Cleaning up...
-----> Building myapp from herokuish...
-----> 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 10 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 10 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 10 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=10
ATTEMPTS=6
/
```
> The check to the root url '/' would normally access the database.
### Deploy Output
> Note: The output has been trimmed for brevity
```shell
git push dokku master
```
```
-----> Cleaning up...
-----> Building myapp from herokuish...
-----> 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 10 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 10 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 10 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 10 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 10 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 10 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
TCP/IP connections on port 5431?
):
vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:651:in `initialize'
vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:651:in `new'
vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:651:in `connect'
vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:242:in `initialize'
vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:44:in `new'
vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:44:in `postgresql_connection
=====> end myapp container output
/usr/bin/dokku: line 49: 23409 Killed dokku deploy "$APP"
To dokku@dokku.example.com:myapp
! [remote rejected] dokku -> master (pre-receive hook declined)
error: failed to push some refs to 'dokku@dokku.example.com:myapp'
```