Merge pull request #492 from jeroenvisser101/cache-docs

docs(slugbuilder-cache): add docs for the slugbuilder cache

Author: Matthew Fisher

src/applications/deploying-apps.md

@@ -60,6 +60,7 @@ It is possible to configure a few of the [globally tunable](../applications/mana
 
 Setting                                         | Description
 ----------------------------------------------- | ---------------------------------
+DEIS_DISABLE_CACHE                              | if set, this will disable the [slugbuilder cache][] (default: not set)
 DEIS_DEPLOY_BATCHES                             | the number of pods to bring up and take down sequentially during a scale (default: number of available nodes)
 DEIS_DEPLOY_TIMEOUT                             | deploy timeout in seconds per deploy batch (default: 120)
 IMAGE_PULL_POLICY                               | the kubernetes [image pull policy][pull-policy] for application images (default: "IfNotPresent") (allowed values: "Always", "IfNotPresent")
@@ -100,6 +101,7 @@ each having multiple ReplicaSets (one per release) which in turn manage the Pods
 Deis Workflow will behave the same way with `DEIS_KUBERNETES_DEPLOYMENTS` enabled or disabled (only applicable to versions prior to 2.4).
 The changes are behind the scenes. Where you will see differences while using the CLI is `deis ps:list` will output Pod names differently.
 
+[slugbuilder cache]: ./managing-app-configuration.md#slugbuilder-cache
 [install client]: ../users/cli.md#installation
 [application]: ../reference-guide/terms.md#application
 [controller]: ../understanding-workflow/components.md#controller

src/applications/managing-app-configuration.md

@@ -52,6 +52,32 @@ the application to an external PostgreSQL database.
 Detachments can be performed with `deis config:unset`.
 
 
+## Slugbuilder Cache
+
+By default, apps using the [Slugbuilder][] will have caching turned on. This means that Deis will
+persist all data being written to `CACHE_DIR` inside the buildpack will be persisted between
+deploys. When deploying applications that depend on third-party libraries that have to be fetched,
+this could speed up deployments a lot. In order to make use of this, the buildpack must implement
+the cache by writing to the cache directory. Most buildpacks already implement this, but when using
+custom buildpacks, it might need to be changed to make full use of the cache.
+
+### Disabling and re-enabling the cache
+
+In some cases, cache might not speed up your application. To disable caching, you can set the
+`DEIS_DISABLE_CACHE` variable with `deis config:set DEIS_DISABLE_CACHE=1`. When you disable the
+cache, Deis will clear up files it created to store the cache. After having it turned off, run
+`deis config:unset DEIS_DISABLE_CACHE` to re-enable the cache.
+
+### Clearing the cache
+
+Use the following procedure to clear the cache:
+
+    $ deis config:set DEIS_DISABLE_CACHE=1
+    $ git commit --allow-empty -m "Clearing Deis cache"
+    $ git push deis # (if you use a different remote, you should use your remote name)
+    $ deis config:unset DEIS_DISABLE_CACHE
+
+
 ## Custom Health Checks
 
 By default, Workflow only checks that the application starts in their Container. If it is preferred
@@ -179,7 +205,7 @@ TCP Socket Probe: N/A
 Configured health checks also modify the default application deploy behavior. When starting a new
 Pod, Workflow will wait for the health check to pass before moving onto the next Pod.
 
-
+[Slugbuilder]: ../understanding-workflow/components.md#builder-builder-slugbuilder-and-dockerbuilder
 [attached resources]: http://12factor.net/backing-services
 [stores config in environment variables]: http://12factor.net/config
 [release]: ../reference-guide/terms.md#release

src/installing-workflow/configuring-object-storage.md

@@ -115,7 +115,8 @@ Slugbuilder is configured and launched by the builder component. Slugbuilder rea
 If you are using slugbuilder as a standalone component the following configuration is important:
 
 - `TAR_PATH` - The location of the application `.tar` archive, relative to the configured bucket for builder e.g. `home/burley-yeomanry:git-3865c987/tar`
-- `PUT_PATH` - The location to upload the finished slug, relative to the configured bucket fof builder e.g. `home/burley-yeomanry:git-3865c987/push`
+- `PUT_PATH` - The location to upload the finished slug, relative to the configured bucket of builder e.g. `home/burley-yeomanry:git-3865c987/push`
+- `CACHE_PATH` - The location to upload the cache, relative to the configured bucket of builder e.g. `home/burley-yeomanry/cache`
 
 !!! note
 	These environment variables are case-sensitive.