Improve documentation on setting config variables

Christopher Frost · Christopher Frost · commit 649b9f9c2035 · 2015-09-15T15:36:42.000+01:00
This commit improves the documentation around using environment variables to set configuration values. This includes some new examples of how to set values from an applications manifest file.

[#102675140]
diff --git a/README.md b/README.md
@@ -27,19 +27,33 @@ The following are _very_ simple examples for deploying the artifact types that w
 ## Configuration and Extension
 The buildpack supports extension through the use of Git repository forking. The easiest way to accomplish this is to use [GitHub's forking functionality][] to create a copy of this repository.  Make the required extension changes in the copy of the repository. Then specify the URL of the new repository when pushing Cloud Foundry applications. If the modifications are generally applicable to the Cloud Foundry community, please submit a [pull request][] with the changes.
 
-Buildpack configuration can be overridden with an environment variable matching the configuration file you wish to override minus the `.yml` extension and with a prefix of `JBP_CONFIG`. It is not possible to add new configuration properties and properties with `nil` or empty values will be ignored by the buildpack. The value of the variable should be valid inline yaml. For example, to change the default version of Java to 7 and adjust the memory heuristics apply this environment variable to the application.
+Buildpack configuration can be overridden with an environment variable matching the configuration file you wish to override minus the `.yml` extension and with a prefix of `JBP_CONFIG`. It is not possible to add new configuration properties and properties with `nil` or empty values will be ignored by the buildpack. The value of the variable should be valid inline yaml, referred to as `flow style` in the yaml spec. For example, to change the default version of Java to 7 and adjust the memory heuristics apply this environment variable to the application.
 
 ```bash
-$ cf set-env my-application JBP_CONFIG_OPEN_JDK_JRE 'jre: { version: 1.7.0_+ }'
+$ cf set-env my-application JBP_CONFIG_OPEN_JDK_JRE '[jre: { version: 1.7.0_+ }]'
 ```
 
 If the key or value contains a special character such as `:` it should be escaped with double quotes. For example, to change the default repository path for the buildpack.
 
 ```bash
-$ cf set-env my-application JBP_CONFIG_REPOSITORY 'default_repository_root: "http://repo.example.io"'
+$ cf set-env my-application JBP_CONFIG_REPOSITORY '[default_repository_root: "http://repo.example.io"]'
 ```
 
-Environment variable can also be specified in the applications `manifest` file. See the [Environment Variables][] documentation for more information.
+Environment variable can also be specified in the applications `manifest` file. For example, to specify an environment variable in an applications manifest file that disables Auto-reconfiguration.
+
+```bash
+  env: 
+    JBP_CONFIG_SPRING_AUTO_RECONFIGURATION: '[enabled: false]'
+```
+
+This final example shows how to change the version of Tomcat that is used by the buildpack with an environment variable specified in the applications manifest file.
+
+```bash
+  env: 
+    JBP_CONFIG_TOMCAT: '[tomcat: { version: 8.0.+ }]'
+```
+
+See the [Environment Variables][] documentation for more information.
 
 To learn how to configure various properties of the buildpack, follow the "Configuration" links below. More information on extending the buildpack is available [here](docs/extending.md).
 
diff --git a/docs/container-groovy.md b/docs/container-groovy.md
@@ -22,7 +22,7 @@ Tags are printed to standard output by the buildpack detect script
 Any JAR files found in the application are automatically added to the classpath at runtime.
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The container can be configured by modifying the [`config/groovy.yml`][] file in the buildpack fork.  The container uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
 
diff --git a/docs/container-java_main.md b/docs/container-java_main.md
@@ -25,7 +25,7 @@ If the application uses Spring, [Spring profiles][] can be specified by setting
 If the main class is Spring Boot's `JarLauncher`, `PropertiesLauncher` or `WarLauncher`, the Java Main Container adds a `--server.port` argument to the command so that the application uses the correct port.
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The container can be configured by modifying the `config/java_main.yml` file in the buildpack fork.
 
diff --git a/docs/container-spring_boot_cli.md b/docs/container-spring_boot_cli.md
@@ -22,7 +22,7 @@ Tags are printed to standard output by the buildpack detect script.
 If the application uses Spring, [Spring profiles][] can be specified by setting the [`SPRING_PROFILES_ACTIVE`][] environment variable. This is automatically detected and used by Spring. The Spring Auto-reconfiguration Framework will specify the `cloud` profile in addition to any others. 
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The container can be configured by modifying the [`config/spring_boot_cli.yml`][] file in the buildpack fork.  The container uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
 
diff --git a/docs/container-tomcat.md b/docs/container-tomcat.md
@@ -15,7 +15,7 @@ Tags are printed to standard output by the buildpack detect script
 If the application uses Spring, [Spring profiles][] can be specified by setting the [`SPRING_PROFILES_ACTIVE`][] environment variable. This is automatically detected and used by Spring. The Spring Auto-reconfiguration Framework will specify the `cloud` profile in addition to any others.
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The container can be configured by modifying the [`config/tomcat.yml`][] file in the buildpack fork.  The container uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
 
diff --git a/docs/extending-caches.md b/docs/extending-caches.md
@@ -39,7 +39,7 @@ end
 ```
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 Caching can be configured by modifying the [`config/cache.yml`][] file in the buildpack fork.
 
diff --git a/docs/extending-logging.md b/docs/extending-logging.md
@@ -24,7 +24,7 @@ logger.debug { "#{costly_method}" }
 ```
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The console logging severity filter is set to `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` using the following strategies in descending priority:
 
diff --git a/docs/extending-repositories.md b/docs/extending-repositories.md
@@ -59,7 +59,7 @@ end
 | `{architecture}` | The architecture of the system as returned by Ruby.  The value is typically one of `x86_64` or `x86`.
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 Repositories can be configured by modifying the [`config/repository.yml`][] file in the buildpack fork.
 
diff --git a/docs/framework-app_dynamics_agent.md b/docs/framework-app_dynamics_agent.md
@@ -29,7 +29,7 @@ When binding AppDynamics using a user-provided service, it must have name or tag
 To provide more complex values such as the `tier-name`, using the interactive mode when creating a user-provided service will manage the character escaping automatically. For example, the default `tier-name` could be set with a value of `Tier-$(expr "$VCAP_APPLICATION" : '.*instance_index[": ]*\([[:digit:]]*\).*')` to calculate a value from the Cloud Foundry instance index.
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The framework can be configured by modifying the [`config/app_dynamics_agent.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
 
diff --git a/docs/framework-dyna_trace_agent.md b/docs/framework-dyna_trace_agent.md
@@ -58,7 +58,7 @@ TIP: Changes will not apply to existing running applications until they are rest
 ```
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The framework can be configured by modifying the [`config/dyna_trace_agent.yml`][] file in the buildpack fork.  The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
 
diff --git a/docs/framework-introscope_agent.md b/docs/framework-introscope_agent.md
@@ -31,7 +31,7 @@ The credential payload of the service may contain the following entries:
 To provide more complex values such as the `agent-name`, using the interactive mode when creating a user-provided service will manage the character escaping automatically. For example, the default `agent-name` could be set with a value of `agent-$(expr "$VCAP_APPLICATION" : '.*application_name[": ]*\([[:word:]]*\).*')` to calculate a value from the Cloud Foundry application name.
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The framework can be configured by modifying the [`config/introscope_agent.yml`][] file in the buildpack fork.  The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
 
diff --git a/docs/framework-java_opts.md b/docs/framework-java_opts.md
@@ -16,7 +16,7 @@ Tags are printed to standard output by the buildpack detect script
 
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The framework can be configured by creating or modifying the [`config/java_opts.yml`][] file in the buildpack fork.
 
diff --git a/docs/framework-jrebel_agent.md b/docs/framework-jrebel_agent.md
@@ -17,7 +17,7 @@ Tags are printed to standard output by the buildpack detect script
 For more information regarding setup and configuration, please refer to the [JRebel with Pivotal Cloud Foundry tutorial][pivotal].
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The framework can be configured by modifying the [`config/jrebel_agent.yml`][] file in the buildpack fork.  The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
 
diff --git a/docs/framework-luna_security_provider.md b/docs/framework-luna_security_provider.md
@@ -27,7 +27,7 @@ When binding to the Luna Security Provider using a user-provided service, it mus
 To provide more complex values such as the PEM certificates, using the interactive mode when creating a user-provided service will manage the character escaping automatically.
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The framework can be configured by modifying the [`config/luna_security_provider.yml`][] file in the buildpack. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
 
diff --git a/docs/framework-maria_db_jdbc.md b/docs/framework-maria_db_jdbc.md
@@ -24,7 +24,7 @@ Tags are printed to standard output by the buildpack detect script
 Users may optionally provide their own MariaDB or MySQL service. A user-provided MariaDB or MySQL service must have a name or tag with `mariadb` or `mysql` in it so that the MariaDB JDBC Framework will automatically download the JDBC driver JAR and place it on the classpath.
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The framework can be configured by modifying the [`config/maria_db_jdbc.yml`][] file in the buildpack fork.  The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
 
diff --git a/docs/framework-new_relic_agent.md b/docs/framework-new_relic_agent.md
@@ -28,7 +28,7 @@ The credential payload of the service may contain the following entries:
 | `***` | (Optional) Any additional entries will be applied as a system property appended to `-Dnewrelic.config.` to allow full configuration of the agent.
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The framework can be configured by modifying the [`config/new_relic_agent.yml`][] file in the buildpack fork.  The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
 
diff --git a/docs/framework-play_framework_auto_reconfiguration.md b/docs/framework-play_framework_auto_reconfiguration.md
@@ -14,7 +14,7 @@ The Play Framework Auto-reconfiguration Framework causes an application to be au
 Tags are printed to standard output by the buildpack detect script
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The framework can be configured by modifying the [`config/play_framework_auto_reconfiguration.yml`][] file in the buildpack fork.  The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
 
diff --git a/docs/framework-play_framework_jpa_plugin.md b/docs/framework-play_framework_jpa_plugin.md
@@ -19,7 +19,7 @@ The Play Framework JPA Plugin Framework causes an application to be automaticall
 Tags are printed to standard output by the buildpack detect script
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The framework can be configured by modifying the [`config/play_framework_jpa_plugin.yml`][] file in the buildpack fork.  The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
 
diff --git a/docs/framework-postgresql_jdbc.md b/docs/framework-postgresql_jdbc.md
@@ -22,7 +22,7 @@ Tags are printed to standard output by the buildpack detect script
 Users may optionally provide their own PostgreSQL service. A user-provided PostgreSQL service must have a name or tag with `postgres` in it so that the PostgreSQL JDBC Framework will automatically download the JDBC driver JAR and place it on the classpath.
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The framework can be configured by modifying the [`config/postgresql_jdbc.yml`][] file in the buildpack fork.  The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
 
diff --git a/docs/framework-spring_auto_reconfiguration.md b/docs/framework-spring_auto_reconfiguration.md
@@ -16,7 +16,7 @@ Tags are printed to standard output by the buildpack detect script
 If a `/WEB-INF/web.xml` file exists, the framework will modify it in addition to making the auto-reconfiguration JAR available on the classpath. This modification consists of adding `org.cloudfoundry.reconfiguration.spring.CloudProfileApplicationContextInitializer`, `org.cloudfoundry.reconfiguration.spring.CloudPropertySourceApplicationContextInitializer`, and `org.cloudfoundry.reconfiguration.spring.CloudAutoReconfigurationApplicationContextInitializer` to the collection of `contextInitializerClasses`. The Spring Auto-reconfiguration Framework also adds the `cloud` profile to any existing Spring profiles such as those defined in the [`SPRING_PROFILES_ACTIVE`][] environment variable.
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The framework can be configured by modifying the [`config/spring_auto_reconfiguration.yml`][] file in the buildpack fork.  The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
 
diff --git a/docs/jre-open_jdk_jre.md b/docs/jre-open_jdk_jre.md
@@ -14,7 +14,7 @@ The OpenJDK JRE provides Java runtimes from the [OpenJDK][] project.  Versions o
 Tags are printed to standard output by the buildpack detect script
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The JRE can be configured by modifying the [`config/open_jdk_jre.yml`][] file in the buildpack fork.  The JRE uses the [`Repository` utility support][repositories] and so it supports the [version syntax][]  defined there.
 
diff --git a/docs/jre-oracle_jre.md b/docs/jre-oracle_jre.md
@@ -23,7 +23,7 @@ Tags are printed to standard output by the buildpack detect script
 For details on the repository structure, see the [repository documentation][repositories].
 
 ## Configuration
-For general information on configuring the buildpack, refer to [Configuration and Extension][].
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
 
 The JRE can be configured by modifying the [`config/oracle_jre.yml`][] file in the buildpack fork.  The JRE uses the [`Repository` utility support][repositories] and so it supports the [version syntax][]  defined there.
 
