Skip to content

Add OpenVox Server 9.x docs collection as a preview (latest stays on 8.x) - #457

Open
miharp wants to merge 1 commit into
OpenVoxProject:masterfrom
miharp:docs/openvox-server9-cutover
Open

Add OpenVox Server 9.x docs collection as a preview (latest stays on 8.x)#457
miharp wants to merge 1 commit into
OpenVoxProject:masterfrom
miharp:docs/openvox-server9-cutover

Conversation

@miharp

@miharp miharp commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Phase 1 of the major-version cutover in MAINTAINING.md for OpenVox Server, following #430 for OpenVox core: docs/_openvox-server_8x copied to docs/_openvox-server_9x, the collection registered in _config.yml, nav_map.yml, navigation.yml, and products.yml, with latest staying on 8.x until 9.0.0 ships. The collection is authored-only, so there is no reference pin and nothing to regenerate. Content reflects the 9.0.0 prerelease series through 9.0.0-beta5.

Part of #456.

What changed beyond the copy

Page Change
9x: index.markdown Title, prerelease notice, Java 21 or 25, openvox-agent 9.x dependency
9x: install_pre.md Platform tables from the shared-actions main platform list (Debian 11/12 and Amazon Linux 2 dropped), Java 21 or 25 with 17 unsupported, note that the package pulls in openvox-agent 9.x, and the DNS step now says agents no longer fall back to the hostname puppet (matches the core 9.x page)
9x: install_from_packages.markdown openvox9-release-* packages (verified present on apt/yum.voxpupuli.org)
9x: services_puppetserver.markdown Java requirement; 9.x/9.x compatibility line with the agent dependency; two intra-product links made relative
9x: dev_running_from_source.markdown Java 21 or 25; Ruby 3.2 for running the source agent
9x: config_file_auth.markdown Note on the 9.0 default auth.conf filebucket rule split (openvox-server#549)
9x: http_file_bucket_file.md Same note from the endpoint side
9x: release_notes.markdown Rewritten for the 9.0.0 beta series (full rewrite; see the GitHub diff view)
9x: http_file_content.md Cross-product links pinned to /openvox/8.x/ now point at /openvox/9.x/
9x: http_file_metadata.md Same
9x: subcommands.markdown Hardcoded /openvox-server/latest/ link made relative
9x: puppet-api/v3/file_content.markdown Same, plus an unclosed heading backtick and a missing sentence period fixed
8x: puppet-api/v3/file_content.markdown The same backtick/period fix on the 8.x page so the two copies stay aligned (the only 8.x change in this PR)

How the content was checked

  • Version-string sweep per the runbook (OpenVox 8, 8.x), reviewed hit by hit.
  • Behavioral check of every breaking change in the beta1 to beta5 release notes against the authored pages (Java 17 dropped / 25 added, Jetty 12, JRuby 10, pe_serverversion removed, Debian 11/12 and Amazon Linux 2 packages dropped, agent 9 dependency, filebucket read authorization, gettext gem, CA bundle fallback). Only the items in the table needed page changes.
  • Diffed the shipped config templates (ezbake/config/conf.d/*.conf) between 8.15.2 and 9.0.0-beta5: the only change is the auth.conf filebucket rule split, so the configuration reference pages are otherwise unchanged.
  • certificate-status / client-whitelist still exist in 9, so the deprecated-features page is unchanged. Known issues are not version-specific and are unchanged.
  • Java 21 or 25 comes from openvox-server#336 (JDK 17 now logs as unsupported) and Clean up markdown lint violations in OpenBolt docs #343; the platform list is the main series in _data/supported_platforms.yml.
  • jekyll build, rake test:products_data, markdownlint on the new collection, and htmlproofer over _site/openvox-server/9.x: the only failures are the generated OpenVox reference pages that are gitignored locally (the usual local false positive; CI generates them).
  • Visual review of every changed page on a local build (screenshots below): the version selector on server pages lists 9.x and 8.x (latest) from both sides, the top bar marks OpenVox Server active on 9.x pages, and the out-of-date banner does not render on the 9.x preview.

Screenshots

01-server9-index 02-install-pre-full 03-install-from-packages 04-release-notes-full 05-auth-conf-filebucket-note 06-file-bucket-file-note 07-services-overview 08-running-from-source-prereqs 09-server8-index-selector

Diffs for the small edits

diff against the 8.x source
--- a/index.markdown
+++ b/index.markdown
@@ -1,8 +1,11 @@
 ---
 layout: default
-title: "OpenVox Server 8"
+title: "OpenVox Server 9"
 ---
 
+> **OpenVox Server 9 is in prerelease.** See the [release notes](release_notes.html) for
+> the current build and expect breaking changes before the stable 9.0.0 release.
+
 OpenVox Server is the primary server component in an OpenVox agent/server deployment.
 It compiles configuration catalogs for managed nodes, serves files, manages certificates,
 and receives reports from agents.
@@ -22,7 +25,7 @@ For a full description of the service and its internal components, see
 
 | Package | Contents |
 | ------- | -------- |
-| `openvox-server` | JVM-based catalog server; depends on `openvox-agent`. Requires Java 17 or 21 (not bundled). |
+| `openvox-server` | JVM-based catalog server; depends on `openvox-agent` 9.x. Requires Java 21 or 25 (not bundled). |
 
 ## Getting started
 
--- a/install_pre.md
+++ b/install_pre.md
@@ -17,26 +17,32 @@ Before installing OpenVox Server:
 
    | Distribution | Versions |
    | ------------ | -------- |
-   | Debian | 10, 11, 12, 13 |
-   | Ubuntu | 18.04, 20.04, 22.04, 24.04, 25.04, 26.04 |
+   | Debian | 13 |
+   | Ubuntu | 22.04, 24.04, 26.04 |
 
    **yum/dnf-based systems:**
 
    | Distribution | Versions | Architectures |
    | ------------ | -------- | ------------- |
-   | EL (RHEL, AlmaLinux, Rocky Linux, CentOS) | 7 | x86_64 |
-   | EL (RHEL, AlmaLinux, Rocky Linux, CentOS) | 8, 9 | x86_64, aarch64, ppc64le |
-   | EL (RHEL, AlmaLinux, Rocky Linux, CentOS) | 10 | x86_64, aarch64 |
-   | Amazon Linux | 2, 2023 | x86_64, aarch64 |
-   | Fedora | 36, 40, 41, 42, 43 | x86_64, aarch64 |
-   | SLES | 15, 16 | x86_64, aarch64 |
-   | RHEL FIPS | 8, 9 | x86_64, aarch64 |
+   | EL (RHEL, AlmaLinux, Rocky Linux, CentOS) | 8, 9, 10 | x86_64, aarch64 |
+   | Amazon Linux | 2023 | x86_64, aarch64 |
+   | Fedora | 43, 44 | x86_64, aarch64 |
+   | SLES | 15 | x86_64 |
+   | SLES | 16 | x86_64, aarch64 |
+   | RHEL FIPS | 8, 9 | x86_64 |
+
+   OpenVox Server 9 no longer ships packages for Debian 11 and 12 (they only provide
+   Java 17) or for Amazon Linux 2. For the list the build system works from, see
+   [Supported platforms](/openvox/latest/supported_platforms.html).
 
 2. Verify your Java version.
 
-   OpenVox Server requires Java 17 or 21. Install a supported JDK from your
-   distribution's repositories before installing the OpenVox Server package. OpenVox
-   Server does not bundle a JDK.
+   OpenVox Server 9 requires Java 21 or 25; Java 17 is no longer supported. Install a
+   supported JDK from your distribution's repositories before installing the OpenVox
+   Server package. OpenVox Server does not bundle a JDK.
+
+   The `openvox-server` 9.x package depends on `openvox-agent` 9.x, so the package
+   manager installs or upgrades the agent on the server host along with it.
 
 3. Plan memory allocation.
 
@@ -52,9 +58,10 @@ Before installing OpenVox Server:
 
 5. Verify DNS.
 
-   By default, agents look for the server at the hostname `puppet`. Make sure that
-   name resolves correctly on the network, or plan to set the `server` setting in
-   `puppet.conf` on each agent explicitly.
+   Starting in OpenVox 9, agents no longer fall back to the hostname `puppet` by
+   default, so plan to set the `server` setting in `puppet.conf` on each agent
+   explicitly. Forward and reverse DNS should be correct for the server and every
+   node.
 
 6. Synchronize clocks.
 
--- a/install_from_packages.markdown
+++ b/install_from_packages.markdown
@@ -21,8 +21,8 @@ platform is supported, your Java version is correct, and port 8140 is open.
    [apt.voxpupuli.org](https://apt.voxpupuli.org). For example, on Ubuntu 22.04:
 
    ```bash
-   wget https://apt.voxpupuli.org/openvox8-release-ubuntu22.04.deb
-   sudo dpkg -i openvox8-release-ubuntu22.04.deb
+   wget https://apt.voxpupuli.org/openvox9-release-ubuntu22.04.deb
+   sudo dpkg -i openvox9-release-ubuntu22.04.deb
    sudo apt update
    ```
 
@@ -30,7 +30,7 @@ platform is supported, your Java version is correct, and port 8140 is open.
    [yum.voxpupuli.org](https://yum.voxpupuli.org). For example, on EL 9:
 
    ```bash
-   sudo rpm -Uvh https://yum.voxpupuli.org/openvox8-release-el-9.noarch.rpm
+   sudo rpm -Uvh https://yum.voxpupuli.org/openvox9-release-el-9.noarch.rpm
    ```
 
    For the full list of supported distributions and release packages, see the
--- a/services_puppetserver.markdown
+++ b/services_puppetserver.markdown
@@ -17,9 +17,10 @@ This page describes the run environment and architecture of OpenVox Server. For
 OpenVox Server packages are available for Debian, Ubuntu, Red Hat Enterprise Linux and its derivatives, Amazon Linux, Fedora, SLES, and RHEL FIPS.
 For the full list of supported distributions, versions, and architectures, see [Before you begin](./install_pre.html).
 
-OpenVox Server requires Java 17 or 21. It does not bundle a JDK; install one from your distribution's repositories before installing OpenVox Server.
+OpenVox Server requires Java 21 or 25. It does not bundle a JDK; install one from your distribution's repositories before installing OpenVox Server.
 
-OpenVox Server releases are versioned separately from OpenVox (the agent). Major versions are aligned: OpenVox Server 8.x is compatible with OpenVox 8.x.
+OpenVox Server releases are versioned separately from OpenVox (the agent). Major versions are aligned: OpenVox Server 9.x is compatible with OpenVox 9.x, and the
+`openvox-server` 9.x package depends on `openvox-agent` 9.x on the same host.
 
 ## Controlling the Service
 
@@ -48,7 +49,7 @@ The web server's settings can be modified in [`webserver.conf`](./config_file_we
 
 ### OpenVox API Service
 
-OpenVox Server includes a service that handles agent configuration requests. See [OpenVox HTTP API](/openvox-server/latest/http_api_index.html) for documentation on the core APIs.
+OpenVox Server includes a service that handles agent configuration requests. See [OpenVox HTTP API](./http_api_index.html) for documentation on the core APIs.
 
 For OpenVox Server-specific APIs hosted by this service, see:
 
@@ -63,7 +64,7 @@ OpenVox Server includes a certificate authority (CA) service that:
 - Serves certificates and a certificate revocation list (CRL) to nodes
 - Optionally accepts commands to sign or revoke certificates (disabled by default)
 
-The relevant endpoints are `certificate`, `certificate_request`, `certificate_revocation_list`, and `certificate_status`. See [CA HTTP API](/openvox-server/latest/http_api_index.html#ca-v1-http-api) for details.
+The relevant endpoints are `certificate`, `certificate_request`, `certificate_revocation_list`, and `certificate_status`. See [CA HTTP API](./http_api_index.html#ca-v1-http-api) for details.
 
 Signing and revoking certificates over the network is disallowed by default. You can use [`auth.conf`](./config_file_auth.html) to allow specific certificate owners to issue commands.
 
--- a/dev_running_from_source.markdown
+++ b/dev_running_from_source.markdown
@@ -54,10 +54,10 @@ More detailed instructions follow.
 
 Use your system's package tools to ensure that the following prerequisites are installed:
 
-- Java 17 or 21
+- Java 21 or 25
 - [Leiningen 2.12.0 or later](http://leiningen.org/)
 - Git (for checking out the source code)
-- Ruby 3.1 or later -- only needed to run a Puppet Agent from source on the host (the source agent is run through Bundler, which isolates it from any Puppet gems in your Ruby). You can skip this if you
+- Ruby 3.2 or later -- only needed to run a Puppet Agent from source on the host (the source agent is run through Bundler, which isolates it from any Puppet gems in your Ruby). You can skip this if you
   [run the agent in a Docker container](#running-the-agent-inside-a-docker-container) instead.
 
 ## Step 2: Clone Git Repo and Set Up Working Tree
--- a/config_file_auth.markdown
+++ b/config_file_auth.markdown
@@ -18,6 +18,14 @@ To configure how OpenVox Server authenticates requests, use the supported HOCON
 
 You can find the OpenVox Server auth.conf file [here](https://github.com/openvoxproject/openvox-server/blob/master/ezbake/config/conf.d/auth.conf).
 
+> **Note:** Starting with OpenVox Server 9.0, the default `auth.conf` splits the
+> `/puppet/v3/file_bucket_file` rule by HTTP method. Agents keep `head` and `put`, which
+> is all they need to back files up. Reading content back out with `get` or `post` now
+> requires a client certificate with the `pp_cli_auth: "true"` extension, the same
+> extension that gates the CA administrative endpoints. If you restore or diff filebucket
+> content remotely with an ordinary agent certificate, add a rule for that certname rather
+> than widening the shipped rule.
+
 ## HOCON example
 
 Here is an example authorization section using the HOCON configuration format:
--- a/http_file_bucket_file.md
+++ b/http_file_bucket_file.md
@@ -11,6 +11,11 @@ path of the file on the client system. This is usually optional and used as an e
 file is retrieved. The environment is required in all requests but ignored, as the file bucket does not distinguish
 between environments.
 
+> **Note:** In OpenVox Server 9.0 and later, the default `auth.conf` lets every
+> authenticated agent use `HEAD` and `PUT` on this endpoint, but `GET` and `POST` (reading
+> content back out) require a client certificate with the `pp_cli_auth: "true"` extension.
+> See [auth.conf](./config_file_auth.html).
+
 ## Find
 
 Retrieve the contents of a file.
--- a/http_file_content.md
+++ b/http_file_content.md
@@ -16,15 +16,15 @@ Get a file.
 The endpoint path includes a `:mount_point` which can be one of the following types:
 
 - Custom file serving mounts as specified in `fileserver.conf` — see
-  [configuring mount points](/openvox/8.x/config_file_fileserver.html).
+  [configuring mount points](/openvox/9.x/config_file_fileserver.html).
 - `modules/<MODULE>` — allows access to the `files` subdirectory of `<MODULE>` — see
-  [file serving](/openvox/8.x/file_serving.html).
+  [file serving](/openvox/9.x/file_serving.html).
 - `plugins` — merges the `lib` directory of every module together. Used for syncing plugins; not intended for
   general consumption. Per-module sub-paths cannot be specified.
 - `pluginfacts` — merges the `facts.d` directory of every module together. Used for syncing external facts; not
   intended for general consumption. Per-module sub-paths cannot be specified.
 - `tasks/<MODULE>` — allows access to files in the `tasks` subdirectory of `<MODULE>` — see
-  [file serving](/openvox/8.x/file_serving.html).
+  [file serving](/openvox/9.x/file_serving.html).
 
 `:name` is the path to the file within the `:mount_point` that is requested.
 
--- a/subcommands.markdown
+++ b/subcommands.markdown
@@ -51,7 +51,7 @@ Because these commands are shipped as a gem alongside Puppet Server, it can be u
 
 **Note:** These commands are available in Puppet 5, but in order to use them, you must update Puppet Server’s `auth.conf` to include a rule allowing the master’s certname to access the `certificate_status` and
 `certificate_statuses` endpoints. The same applies to upgrading in open source Puppet: if you're upgrading from Puppet 5 to Puppet 6 and are not regenerating your CA, you must whitelist the master’s certname.
-See [Puppet Server Configuration Files: auth.conf](/openvox-server/latest/config_file_auth.html) for details on how to use `auth.conf`.
+See [Puppet Server Configuration Files: auth.conf](./config_file_auth.html) for details on how to use `auth.conf`.
 
 Example:
 
--- a/puppet-api/v3/file_content.markdown
+++ b/puppet-api/v3/file_content.markdown
@@ -7,7 +7,7 @@ The `file_content` endpoint returns contents of the specified file.
 
 ## `GET /puppet/v3/file_content/:mount_point/:module/:file-path?environment=:environment`
 
-When specifying environment see the [OpenVox API docs](/openvox-server/latest/http_file_content.html).
+When specifying environment see the [OpenVox API docs](../../http_file_content.html).
 
 ## `GET /puppet/v3/file_content/:mount_point/:module/:file-path?project=:project-ref`
 

Follow-ups

  • The 8 to 9 upgrade guide for OpenVox core (separate PR) should get a server section or cross-link once it lands; upgrade_minor.md here is unchanged.

@miharp
miharp requested a review from a team as a code owner August 27, 2026 12:32
@miharp
miharp force-pushed the docs/openvox-server9-cutover branch from 4d014a1 to 6afdf23 Compare August 27, 2026 13:37
miharp added a commit to miharp/openvox-docs that referenced this pull request Aug 27, 2026
Add an upgrade-planning page to the 9.x collection covering what to
review before moving a production deployment from OpenVox 8 to 9,
alongside the existing package-mechanics page (upgrade_minor):

- Component version table: Ruby 3.2 -> 4.0, OpenSSL 3.0 -> 3.5,
  OpenFact 5.x -> 6.x, JRuby 9.4 -> 10.1, Java 21/25 (17 dropped)
- Ruby 4.0 review guidance for custom facts, functions, types,
  providers, and agent/server-installed gems
- Behavior changes verified against the 9.0.0 prerelease sources:
  deferred functions preprocessed by default again (openvox#462),
  reports default store -> none (openvox#583), and the server
  setting fallback deprecation (openvox#536 - root agents still
  fall back with a warning, non-root runs fail; the code keeps the
  root fallback in beta2, so the page documents the deprecation
  rather than a hard removal)
- Removed settings (configprint, pluginsync, data_binding_terminus,
  environment_data_provider) and other removals (regsubst encoding
  argument, pe_serverversion fact, zone_core module, Java keystores,
  legacy PAL APIs)
- Server/OpenVoxDB notes: Java 17 dropped, Jetty 12, OpenVoxDB
  Debian 11/12 packages discontinued, openvox-server 9 requires
  openvox-agent 9 on the same host
- Test-then-upgrade checklist and upgrade order

Also add the nav entry and cross-link the page from the breaking-
changes callout in upgrade_minor.

Updated after the server, OpenVoxDB, and OpenFact 6 preview cutovers
(OpenVoxProject#457, OpenVoxProject#458, OpenVoxProject#459): per-component release-notes links, OpenVox Server 9
also dropping Debian 11/12 and Amazon Linux 2, the OpenVox Server 9
filebucket read-authorization change (openvox-server#549), the OpenVoxDB
bootstrap.cfg jetty10-service pitfall for upgrades from 8.14.0 or
earlier, the PostgreSQL 14 minimum, and the concrete OpenFact 6 changes
that affect fact code.

Part of OpenVoxProject#456

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Michael Harp <mike@mikeharp.com>
…8.x)

Phase 1 of the major-version cutover in MAINTAINING.md for OpenVox Server:
copy docs/_openvox-server_8x to docs/_openvox-server_9x, register the
collection, nav map, product bar entry, and products.yml version (no
reference pin; the collection is authored-only), and leave `latest` on
8.x until 9.0.0 ships.

Authored content updated for the 9.0.0 prerelease series (beta1 to beta5):

- index: title, prerelease notice, Java 21 or 25, openvox-agent 9.x
  dependency
- install_pre: platform tables from the shared-actions main platform list
  (Debian 11/12 and Amazon Linux 2 dropped), Java 21 or 25 with 17
  unsupported, note that the package pulls in openvox-agent 9.x
- install_from_packages: openvox9 release packages
- services_puppetserver: Java requirement and 9.x/9.x compatibility line
- dev_running_from_source: Java 21 or 25, Ruby 3.2 for the source agent
- config_file_auth and http_file_bucket_file: the 9.0 default auth.conf
  restricts filebucket GET/POST to pp_cli_auth certificates
  (openvox-server#549)
- release_notes: rewritten for the 9.0.0 beta series
- API pages that pinned /openvox/8.x/ now point at /openvox/9.x/, and the
  four hardcoded /openvox-server/latest/ links are relative so the frozen
  copy stays internally coherent

Also, from the visual review: install_pre's DNS step now reflects the
OpenVox 9 change that agents no longer fall back to the hostname
`puppet` (matching the core 9.x page), and the puppet-api/v3/file_content
page gets its unclosed heading backtick and missing sentence period fixed
in both 8.x and 9.x.

Config templates shipped in 8.15.2 and 9.0.0-beta5 differ only in the
auth.conf filebucket rules, so the configuration pages are otherwise
unchanged. Known issues and deprecated features are unchanged: the
certificate-status settings still exist in 9.

Part of OpenVoxProject#456

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Michael Harp <mike@mikeharp.com>
@miharp
miharp force-pushed the docs/openvox-server9-cutover branch from 6afdf23 to 464a6cb Compare August 27, 2026 21:53
miharp added a commit to miharp/openvox-docs that referenced this pull request Aug 27, 2026
Add an upgrade-planning page to the 9.x collection covering what to
review before moving a production deployment from OpenVox 8 to 9,
alongside the existing package-mechanics page (upgrade_minor):

- Component version table: Ruby 3.2 -> 4.0, OpenSSL 3.0 -> 3.5,
  OpenFact 5.x -> 6.x, JRuby 9.4 -> 10.1, Java 21/25 (17 dropped)
- Ruby 4.0 review guidance for custom facts, functions, types,
  providers, and agent/server-installed gems
- Behavior changes verified against the 9.0.0 prerelease sources:
  deferred functions preprocessed by default again (openvox#462),
  reports default store -> none (openvox#583), and the server
  setting fallback deprecation (openvox#536 - root agents still
  fall back with a warning, non-root runs fail; the code keeps the
  root fallback in beta2, so the page documents the deprecation
  rather than a hard removal)
- Removed settings (configprint, pluginsync, data_binding_terminus,
  environment_data_provider) and other removals (regsubst encoding
  argument, pe_serverversion fact, zone_core module, Java keystores,
  legacy PAL APIs)
- Server/OpenVoxDB notes: Java 17 dropped, Jetty 12, OpenVoxDB
  Debian 11/12 packages discontinued, openvox-server 9 requires
  openvox-agent 9 on the same host
- Test-then-upgrade checklist and upgrade order

Also add the nav entry and cross-link the page from the breaking-
changes callout in upgrade_minor.

Updated after the server, OpenVoxDB, and OpenFact 6 preview cutovers
(OpenVoxProject#457, OpenVoxProject#458, OpenVoxProject#459): per-component release-notes links, OpenVox Server 9
also dropping Debian 11/12 and Amazon Linux 2, the OpenVox Server 9
filebucket read-authorization change (openvox-server#549), the OpenVoxDB
bootstrap.cfg jetty10-service pitfall for upgrades from 8.14.0 or
earlier, the PostgreSQL 14 minimum, and the concrete OpenFact 6 changes
that affect fact code.

Part of OpenVoxProject#456

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Michael Harp <mike@mikeharp.com>
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.

1 participant