Added information on installing Foreman w/ OpenVox

The big trick is that you have to start by installing OpenVox and then
installing the oauth gem. Then the installer just works.

This page is getting a little unwieldy again. We'll need another cleanup
pass on it soon.

Author: binford2k

openvox/install.md

@@ -4,18 +4,21 @@ title: Installing OpenVox
 subsection: openvox
 ---
 
-OpenVox package downloads are currently sponsored by [Overlook InfraTech](https://overlookinfratech.com).
 As of release 8.11, OpenVox is functionally equivalent to Puppet; the command names are the same, the configuration file paths are the same, etc.
 The major differences are in help text output, man pages, and so on.
 This means that you can continue to use all the commands, modules, tooling, etc that you're used to, but at this time *you cannot install both Puppet and OpenVox on the same system*.
 
 > 🔔 Tip: If you want to use Puppet code to manage your systems, if you have strange dependencies, if you're migrating from Puppet Enterprise, or if you have Puppet modules installed as system packages then see the [advanced options](#advanced-options) sections below.
 >
-> * [Alternative Puppet uninstallation options](#alternative-puppet-uninstallation-options)
+> * [Installing Foreman with OpenVox](#installing-foreman-with-openvox)
+>     * [Using the foreman-installer](#using-the-foreman-installer)
+>     * [Using the foreman-foreman module](#using-the-foreman-foreman-module)
+> * [Porting a Foreman infra to OpenVox](#porting-a-foreman-infra-to-openvox)
 > * [Managing OpenVox with OpenVox](#managing-openvox-with-openvox)
 >     * [Managing Repositories](#managing-repositories)
 >     * [Managing the Server/Client](#managing-the-serverclient)
 >     * [Foreman Integration](#foreman-integration)
+> * [Alternative Puppet uninstallation options](#alternative-puppet-uninstallation-options)
 {: class="alert alert-primary callout" }
 
 We encourage you to try out OpenVox on a fresh test system, the way you would for any major system package.
@@ -50,28 +53,62 @@ Then install the packages you want.
 If you have backed up config files, then restore them now.
 
 ### 🎉 That's it! You're done!
-Feel free to read the rest of the page for more options.
+Feel free to read the rest of the page for more options, especially if you're
+also intending to use Foreman.
 
 -----
 
 ## Advanced Options
 
-### Alternative Puppet uninstallation options
+### Installing Foreman with OpenVox
 
-There are some cases in which you might have to take more steps to safely remove legacy Puppet from your system.
+> 🚨 Tip: When using Foreman and OpenVox together, you must install OpenVox first.
+> See [Porting a Foreman infra to OpenVox](#porting-a-foreman-infra-to-openvox) for instructions on how to recover if you started with Foreman.
+{: class="alert alert-warning callout" }
 
-* If you're migrating from Puppet Enterprise you can use the `puppet-enterprise-uninstaller` script on each node as described in [their docs](https://www.puppet.com/docs/pe/latest/uninstalling.html).
-* If you're using distro provided packages, then you might have a bigger job.
-  For example, if you're using Debian packages, you may have several Puppet modules packaged as `.deb` packages that you'll have to move to your `Puppetfile`.
-  You might consider waiting until your distro packages OpenVox.
-    * If you do want to migrate now, then remove any puppet packages and dependencies you have installed using your distro tools.
-        * Debian family
-          * `apt autoremove <packagename>`
-        * RedHat family
-          * `yum autoremove <packagename>`
-    * You might also consider (carefully) cleaning up unused dependencies afterwards by running `apt` or `yum` autoremove without a package name.
+There are two ways to install Foreman: via the `foreman-installer` or via the `theforeman-foreman` module. ***In both cases, you must install OpenVox first***.
 
-You do not need to remove the `[apt|yum].puppet.com` repositories although the only thing you'll be able to use them for going forward is installing historical Puppet releases.
+#### Using the `foreman-installer`
+
+Edit `/etc/foreman-installer/custom-hiera.yaml` to include these Hiera settings.
+If you intend to continue managing your Foreman installation with puppet code, then follow the instructions in the [Managing OpenVox with OpenVox](#managing-openvox-with-openvox) sections to persist these settings into your standard Hiera data files.
+
+``` yaml
+---
+puppet::client_package: openvox-agent
+puppet::server_package: openvox-server
+puppetdb::puppetdb_package: openvoxdb
+puppetdb::master::config::terminus_package: openvoxdb-termini
+foreman::providers::oauth: false
+```
+Then manually install the `oauth` gem into OpenVox's gempath.
+
+```
+# /opt/puppetlabs/puppet/bin/gem install oauth
+```
+
+And finally, use [Foreman's Quickstart Guide](https://theforeman.org/manuals/3.15/quickstart_guide.html) to install Foreman.
+
+#### Using the `foreman-foreman` module
+
+1. Ensure that OpenVox is installed, then follow the instructions in the [Managing OpenVox with OpenVox](#managing-openvox-with-openvox) sections to configure Hiera properly.
+1. Add `theforeman-foreman` to your `Puppetfile` and deploy it.
+1. Use the [documentation](https://github.com/theforeman/puppet-foreman) to classify your server node to your requirements and then run the OpenVox agent to configure everything.
+
+### Porting a Foreman infra to OpenVox
+
+If you're already running Foreman and you want to switch it to be backed by OpenVox then you have a little bit of housekeeping to do first.
+First, use your system package manager to remove the `puppet-agent-oauth` package.
+If you use the `foreman-installer` to manage and upgrade your setup, then ensure that you remove the cached scenario file, or it will continue to use old package names.
+
+```
+# rm /etc/foreman-installer/scenarios.d/last_scenario.yaml
+```
+
+If you're porting from system installed Puppet, then you may have to purge package configuration or remove legacy directory structures.
+Ensure that the `aio_agent_version` fact returns the appropriate version before continuing.
+
+Then follow the [installation instructions](#installing-foreman-with-openvox) above to update your infrastructure.
 
 
 ### Managing OpenVox with OpenVox
@@ -157,6 +194,23 @@ package { 'oauth':
 }
 ```
 
+### Alternative Puppet uninstallation options
+
+There are some cases in which you might have to take more steps to safely remove legacy Puppet from your system.
+
+* If you're migrating from Puppet Enterprise you can use the `puppet-enterprise-uninstaller` script on each node as described in [their docs](https://www.puppet.com/docs/pe/latest/uninstalling.html).
+* If you're using distro provided packages, then you might have a bigger job.
+  For example, if you're using Debian packages, you may have several Puppet modules packaged as `.deb` packages that you'll have to move to your `Puppetfile`.
+  You might consider waiting until your distro packages OpenVox.
+    * If you do want to migrate now, then remove any puppet packages and dependencies you have installed using your distro tools.
+        * Debian family
+          * `apt autoremove <packagename>`
+        * RedHat family
+          * `yum autoremove <packagename>`
+    * You might also consider (carefully) cleaning up unused dependencies afterwards by running `apt` or `yum` autoremove without a package name.
+
+You do not need to remove the `[apt|yum].puppet.com` repositories although the only thing you'll be able to use them for going forward is installing historical Puppet releases.
+
 -----
 
 ## Sponsorship