(MAINT) add install PE doc (#41)

[skip ci]

README.md

@@ -17,6 +17,9 @@ that help someone acceptance test PE easier with Beaker.
 technical reference for APIs and other aspects of beaker-pe. They describe
 how it works and how to use it but assume that you have a basic understanding
 of key concepts.
+- [How-to guides](docs/how_to) are recipes. They guide you through the steps
+involved in addressing key problems and use-cases. For instance, checkout our
+[How-to Install Puppet Enterprise doc](docs/how_to/install_puppet_enterprise.md).
 
 # Upgrading from 0.y to 1.y?
 

docs/how_to/install_puppet_enterprise.md

@@ -0,0 +1,87 @@
+# How To Install Puppet Enterprise
+
+Welcome to the choose your own adventure of installing Puppet Enterprise (PE)!
+This doc will guide you through the process beaker's DSL helpers use to install
+PE for acceptance testing.
+
+Note that this is not a complete documentation of the process, but a general
+overview. There will be specific hiccups for particular platforms and special
+cases. These are not included at this point. The idea is that as we come upon
+them, we will now have a place to document those details, so that we can
+over time bring this to 100% completeness.
+
+# First Things First: What Do You Want to Install?
+
+PE comes in all varieties. Not only in any number of ever-growing versions, but
+in different install methods & locations as Puppet improves the install methods
+over time.
+
+The first questions to ask yourself are:
+
+1. Are you installing Puppet Agent, or other services?
+1. What version of PE are you installing from?
+
+If you're installing PE 2015.2 or newer and you're installing PE's Puppet Agent,
+then you're on track for our newest agent install strategy, installing from PE's
+promoted agents location. Check our next section for more information on that.
+
+If one (or both) of these conditions don't apply to you, then skip to the next
+section: All Other Installs.
+
+# PE Promoted Agent Installs
+
+Installing Puppet Agent from the PE promoted locations is handled in core beaker,
+not in beaker-pe itself. You can read more about doing this in
+[beaker's How To Install Puppet Doc](https://github.com/puppetlabs/beaker/tree/master/docs/how_to/install_puppet.md).
+
+### Higher-level Install Methods
+
+Below, there's a section on "General Installer Methods." The method in beaker's
+"How To Install Puppet" doc (link above) is the only one specifically for
+installing Puppet Agent from the PE promoted location, but the higher methods
+will call that one if certain conditions are met 
+([conditions doc](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Roles#aio_version%3F-instance_method)).
+
+# All Other Installs
+
+If you need any other services besides an agent, or you're installing from a
+version before 2015.2, you'll end up with our traditional tarball (compressed
+`*.tar.gz` file) installer. These installers are described in the next section.
+
+# Generic Installer Methods
+
+### [`install_pe_on`](http://www.rubydoc.info/github/puppetlabs/beaker-pe/Beaker/DSL/InstallUtils/PEUtils#install_pe_on-instance_method)
+
+This method is a wrapper on our install PE behavior that allows you to pass in
+which hosts in particular you'd like to call, as well as specifying the options
+used yourself.
+
+Note that there are a number of properties needed for installing
+PE and they haven't been all documented, so the general workaround is to pass
+the global options hash (the `options` TestCase accessor is best, you don't have
+to qualify or include anything to get the method, just use the method by name)
+as the `opts` parameter.
+
+Note that this method does the work to figure out `pe_ver` if you don't pass it
+in as an argument. As a last result, beaker-pe will try to put together a URL
+in this form from these beaker global settings:
+
+```ruby
+#{ pe_dir }/${ pe_version_file }
+```
+
+`pe_version_file` is set to `LATEST` by default. This is the file that will tell
+beaker which PE installer in the directory it should install. This file should
+be plain text, and just include the PE version number of the installer to use.
+To check further into how this code works, you'll have to read the code
+
+To see how the filename for the package itself is built, please checkout how the
+`host['dist']` property is built for a particular platform in
+[this code](https://github.com/puppetlabs/beaker-pe/blob/master/lib/beaker-pe/install/pe_utils.rb#L388-L421).
+
+### [`install_pe`](http://www.rubydoc.info/github/puppetlabs/beaker-pe/Beaker/DSL/InstallUtils/PEUtils#install_pe-instance_method)
+
+This method is our generic "install PE on all hosts" convenience method. As a
+matter of fact, it just calls `install_pe_on`, passing the entire `hosts` array
+and the global options hash as the `opts` parameter, just as we suggested in the
+`install_pe_on` documentation above. Please check those docs for more info.