Merge pull request #3730 from habitat-sh/dw/cf_export

Added docs on exporting to Cloud Foundry

www/source/partials/docs/_dev-pkgs-exports.html.md.erb

@@ -68,7 +68,7 @@ You can create an Application Container Image (ACI) for any package by performin
 
 5. The `.aci` can now be moved to any runtime capable of running ACIs (e.g. [rkt](https://coreos.com/rkt/) on CoreOS) for execution.
 
-##Exporting to Apache Mesos and DC/OS
+## Exporting to Apache Mesos and DC/OS
 
 1. Create an interactive studio in any directory with the `hab studio enter` command.
 
@@ -96,3 +96,85 @@ You can create an Application Container Image (ACI) for any package by performin
 5. Note that the default resource allocation for the application is very small: 0.5 units of CPU, no disk, one instance, and 256MB of memory. To change these resource allocations, pass different values to the Mesos exporter as command line options (defaults are documented with `--help`).
 
 6. See the article [Apaches Mesos and DC/OS](/docs/best-practices/#mesos-dcos) for more information on getting your application running on Mesos.
+
+## Exporting to Cloud Foundry
+
+Packages can be exported to run in a [Cloud Foundry plaform](https://www.cloudfoundry.org/certified-platforms/) through the use of a Docker image that contains additional layers meant to handle mapping from the Cloud Foundry environment to a Habitat default.toml file. 
+
+### Setting up Docker support in Cloud Foundry
+
+If you have not done so already, you must enable Docker support for Cloud Foundry before you can upload your Cloud Foundry-specific Docker image.
+
+To do so, make sure you have done the following:
+
+1. Log in as an Admin user.
+2. Enable Docker support on your Cloud Foundry deployment by enabling the `diego_docker` feature flag.
+
+   ```
+   $ cf enable-feature-flag diego_docker
+   ```
+
+### Creating a Mapping file
+
+The mapping file is a TOML file that can add Bash-interpolated variables and scripts. The Bash code will have access to:
+
+* all environment variables
+* the jq binary
+* the helper methods listed below
+
+Here's an example of a mapping TOML file named `cf-mapping.toml`:
+
+```
+secret_key_base = "$SECRET_KEY_BASE"
+rails_env = "$RAILS_ENV"
+port = ${PORT}
+
+[db]
+user = "$(service "elephantsql" '.credentials.username')"
+password = "$(service "elephantsql" '.credentials.password')"
+host = "$(service "elephantsql" '.credentials.host')"
+name = "$(service "elephantsql" '.credentials.database')"
+```
+
+#### Helpers
+
+The helper methods are designed to extract information from the standard Cloud Foundry environment variables [VCAP_SERVICES](https://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES) and [VCAP_APPLICATION](https://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-APPLICATION).
+
+* `service <service-name> <jq-expression>` will extract the JSON associated with the given service-name from the `VCAP_SERVICES` environment variable and apply the jq-expression to it.
+* `application <jq-expression>` will apply the jq-expression to the `VCAP_APPLICATION` environment variable
+
+### Exporting and pushing to Cloud Foundry endpoint
+
+1. Create a mapping.toml file using the format specified above and place that file in your local project repo.
+
+2. Enter the Studio through `hab studio enter`.
+
+3. Install or [build](/docs/developing-packages/#plan-builds) the package that you want to export.
+
+    ```
+    $ hab pkg install yourorigin/yourpackage
+    ```
+
+4. Run the Cloud Foundry exporter on the package.
+
+    ```
+    $ hab pkg export cf yourorigin/yourpackage /path/to/mapping.toml
+    ```
+
+   > **Note** To generate this image, a base Docker image is also created. The Cloud Foundry version of the docker image will have `cf-` as a prefix in the image tag.
+
+5. (Optional) If you are creating a web app that binds to another Cloud Foundry service, such as ElephantSQL, you must have this service enabled in your deployment before running your app.
+
+6. [Upload your Docker image to a supported registry](https://docs.cloudfoundry.org/devguide/deploy-apps/push-docker.html). Your Docker repository should be match the `origin/package` identifier of your package. 
+
+    ```
+    $ docker push origin/package:cf-version-release
+    ```
+
+7. After your Cloud Foundry Docker image is built, you can deploy it to a Cloud Foundry platform. 
+
+    ```
+    $cf push cf push APP-NAME --docker-image docker_org/repository
+    ```
+
+   Your application will start after it has been successfully uploaded and deployed.