dokku · josegonzalez · Nov 9, 2015 · Nov 9, 2015
diff --git a/docs/application-deployment.md b/docs/application-deployment.md
@@ -128,20 +128,6 @@ 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.
 
-### 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 APP with the name of your application
-# replace REPOSITORY_URL with your buildpack's url
-dokku config:set APP BUILDPACK_URL=REPOSITORY_URL
-```
-
-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 subdomains
 
 The name of remote repository is used as the name of application to be deployed, as for example above:
@@ -178,6 +164,10 @@ This is in particular useful, then you want to deploy to root domain, as
 
 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/progrium/dokku/issues/1220), dokku executes a cleanup function prior to every deployment. This function removes all exited containers and all 'unattached' images.
 
+### Specifying a custom buildpack
+
+See the [buildpack documentation](/dokku/deployment/buildpacks/).
+
 ## Default vhost
 
 See the [nginx documentation](/dokku/nginx/#default-site).

diff --git a/docs/deployment/buildpacks.md b/docs/deployment/buildpacks.md
@@ -0,0 +1,72 @@
+# Buildpack Deployment
+
+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.
+- 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 APP with the name of your application
+# replace REPOSITORY_URL with your buildpack's url
+dokku config:set APP BUILDPACK_URL=REPOSITORY_URL
+```
+
+Please check the documentation for your particular buildpack as you may need to include configuration files (such as a Procfile) in your project root.
+
+## 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:
+
+```shell
+https://github.com/heroku/heroku-buildpack-nodejs.git
+https://github.com/heroku/heroku-buildpack-ruby.git
+```
+
+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:
+
+```shell
+# using the latest nodejs buildpack
+# replace APP with the name of your application
+dokku config:set APP BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-nodejs
+```
+
+You may also wish to use a **specific** version of a buildpack, which is also simple
+
+```shell
+# using v87 of the nodejs buildpack
+# replace APP with the name of your application
+dokku config:set APP BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-nodejs#v87
+```
+
+## Clearing buildpack 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:
+
+```shell
+# replace APP with the name of your application
+sudo rm -rf /home/dokku/APP/cache/*
+```
+
+### 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
+```
diff --git a/docs/template.html b/docs/template.html
@@ -66,6 +66,7 @@ <h1 class="heading navbar-brand">
             <a href="#" class="list-group-item disabled">Deployment</a>
 
             <a href="/dokku/application-deployment/" class="list-group-item">Deploying an Application</a>
+            <a href="/dokku/deployment/buildpacks/" class="list-group-item">Buildpack Deployment</a>
             <a href="/dokku/deployment/dockerfiles/" class="list-group-item">Dockerfile Deployment</a>
             <a href="/dokku/deployment/images/" class="list-group-item">Image Tagging</a>
             <a href="/dokku/remote-commands/" class="list-group-item">Remote Commands</a>

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -138,12 +138,11 @@ If you see output similar this when deploying:
  !     tar: Error is not recoverable: exiting now
 ```
 
-it might that the curl command that is supposed to fetch the buildpack (anything in the low megabyte file size range) takes too long to finish, due to slowish connection.  To overwrite the default values (connection timeout: 3 seconds, total maximum time for operation: 30 seconds), edit `/home/dokku/ENV` like the following:
+it might that the curl command that is supposed to fetch the buildpack (anything in the low megabyte file size range) takes too long to finish, due to slowish connection.  To overwrite the default values (connection timeout: 3 seconds, total maximum time for operation: 30 seconds), set the following environment variables:
 
-```
-#/home/dokku/ENV
-export CURL_TIMEOUT=600
-export CURL_CONNECT_TIMEOUT=30
+```shell
+dokku config:set --global CURL_TIMEOUT=600
+dokku config:set --global CURL_CONNECT_TIMEOUT=30
 ```
 
 References