Issue 122 - Puppet ENC via Hiera

README.md

 Adblock Plus infrastructure
 ===========================
 
 The Adblock Plus infrastructure uses [Puppet](http://puppetlabs.com/)
 to set up servers, and to have a realistic development environment.
 
 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 passwords, for example,
+are confidential. In order to allow for such 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
 -----------------------
 
 As with our other projects, all changes to our infrastructure should
 be made in a local development environment, and reviewed before
 deployment. Thanks to Puppet, we can easily set up local VMs that
 mirror our production environment.
 
 The most convenient way to do this is to use Vagrant, as described
@@ skipping 138 matching lines @@
 Monitoring is fully functional in any environment, including development.
 Here, after bootstrapping the `server4` box, one can access the Nagios GUI
 from the host machine via <https://nagiosadmin:nagiosadmin@10.8.0.99/>.
 
 The monitoring service of our production environment, however, is accessible
 via <https://monitoring.adblockplus.org/>.
 Add yourself to _files/nagios-htpasswd_ in the _private_ module used on the
 server, or have someone add you if you don't have access.