Issue 122 - Puppet ENC via Hiera

README.md

Index: README.md
===================================================================
--- a/README.md
+++ b/README.md
@@ -6,17 +6,46 @@
 
 Our Puppet manifests are only tested with Ubuntu 12.04 right now.
 
-Private files
--------------
+Host specific setup
+-------------------
 
-Some parts of our infrastructure are, obviously, confidential. We have
-htpasswd files, SSH keys and SSL certificates that we need to be
-careful with.
+Some infrastructure parts are specific to the environment (such as e.g.
+*development*, *test* and *production*), whilst others are confidential.

[Wladimir Palant, 2014/11/17 16:43:36]

Explicitly mention passwords as example of "confidential"? This leaves quite a
bit room for interpretation otherwise, we don't want the impression that we are
hiding something here (yes, I know that we sort of explain it below already).

[mathias, 2014/11/27 00:30:18]

Done.

+In order to allow for specific configuration, the repository requires a
+set of manual operations during the initial setup:
 
-That's why _modules/private_ is missing, and needs to be placed there
-manually. We provide stub versions of all those files in
-_modules/private-stub_, so just linking or copying that to
-_modules/private_ will make everything work locally.
+### `modules/private`
+
+The `private` module is destined to store confidential information such as
+[RSA](http://en.wikipedia.org/wiki/RSA_%28cryptosystem%29) keys, `htpasswd`
+files and so on. The repository provides a `private-stub` module containing
+defaults suitable for development and testing purpose. One can create a
+symbolic link to start using the resource:
+
+    # UNIX-oid
+    user@host:~/infrastructure$ ln -s private-stub modules/private
+
+    # Windows
+    C:\infrastructure\> MKLINK /D modules\private private-stub
+
+When creating a custom version, one may inspect the `modules/private-stub`
+directory to determine which resources have to be provided.
+
+### `hiera/environment`
+
+[Hiera](https://docs.puppetlabs.com/hiera/1/) configuration files specific
+to the current environment are expected to be found in `hiera/environment`.
+Default resources for development (and testing) purpose are provided within
+`hiera/development`:
+
+    # UNIX-oid
+    user@host:~/infrastructure$ ln -s development hiera/environment
+
+    # Windows
+    C:\infrastructure\> MKLINK /D hiera\environment development
+
+Note that custom versions are recommended to be tracked together with the
+custom `private` module, if any.
 
 Development environment
 -----------------------