Added information on installing Foreman w/ OpenVox by binford2k · Pull Request #534 · voxpupuli/voxpupuli.github.io

binford2k · 2025-08-18T20:20:16Z

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.

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.

openvox/install.md

ekohl

This is a quick review of things that jumped out, but it's late and I may be missing something.

ekohl · 2025-08-26T20:37:16Z

openvox/install.md

+foreman::providers::oauth: false
+```
+Then manually install the `oauth` gem into OpenVox's gempath.
+
+```
+# /opt/puppetlabs/puppet/bin/gem install oauth


This isn't needed anymore now that openvox-agent provides puppet-agent

Suggested change

foreman::providers::oauth: false

```

Then manually install the `oauth` gem into OpenVox's gempath.

```

# /opt/puppetlabs/puppet/bin/gem install oauth

8.18.1 is only a few months old. I don't think we can drop docs for it yet. I'll make a note about this not being needed on current though.

actually, I'm not convinced that what we have is sufficient. I kept getting errors while it was trying to install this package. I'm going to leave it as is until we can confirm that all dependencies are always resolved correctly.

@binford2k do you still see issues? foreman + openvox is working fine for me without manually installing the gem

openvox/install.md

ekohl · 2025-08-26T20:39:14Z

openvox/install.md

+### 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.


Not needed anymore.

Suggested change

First, use your system package manager to remove the `puppet-agent-oauth` package.

ekohl · 2025-08-26T20:42:27Z

openvox/install.md

+puppet::client_package: openvox-agent
+puppet::server_package: openvox-server


These are answers and shouldn't be overridden via Hiera. The real way is to provide them options:

foreman-installer --puppet-client-package openvox-agent --puppet-server-package openvox-server

This also should solve your "caching" issue with the answers.

Hrm. This gets complex when describing how to do something as simple as including the puppetdb plugin. As far as I can tell, there's no CLI options for

puppetdb::puppetdb_package: openvoxdb puppetdb::master::config::terminus_package: openvoxdb-termini

Correct - ideally they would also be updated to add Provides: statements so a dnf install puppetdb-termini will end up installing openvoxdb-termini. Puppet added support for that a long time ago and it also helps migrations.

Then in a new major version we can update theforeman-puppet to become focused on OpenVox so none of this is needed.

those packages now all have proper 'Provides: ` attributes, the hiera keys aren't needed anymore.

ekohl · 2025-08-26T20:43:28Z

openvox/install.md

+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
+```


This is never a good idea. It's a symlink pointing to the real scenario. This deselects the scenario, but that really isn't of any use. Especially if you only have a single scenario available.

Nor is it needed. The scenario file is describing the scenario to be used. The answers file (which you're not using) is

Suggested change

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

```

I'm not convinced this it's enough to specify the CLI parameters. I can validate later, but what happens now is that someone on Debian does

apt install foreman-installer (which pulls in Debian packaged puppet-agent, non-AIO)

configures hiera data (which I believe is roughly equivalent to passing CLI args)

runs the installer

everything breaks because /etc/puppet/<stuff> exists even after the openvox-agent package replaces the system puppet-agent package and foreman-installer continues to use the /etc/puppet directory.

Even after deleting the /etc/puppet directory it still breaks, even with the proper package names. That's what we're trying to address here.

If you follow ☝️ then this is the error you get.

2025-08-26 15:18:35 [ERROR ] [configure] Evaluation Error: Error while evaluating a Virtual Query, Resource type cron doesn't exist (file: /usr/share/foreman-installer/modules/foreman_proxy/manifests/register.pp, line: 38, column: 60) on node debian.overlookinfra.home

I added instructions for resetting the answers file to default. I'd love for there to be a better way.

I'm not convinced this it's enough to specify the CLI parameters. I can validate later, but what happens now is that someone on Debian does

Oh yes, I couldn't quite get it to work with Debian (OpenVoxProject/openvox-agent#21). I as assuming RPM.

apt install foreman-installer (which pulls in Debian packaged puppet-agent, non-AIO)

If you change that to apt install openvox-agent foreman-installer I suspect it does work.

configures hiera data (which I believe is roughly equivalent to passing CLI args)

If you look at https://github.com/theforeman/foreman-installer/blob/develop/config/foreman-hiera.yaml you can see that the answers are a layer. Custom user answers should override those though (custom.yaml ends up being /etc/foreman-installer/custom-hiera.yaml).

everything breaks because /etc/puppet/<stuff> exists even after the openvox-agent package replaces the system puppet-agent package and foreman-installer continues to use the /etc/puppet directory.

Yes, our module supports non-AIO Puppet on Debian so if you install that package then it uses those. Switching between them is painful because so many of those paths end up being stored in the answers file. My recommendation is to start with the right package from the beginning.

If you follow ☝️ then this is the error you get.

2025-08-26 15:18:35 [ERROR ] [configure] Evaluation Error: Error while evaluating a Virtual Query, Resource type cron doesn't exist (file: /usr/share/foreman-installer/modules/foreman_proxy/manifests/register.pp, line: 38, column: 60) on node debian.overlookinfra.home

This is because on Debian the non-AIO puppet-agent package doesn't include the vendored Puppet modules. You need to install puppet-module-puppetlabs-cron-core and friends for that to work. It's awkward and IMHO a packaging bug.

Yes, if you install the proper package to begin with, then it works great. But we can't require perfection from our users! The only way to get from system puppet-agent -> AIO openvox-agent is to start with a fresh answers file or to edit some 500 lines of data and correct each and every legacy path.

ekohl

I missed this part at first, but I really insist we don't merge any instructions to reset the answer file.

My preference is still to add the right metadata to packages to replace the old Puppet packages and then tell users to install the latest version. Then it should really be a drop in replacement. No work needed for users other than to swap the package.

ekohl · 2025-08-27T18:38:44Z

openvox/install.md

+
+<details class="card" >
+<summary class="card-header">Debian Family</summary>
+<pre><code># rm /etc/foreman-installer/scenarios.d/foreman-answers.yaml


Please don't recommend users to do this. It wipes all answers and can break installations. You're better off telling them to reinstall.

tbh, if they're reading this part of the docs, they're already in a broken state.

Also, even with correct metadata, that doesn't fix the fact that foreman-installer still tries to use the incorrect paths in the cached answers file!

@ekohl Came back and poked a little bit this week. It seems now that this is sufficient on redhat flavored machines that don't have the puppet repos enabled.

dnf install https://yum.voxpupuli.org/openvox8-release-el-9.noarch.rpm

dnf install https://yum.theforeman.org/releases/3.16/el9/x86_64/foreman-release.rpm

dnf install foreman-installer

foreman-installer --puppet-client-package openvox-agent --puppet-server-package openvox-server

But it still doesn't seem to correct derived values that get cached in the answers file if you mess up the first time around. What's Foreman's approach to fixing those?

My preference is still to reset the answers file and recreate it. I don't see the possibility of breaking a system being a problem because they've just installed and can just ⬆️ a few times and re-run the installer.

Cautions people about ramifications of removing the answers file and has more instructions about handling critical configuration files.

ekohl · 2025-08-29T15:11:29Z

Today we made progress on the Debian side:

Correct provides statement for Debian packaging OpenVoxProject/openvox-agent#120 & Respect Provides version in Debian control files OpenVoxProject/vanagon#51 add the version number for Provides on Debian. That should help it to properly replace the existing package
@tuxmea found we need to drop the Conflicts on Debian for foreman-installer to accept it as a proper replacement.

bastelfreak · 2025-12-17T20:14:31Z

openvox/install.md

+### 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.


you only need the repo, the packages don't have to be installed yet.

Added information on installing Foreman w/ OpenVox

ee78279

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.

binford2k requested a review from ekohl August 18, 2025 20:20

binford2k commented Aug 18, 2025

View reviewed changes

openvox/install.md Outdated Show resolved Hide resolved

kenyon reviewed Aug 18, 2025

View reviewed changes

openvox/install.md Outdated Show resolved Hide resolved

ekohl requested changes Aug 26, 2025

View reviewed changes

instructions for restoring the answers file to default

2954bae

binford2k force-pushed the foreman_install_updates branch from b4391d8 to 2954bae Compare August 27, 2025 06:17

ekohl requested changes Aug 27, 2025

View reviewed changes

Add more warnings

b79361b

Cautions people about ramifications of removing the answers file and has more instructions about handling critical configuration files.

bastelfreak reviewed Dec 17, 2025

View reviewed changes

		puppet::client_package: openvox-agent
		puppet::server_package: openvox-server

Uh oh!

Conversation

binford2k commented Aug 18, 2025

Uh oh!

Uh oh!

Uh oh!

ekohl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ekohl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ekohl commented Aug 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants