dokku · josegonzalez · Oct 16, 2015 · Oct 14, 2015 · Oct 14, 2015 · Oct 14, 2015
diff --git a/docs/application-deployment.md b/docs/application-deployment.md
diff --git a/docs/assets/style.css b/docs/assets/style.css
@@ -228,6 +228,16 @@ pre {
   color: #4d4d4c;
   margin: 2em 0;
 }
+blockquote {
+  border-left: 4px solid #5bc0de;
+  background-color: #f4f8fa;
+  padding: 15px 15px 1px;
+  margin-bottom: 30px;
+}
+blockquote.new-as-of {
+  border-left: 4px solid #ef5b58;
+  background-color: #f9ad76;
+}
 @media (min-width: 768px) {
   .quickstart-code {
     font-size: 14px;

diff --git a/docs/checks-examples.md b/docs/checks-examples.md
@@ -1,41 +1,104 @@
-# Checks Examples
+# Zero Downtime Deploys
+
+> New as of 0.3.0
+
+Following a deploy, dokku will now wait `10` seconds before routing traffic to the nwe container. If the container is not running after this time, then the deploy is failed and your old container will continue serving traffic. You can configure this time using the following command:
+
+```shell
+dokku config:set --global DOKKU_DEFAULT_CHECKS_WAIT=30
+```
+
+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.
+
+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 `5` seconds before running the checks to give server time to start. This time can be overridden on a per-app basis in the `CHECKS` file by setting `WAIT=nn`. You may also override this for the global dokku installation:
+
+```shell
+dokku config:set --global DOKKU_CHECKS_WAIT=15
+```
+
+Dokku will wait `60` seconds before stopping the old container so that existing connections are given a chance to complete. This time is also configurable globally:
+
+```shell
+dokku config:set --global 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.
+
+Dokku will retry the checks `5` times until the checks are successful. If all 5 checks fail, the deployment is considered failed. This can be overridden in the `CHECKS` file by setting `ATTEMPTS=nn`. This number is also configurable globally:
+
+```shell
+dokku config:set --global DOKKU_CHECKS_ATTEMPTS=2
+```
+
+You can also choose to skip checks completely either globally or on a per-application basis:
+
+```shell
+# globally
+dokku config:set --global DOKKU_SKIP_ALL_CHECKS=true
+
+# for APP
+dokku config:set APP DOKKU_SKIP_ALL_CHECKS=true
+```
+
+## Checks Examples
 
 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
+```
+/                       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
+```
+//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.
+
+```
+https://admin.example.com     Admin Dashboard
+https://static.example.com/logo.png
+```
+
+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
+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
+```
+WAIT=30     # Wait 1/2 minute
+TIMEOUT=60  # Timeout after a minute
+ATTEMPTS=10  # attempt checks 10 times
+
+/                       My Amazing App
+```
+
+## Example: Successful Rails Deployment
 
-# 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.
+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
+### CHECKS file
 
 ````
 WAIT=5
@@ -45,7 +108,7 @@ ATTEMPTS=6
 
 > check.txt is a text file returning the string 'simple_check'
 
-## Deploy Output
+### Deploy Output
 
 > Note: The output has been trimmed for brevity
 
@@ -101,12 +164,12 @@ curl: (7) Failed to connect to 172.17.0.155 port 5000: Connection refused
        http://myapp.dokku.example.com
 ````
 
-# Example: Failing Rails Deployment
+## Example: Failing Rails Deployment
 In this example, a Rails application fails to deploy.  The reason for the failure is that the postgres database connection fails.  The initial checks will fail while we wait for the server to start up, just like in the above example.  However, once the server does start accepting connections, we will see an error 500 due to the postgres database connection failure.
 
 Once the attempts have been exceeded, the deployment fails and we see the container output, which shows the Postgres connection errors.
 
-## CHECKS file
+### CHECKS file
 
 ````
 WAIT=5
@@ -116,7 +179,7 @@ ATTEMPTS=6
 
 > The check to the root url '/' would normally access the database.
 
-## Deploy Output
+### Deploy Output
 
 > Note: The output has been trimmed for brevity
 

diff --git a/docs/configuration-management.md b/docs/configuration-management.md
@@ -1,16 +1,57 @@
-# Configuration management
+# Environment Variables
 
 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
+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. You no longer need a `user-env` plugin as Dokku handles this functionality in a way equivalent to how Heroku handles it.
+The variables are available both at run time and during the application build/compilation step.
 
-> 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.
+> 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:
+
+```shell
+dokku config:set node-js-app ENV=prod COMPILE_ASSETS=1
+```
+
+When setting variables with whitespace, you need to escape the whitespace:
+
+```shell
+dokku config:set node-js-app KEY=\"VAL\ WITH\ SPACES\"
+```
+
+When setting or unsetting environment variables, you may wish sometimes 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:
+
+```shell
+dokku --no-restart config:set node-js-app ENV=prod
+```
+
+If you wish to have the variables output in an `eval`-compatible form, you can use the `--export` flag:
+
+```shell
+dokku config node-js-app --export
+# outputs variables in the form:
+#
+#   export ENV='prod'
+#   export COMPILE_ASSETS='1'
+
+# source in all the node-js-app app environment variables
+eval $(dokku config node-js-app --export)
+```
+
+You can also output the variables in a single-line for usage in command-line utilities with the `--shell` flag:
+
+```shell
+dokku config node-js-app --shell
+
+# outputs variables in the form:
+#
+#   ENV='prod' COMPILE_ASSETS='1'
+```
diff --git a/docs/deployment/dockerfiles.md b/docs/deployment/dockerfiles.md
@@ -0,0 +1,41 @@
+# Dockerfile Deployment
+
+> New as of 0.3.15
+
+While Dokku normally defaults to using [heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, you can also use docker's native `Dockerfile` system to define a container.
+
+To use a dockerfiles for deployment, commit a valid `Dockerfile` to the root of your repository and push the repository to your Dokku installation. If this file is detected, Dokku will default to using it to construct containers **except** in the following two cases:
+
+- The application has a `BUILDPACK_URL` environment variable set via the `dokku config:set` command or in a committed `.env` file. In this case, Dokku will use your specified buildpack.
+- The application has a `.buildpacks` file in the root of the repository. In this case, Dokku will use your specified buildpack(s).
+
+## Exposed ports
+
+By default, Dokku will extract the first `EXPOSE` tcp port and use said port with nginx to proxy your app to that port. For applications that have multiple ports exposed, you may override this port via the following command:
+
+```shell
+# replace APP with the name of your application
+dokku config:set APP DOKKU_DOCKERFILE_PORT=8000
+```
+
+Dokku will not expose other ports on your application without a [custom docker-option](/dokku/configuration/docker-options/).
+
+If you do not have a port explicitly exposed, Dokku will automatically expose port `5000` for your application.
+
+## Customizing the run command
+
+By default no arguments are passed to `docker run` when deploying the container and the `CMD` or `ENTRYPOINT` defined in the `Dockerfile` are executed. You can take advantage of docker ability of overriding the `CMD` or passing parameters to your `ENTRYPOINT` setting `$DOKKU_DOCKERFILE_START_CMD`. Let's say for example you are deploying a base nodejs image, with the following `ENTRYPOINT`:
+
+```
+ENTRYPOINT ["node"]
+```
+
+You can do:
+
+```
+dokku config:set APP DOKKU_DOCKERFILE_START_CMD="--harmony server.js"
+```
+
+To tell docker what to run.
+
+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`.
diff --git a/docs/deployment/images.md b/docs/deployment/images.md
@@ -0,0 +1,57 @@
+# Image Tagging
+
+> New as of 0.4.0
+
+The dokku tags plugin allows you to add docker image tags to the currently deployed app image for versioning and subsequent deployment.
+
+```
+tags <app>                                       List all app image tags
+tags:create <app> <tag>                          Add tag to latest running app image
+tags:deploy <app> <tag>                          Deploy tagged app image
+tags:destroy <app> <tag>                         Remove app image tag
+```
+
+Example:
+
+```
+root@dokku:~# dokku tags node-js-app
+=====> Image tags for dokku/node-js-app
+REPOSITORY          TAG                 IMAGE ID            CREATED              VIRTUAL SIZE
+dokku/node-js-app   latest              936a42f25901        About a minute ago   1.025 GB
+
+root@dokku:~# dokku tags:create node-js-app v0.9.0
+=====> Added v0.9.0 tag to dokku/node-js-app
+
+root@dokku:~# dokku tags node-js-app
+=====> Image tags for dokku/node-js-app
+REPOSITORY          TAG                 IMAGE ID            CREATED              VIRTUAL SIZE
+dokku/node-js-app   latest              936a42f25901        About a minute ago   1.025 GB
+dokku/node-js-app   v0.9.0              936a42f25901        About a minute ago   1.025 GB
+
+root@dokku:~# dokku tags:deploy node-js-app v0.9.0
+-----> Releasing node-js-app (dokku/node-js-app:v0.9.0)...
+-----> Deploying node-js-app (dokku/node-js-app:v0.9.0)...
+-----> Running pre-flight checks
+       For more efficient zero downtime deployments, create a file CHECKS.
+       See http://progrium.viewdocs.io/dokku/checks-examples.md for examples
+       CHECKS file not found in container: Running simple container check...
+-----> Waiting for 10 seconds ...
+-----> Default container check successful!
+=====> node-js-app container output:
+       Detected 512 MB available memory, 512 MB limit per process (WEB_MEMORY)
+       Recommending WEB_CONCURRENCY=1
+       > node-js-app@0.1.0 start /app
+       > node index.js
+       Node app is running at localhost:5000
+=====> end node-js-app container output
+-----> Running post-deploy
+-----> Configuring node-js-app.dokku.me...
+-----> Creating http nginx.conf
+-----> Running nginx-pre-reload
+       Reloading nginx
+-----> Shutting down old containers in 60 seconds
+=====> 025eec3fa3b442fded90933d58d8ed8422901f0449f5ea0c23d00515af5d3137
+=====> Application deployed:
+       http://node-js-app.dokku.me
+
+```