Improve readme

Author: Daniel Dreier

README.md

@@ -3,50 +3,146 @@
 
 100% free range, organic, pesticide free Puppet module for managing Puppet.
 
+#### Table of Contents
 
-## Usage
+1. [Overview](#overview)
+2. [Module Description - What the module does and why it is useful](#module-description)
+3. [Setup - getting started with puppet-puppet](#setup)
+    * [What puppet-puppet affects](#what-puppet-puppet-affects)
+    * [Setup requirements](#setup-requirements)
+4. [Usage - Configuration options and additional functionality](#usage)
+    * [Puppet Master](#puppetmaster-setup)
+    * [Puppet Agent](#puppet-agent-configuration)
+5. [Limitations - OS compatibility, etc.](#limitations)
+6. [Development - Guide for contributing to the module](#development)
+
+## Overview
+
+The puppet-puppet module manages puppet masters and agents using puppet.
+
+## Module Description
+
+Puppet masters are frequently the only hand-crafted part of puppet-managed
+infrastructure. This module seeks to make the experience of running a puppet
+master similar to running Apache, Nginx, or MySQL using puppet.
+
+## Setup
 
+### What puppet-puppet affects
 
-### Puppetmaster
+Depending on how you use this module, it can touch any of:
+* Puppet configuration files
+* Nginx or Apache configurations needed for running a master
+* Unicorn, Passenger, and thin configurations and init scripts
+* PuppetDB and PostgreSQL
+
+As far as possible, this module tries to use other general-purpose modules to
+configure required non-puppet systems.
+
+### Setup Requirements
+
+Puppet-puppet does not manage SSL certificates. You can generate the
+appropriate puppet SSL certificates by starting the webrick-based puppetmaster
+before using puppet-puppet. If you don't generate those SSL certs first, the
+resulting master won't work. (but should if you generate the certs; it's not
+strictly order dependent)
+
+This module also doesn't manage [r10k][r10k-github] or [hiera][hiera-docs].
+Look at [zack/r10k][zack-r10k] or [sharpie/r10k][sharpie-r10k] for r10k, and
+the [hunner/hiera][hunner-hiera] module for managing hiera. If this is all
+unfamiliar, read the [Shit Gary Says](http://garylarizza.com/) blog, starting
+with [Building a Functional Puppet Workflow Part 1: Module Structure][sgs-1].
+
+Don't use the forge release of this module until further notice. It's very
+outdated and has many known problems. Either use r10k to install it, or build
+a puppet module tarball with:
+
+```bash
+git clone https://github.com/puppetlabs-operations/puppet-puppet.git
+cd puppet-puppet
+bundle install
+rake build
+```
+
+The resulting tarball in the `pkg` folder can be installed using something like
+`puppet module install ploperations-puppet-0.12.0.tar.gz` and it will do
+dependency resolution for you. This notice will be removed when the forge
+version of the module is reasonable to use.
+
+## Usage
+There are two general areas managed with this module: masters and agents.
+
+### Puppetmaster Setup
+#### Webrick master
 
 At an absolute minimum, you need the following.
 
-``` Puppet
+```puppet
 class { 'puppet::server':
-  servertype   => 'standalone',
-  manifest     => '/etc/puppet/manifests/site.pp',
-  ca           => true,
+  servertype => 'standalone',
+  manifest   => '/etc/puppet/manifests/site.pp',
+  ca         => true,
 }
 ```
 
 This should get you a puppetmaster running under `webrick` which might scale to
 about `10` nodes if the wind doesn't blow too hard.
 
 If, however, the moon is in the next phase then you probably want to use
-something that scales a bit more.
+something that scales a bit more. Your options are nginx/unicorn,
+apache/passenger, or nginx/thin (but thin support in this module is deprecated
+because nobody seems to be using it).
 
-``` Puppet
+#### Nginx/Unicorn Master
+The most basic setup would look something like:
+```puppet
+class { 'puppet::server':
+  servertype => 'unicorn',
+  ca         => true,
+}
+```
+
+A similar Apache/Passenger server would be:
+```puppet
+class { 'puppet::server':
+  servertype => 'passenger',
+  ca         => true,
+}
+```
+
+#### Master with PuppetDB, PostgreSQL, and reports
+Running a puppet master without PuppetDB loses much of the utility of Puppet,
+so you probably want it. As a convenience, this module will install puppetdb
+and postgresql using the [puppetlabs/puppetdb][puppetlabs-puppetdb] module if
+`manage_puppetdb => true` is set.
+
+If you want a more complex setup with PuppetDB and/or PostgreSQL on a different
+server, don't enable that option; use the 
+[puppetlabs/puppetdb][puppetlabs-puppetdb] module directly because it has many
+more configuration options that aren't exposed here.
+
+```puppet
 class { '::puppet::server':
-  modulepath   => [
-    '$confdir/modules/site',
-    '$confdir/env/$environment/dist',
+  modulepath      => [
+    '$confdir/modules',
+    '$confdir/environments/$environment/modules/site',
+    '$confdir/environments/$environment/modules/site/dist',
   ],
-  storeconfigs => 'puppetdb',
-  reporturl    => "https://${::fqdn}/reports",
-  servertype   => 'unicorn',
-  manifest     => '$confdir/environments/$environment/site.pp',
-  ca           => true,
-  reports      => [
+  manage_puppetdb => true,
+  reporturl       => "https://${::fqdn}/reports",
+  servertype      => 'unicorn',
+  manifest        => '$confdir/environments/$environment/site.pp',
+  ca              => true,
+  reports         => [
     'https',
-    'graphite',
-    'irccat',
     'store',
+    'puppetdb',
   ],
 }
 
 # in a real environment, you'll probably populate parameters on these
 # report classes from hiera. For this example, it's specified inline so that
-# the manifest works as-is
+# the manifest works as-is.
 
 class { 'puppet::reports::graphite':
   server => $::fqdn,
@@ -61,3 +157,68 @@ class { 'puppet::reports::irccat':
 }
 ```
 
+
+### Puppet Agent Configuration
+At the most basic, simply:
+```puppet
+include puppet::agent
+```
+
+That will configure a cron job to run the puppet agent. If that's not what you
+want, one of the following may be more to your liking:
+
+#### Running the agent service instead of via cron
+```puppet
+class { 'puppet::agent':
+  method => 'service',
+}
+```
+
+#### Agent using cron, with more configuration options set:
+Note that although the parameters correspond with puppet configuration file
+option names, only a relatively subset can currently be managed with this
+module.
+
+```puppet
+class { 'puppet::agent':
+  server        => 'puppet.example.com',
+  ca_server     => 'puppetca.example.com',
+  report_server => 'puppet_reports.example.com',
+  method        => 'cron',
+  configtimeout => 900,
+}
+```
+
+In a production environment, you should probably use `include puppet::agent`
+and populate parameters using [hiera automatic parameter lookup][hiera-lookup]
+instead of hardcoding these values into manifests.
+
+## Limitations
+
+This module is (basically) only tested on Debian Wheezy. The maintainers care
+about FreeBSD and OpenBSD support. A token gesture of EL support exists in
+`params.pp` but that's about it; this probably won't do much on CentOS/RedHat.
+Pull requests welcome if you're interested.
+
+Bootstrapping an all-in-one (master, puppetdb, postgresql) puppetmaster with
+puppet-puppet is relatively straightforward. However, building a usable puppet
+infrastructure with it requires additional steps, such as figuring out how you
+want to deploy manifests and modules to your master. (tip: use r10k)
+
+You should definitely not use this module on an existing production
+puppetmaster unless you've tested it extensively. This is a tool developed by
+sysadmins, not developers, and testing is very incomplete.
+
+## Development
+
+Read CONTRIBUTING.md to see instructions on running beaker and rspec tests.
+
+  [puppetlabs-puppetdb]: https://github.com/puppetlabs/puppet-puppetdb
+  [puppetlabs-apache]: https://github.com/puppetlabs/puppetlabs-apache
+  [jfryman-nginx]: https://github.com/jfryman/puppet-nginx
+  [r10k]: https://github.com/adrienthebo/r10k
+  [hiera-lookup]: https://docs.puppetlabs.com/hiera/1/puppet.html#automatic-parameter-lookup
+  [hiera-docs]: https://docs.puppetlabs.com/hiera/1/
+  [zack-r10k]: https://forge.puppetlabs.com/zack/r10k
+  [sharpie-r10k]: https://github.com/Sharpie/puppet-r10k
+  [sgs-1]: http://garylarizza.com/blog/2014/02/17/puppet-workflow-part-1/