Skip to content

Modernize openvox-server install docs into structured section#148

Merged
tuxmea merged 4 commits intoOpenVoxProject:masterfrom
miharp:feat/modernize-openvox-server-install
May 4, 2026
Merged

Modernize openvox-server install docs into structured section#148
tuxmea merged 4 commits intoOpenVoxProject:masterfrom
miharp:feat/modernize-openvox-server-install

Conversation

@miharp
Copy link
Copy Markdown
Contributor

@miharp miharp commented May 4, 2026

Summary

  • Replaces the single outdated install_from_packages page with a proper Installing and upgrading nav section, modeled on the openvox agent docs structure
  • Adds three new pages: install_pre.md (before you begin), install_what_and_where.md (file layout), and upgrade_minor.md (upgrade procedure)
  • Rewrites install_from_packages.markdown with current repo URLs, split apt/yum sections, and a verification step
  • Updates _data/nav/openvox-server_8x.yml to replace the flat install link with a grouped section

Content changes

  • Platform list updated from EOL versions to current supported OS/arch from yum.voxpupuli.org/openvox8 and apt.voxpupuli.org
  • Java requirement corrected to 17 or 21 (verified from CI matrix in openvox-server repo)
  • All puppet.com links replaced with openvox equivalents
  • Removed outdated Java backports/universe repo workarounds

Closes #147

Test plan

  • All four new/updated pages render correctly locally
  • "Installing and upgrading" section appears in the openvox-server sidebar
  • All nav links resolve to the correct pages
  • No broken internal links
  • All new files pass markdownlint

@miharp miharp requested a review from a team as a code owner May 4, 2026 12:41
Replaces the single outdated install_from_packages page with a proper
"Installing and upgrading" nav section modeled on the openvox agent docs.
New pages cover prerequisites (with current platform/arch/Java info),
installation steps split by apt and yum/dnf, file layout, and upgrade
procedure. Removes all puppet.com links and EOL platform references.

Closes OpenVoxProject#147

Signed-off-by: Michael Harp <mike@mikeharp.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@miharp miharp force-pushed the feat/modernize-openvox-server-install branch from 4308a3f to 4472a7c Compare May 4, 2026 12:42
/var/opt/puppetlabs/puppetserver/ does not exist; vardir is
/opt/puppetlabs/server/data/puppetserver/. CA material lives at
/etc/puppetlabs/puppetserver/ca/ (cadir), not ssl/. Add missing
puppetserver-status.log, correct server/bin description, and fix
migration backup path.

Signed-off-by: Michael Harp <mike@mikeharp.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@miharp
Copy link
Copy Markdown
Contributor Author

miharp commented May 4, 2026

Validation notes

Supported OS and architecture

Platform and architecture support was verified directly from the package repository directory trees rather than from documentation:

  • yum packages: browsed https://yum.voxpupuli.org/openvox8/ and crawled each OS family subdirectory (el/, amazon/, fedora/, sles/, redhatfips/) down to the architecture level to confirm which arches are published per version
  • apt packages: checked https://apt.voxpupuli.org/ for supported Debian and Ubuntu codenames
  • Java versions: verified from the CI matrix in the openvox-server repo (.github/workflows/pr-testing.yml), which tests against Java ['17', '21'] only — not 11 as the old page stated

What gets installed and where

Paths were verified against a running OpenVox Server (EL/aarch64) via Vagrant rather than inferred from documentation.

# Check binary and config paths directly
vagrant ssh puppet -c "ls /opt/puppetlabs/bin/puppetserver /opt/puppetlabs/bin/puppet /opt/puppetlabs/server/bin/ ..."

# Check log and runtime dirs with sudo
vagrant ssh puppet -c "sudo ls /etc/puppetlabs/puppetserver/conf.d/ /var/log/puppetlabs/puppetserver/ ..."

# Authoritative path lookup via puppet itself
vagrant ssh puppet -c "sudo /opt/puppetlabs/bin/puppet config print --section server"

Key findings that corrected the initial draft:

  • /var/opt/puppetlabs/puppetserver/ does not exist — the server's vardir is /opt/puppetlabs/server/data/puppetserver/ (confirmed via puppet config print vardir --section server)
  • CA material (ca_crt.pem, ca_crl.pem, signed certs, CSRs) lives at /etc/puppetlabs/puppetserver/ca/ (cadir), not in ssl/
  • ssl/ (ssldir) holds only the server's own node certificate and private key
  • /opt/puppetlabs/server/bin/ contains only puppetdb and puppetserver
  • Three log files present: puppetserver.log, puppetserver-access.log, and puppetserver-status.log
  • Migration backup path corrected to /etc/puppetlabs/ and /opt/puppetlabs/server/data/

Copy link
Copy Markdown
Contributor

@tuxmea tuxmea left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All OpenVox related systems must ensure correct time setting.

Comment thread docs/_openvox-server_8x/install_pre.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Michael Harp <mike@mikeharp.com>
@tuxmea tuxmea enabled auto-merge May 4, 2026 19:16
@tuxmea tuxmea disabled auto-merge May 4, 2026 19:16
@tuxmea tuxmea merged commit 4ad4441 into OpenVoxProject:master May 4, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Modernize openvox-server install_from_packages page

2 participants