Merge lp:~mthaddon/juju-deployer/doc-updates into lp:juju-deployer

[Tom Haddon]

Some doc updates trying to clarify inheritance/chaining config files based on internal docs that we've created to expose this info to admins.

=== modified file 'doc/config.rst'
--- doc/config.rst	2013-05-16 03:20:42 +0000
+++ doc/config.rst	2013-10-25 00:50:51 +0000
@@ -1,8 +1,13 @@
 
+About
+=====
+
+Juju-deployer is a tool to deploy complex stacks of charms quickly via a yaml
+or json configuration file.
+
 Configuration
 =============
 
-
 The deployer configuration file can be in either yaml or json
 formats. The contents of the top level are a dictionary/hash mapping
 of stack names to configuration.
@@ -18,7 +23,6 @@
 Services
 ========
 
-
 Snippet::
 
   wordpress-stage:
@@ -34,25 +38,23 @@
                 icon: include-base64://file.ico
  
 
- The service's charm name will be infered from the vcs branch name if
- possible, else it will assume the service name, is the name of the
- charm, or can be specified manually via the charm key.
-
- The service constraints are specified as a single string value
- corresponding to what would be specified on the command line. Valid
- generic constraints for juju-core are mem, cpu-cores, cpu-power.
-
- Service configuration is specified a dictionary of key/value
- mapping. There is support for including data from external
- files with either the include-file://path-to-file or
- include-base64://path-to-file. Relative paths are resolved
- relative to the config file.
-
+The service's charm name will be infered from the vcs branch name if
+possible, else it will assume the service name, is the name of the
+charm, or can be specified manually via the charm key.
+
+The service constraints are specified as a single string value
+corresponding to what would be specified on the command line. Valid
+generic constraints for juju-core are mem, cpu-cores, cpu-power.
+
+Service configuration is specified a dictionary of key/value
+mapping. There is support for including data from external
+files with either the include-file://path-to-file or
+include-base64://path-to-file. Relative paths are resolved
+relative to the config file.
 
 Relations
 =========
 
-
 Relations can be specified in a few different formats.
 
 legacy::
@@ -68,11 +70,24 @@
     relations:
         - [blog, [db, memcached]]
 
-
-Inheritance
-===========
-
-An environment configuration::
+Inheritance or Multiple Configuration Files
+===========================================
+
+There are a number of reasons why you may wish to have separate configuration
+files for a given juju environment you're deploying to. An example is if you
+have a development, staging and production environment with small differences
+(hostnames, constraints, tuning options, etc.) but don't want entirely separate 
+juju deployer config files for each. Another example is if you want to be able 
+to have secrets such as SSL certs in a different config file so you can share 
+the bulk of the config (anything non-secret) with a wider audience without 
+including the secrets.
+
+In this case your options are to separate config files that you pass on the
+command line to juju-deployer::
+ 
+  juju-deployer -c wordpress.cfg -c wordpress-secrets.cfg -s 90 wordpress
+
+Or config inheritance::
 
   wordpress-stage:
     series: precise