Skip to content

Add OpenVoxDB 9.x docs collection as a preview (latest stays on 8.x) - #458

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

Add OpenVoxDB 9.x docs collection as a preview (latest stays on 8.x)#458
miharp wants to merge 1 commit into
OpenVoxProject:masterfrom
miharp:docs/openvoxdb9-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 OpenVoxDB, following #430 (core) and #457 (server): docs/_openvoxdb_8x copied to docs/_openvoxdb_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. Content reflects 9.0.0-beta1, the only 9.x tag so far.

Part of #456. Merge after #457: the 9.x release notes link to /openvox-server/9.x/release_notes.html, which #457 adds.

What changed beyond the copy

Page Change
index.md Prerelease notice and version note; Java 21 or 25 (17 dropped); platform list from the shared-actions main platform list (Debian 11/12 dropped); OpenJDK 21/25 for custom installs; "OpenVox Server" naming in the server requirement plus the openvoxdb-termini dependency (openvox-agent >= 8.26.2, no upper bound in beta1); PostgreSQL 14 minimum
puppetdb-faq.markdown Supported JDK versions
install_from_source.markdown JDK 21
configure.markdown The [jetty] note names Jetty 12
release_notes.markdown Rewritten for the 9.0.0 prerelease series (full rewrite; see the GitHub diff view), including the bootstrap.cfg jetty10-service pitfall for upgrades from 8.14.0 or earlier

How the content was checked

  • Version-string sweep per the runbook (OpenVoxDB 8, 8.x), reviewed hit by hit. The one remaining hit (api/query/v4/query.markdown, an issue with 8.1.0) is historical and stays.
  • Behavioral check of the 9.0.0-beta1 breaking changes and fixes against the authored pages: Jetty 12 (openvoxdb#208), Java 17 dropped / 25 added (Replace the four nav-linked quick start guides with one modern Forge-module example #294, [Feature request]: provide our logo as favicon #291), Debian 11/12 packages dropped (docs: credit OpenVox and Vox Pupuli in the copyright notices #297), ssl-setup no longer using --configprint (update social share card #400), Jolokia 2.x config (discourage unbounded resource collectors #334).
  • Diffed the shipped config templates (resources/ext/config/**, ezbake.conf) between 8.15.0 and 9.0.0-beta1: identical apart from the packaging dependency (openvox-agent >= 8.28.1, < 9.0.0~ in 8.15.0 versus >= 8.26.2 with no upper bound in beta1), so the configuration pages are otherwise unchanged. The missing upper bound looks like a beta1 artifact (the build branched from 8.13.0); the docs state what ships, and it is worth re-checking at the next 9.x tag.
  • PostgreSQL minimum taken from oldest-supported-db in src/puppetlabs/puppetdb/scf/storage.clj (14.0 in both 8.15.0 and beta1). The 8.x page still says 11, which is already wrong for 8.x; left for a separate 8.x fix rather than widening this PR.
  • Java 21 or 25 comes from openvoxdb#294/docs: credit OpenVox and Vox Pupuli in the copyright notices #297 (the same requirement as openvox-server 9); 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/openvoxdb/9.x: apart from the locally-absent generated OpenVox reference pages, the only failure is the link to the server 9.x release notes noted above.
  • Visual review of every changed page on a local build (screenshots below): the version selector on OpenVoxDB pages lists 9.x and 8.x (latest), and the out-of-date banner does not render on the 9.x preview.

Screenshots

01-db9-overview-full 02-db9-system-requirements 03-db9-release-notes 04-db9-faq-java 05-db8-overview-selector

Diffs for the small edits

diff against the 8.x source
--- a/index.md
+++ b/index.md
@@ -5,6 +5,9 @@ layout: default
 
 # Overview and requirements
 
+> **OpenVoxDB 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.
+
 [exported]: /openvox/latest/lang_exported.html
 [connect]: ./connect_puppet_server.html
 [apply]: ./connect_puppet_apply.html
@@ -39,8 +42,9 @@ To start using OpenVoxDB today:
 
 ## Version note
 
-This documentation covers OpenVoxDB 8, which adds several new features and
-contains some breaking changes since OpenVoxDB 7.
+This documentation covers OpenVoxDB 9, which contains breaking changes since
+OpenVoxDB 8: Java 21 or 25 is required, and packages are no longer built for
+Debian 11 and 12.
 
 [See the release notes][releasenotes] for information on all
 changes.
@@ -66,9 +70,9 @@ through OpenVoxDB's query APIs (see the navigation sidebar for details).
 
 ## System requirements
 
-### \*nix server with JVM 11+
+### \*nix server with JVM 21+
 
-Java 17 is recommended, but Java 11 is supported as well.
+OpenVoxDB 9 requires Java 21 or 25. Java 17 and earlier are no longer supported.
 
 #### Standard install: RHEL, CentOS, Debian, and Ubuntu
 
@@ -76,10 +80,16 @@ Puppet provides OpenVoxDB packages and a module which simplify the
 setup of its SSL certificates and init scripts. The packages are
 available for the following operating systems:
 
-* Red Hat Enterprise Linux 7, 8, and 9
-* SUSE Enterprise Linux 12, 15
-* Debian 10 (Buster), and 11 (Bullseye)
-* Ubuntu 18.04 (Bionic) LTS, 20.04 (Focal), 22.04 (Jammy) LTS
+* Red Hat Enterprise Linux 8, 9, and 10 (and derivatives such as AlmaLinux and Rocky Linux)
+* Amazon Linux 2023
+* Fedora 43 and 44
+* SUSE Linux Enterprise Server 15 and 16
+* Debian 13
+* Ubuntu 22.04, 24.04, and 26.04
+
+OpenVoxDB 9 no longer ships packages for Debian 11 and 12 (they only provide Java 17).
+For the list the build system works from, see
+[Supported platforms](/openvox/latest/supported_platforms.html).
 
 
 [See here for instructions for installing via the OpenVoxDB module.][install_via_module]
@@ -89,28 +99,26 @@ available for the following operating systems:
 #### Custom install: Any Unix-like OS
 
 If you're willing to do some manual configuration, OpenVoxDB can run on
-any Unix-like OS with JVM 11 or newer, including:
+any Unix-like OS with JVM 21 or newer, including:
 
 * Recent MacOS X versions (using built-in support)
-* Nearly any Linux distribution using OpenJDK 11 or Oracle JDK 11
-* Nearly any \*nix distribution using OpenJDK 11 or Oracle JDK 11
+* Nearly any Linux distribution using OpenJDK 21 or 25
+* Nearly any \*nix distribution using OpenJDK 21 or 25
 
 [See here for advanced installation instructions.][install_advanced]
 
-### Puppet 8.0.0
+### OpenVox Server 8.0.0
 
-Your site's Puppet Server must be running Puppet Server 8.0.0 or later.
-[You will need to connect your Puppet Servers to OpenVoxDB after installing it][connect].
+Your site's OpenVox Server must be running OpenVox Server 8.0.0 or later.
+[You will need to connect your OpenVox Servers to OpenVoxDB after installing it][connect].
 If you wish to use OpenVoxDB with
 [standalone nodes that are running puppet apply][apply], every node
-must be running 8.0.0 or later.
+must be running 8.0.0 or later. The `openvoxdb-termini` 9.x package depends on
+`openvox-agent` 8.26.2 or later on the host where it is installed.
 
 ### PostgreSQL 14
 
-OpenVoxDB 8 recommends PostgreSQL 14 or later in order to take advantage of new
-features in PostgreSQL.
-
-OpenVoxDB requires PostgreSQL 11 or later. If not provided by your
+OpenVoxDB 9 requires PostgreSQL 14 or later. If not provided by your
 distribution, compatible versions of Postgres can be installed from the PGDG
 (PostgreSQL Global Development Group) repositories. See
 [apt.postgresql.org][apt_pgdg] or [yum.postgresql.org][yum_pgdg] for more
--- a/puppetdb-faq.markdown
+++ b/puppetdb-faq.markdown
@@ -51,8 +51,8 @@ our team's previous experience with the language.
 
 ## Which versions of Java are supported?
 
-JDK 11 and 17 are officially supported. JDK 17 is recommended if it is
-available on your platform. Other versions may work, and issues will be
+JDK 21 and 25 are officially supported; JDK 17 and earlier are not supported
+by OpenVoxDB 9. Other versions may work, and issues will be
 addressed on a best-effort basis, but support is not guaranteed.
 
 ## Which databases are supported?
--- a/install_from_source.markdown
+++ b/install_from_source.markdown
@@ -24,7 +24,7 @@ Use your system's package tools to ensure that the following prerequisites are i
 
 - (Optional) OpenVox Server 8.x or newer
 - A working OpenVox agent or server setup (for ssl-setup to succeed)
-- JDK 17 or newer
+- JDK 21 or newer
 - [Leiningen][]
 - Git (for checking out the source code)
 
--- a/configure.markdown
+++ b/configure.markdown
@@ -704,7 +704,7 @@ Sets the maximum number of threads assigned to responding to HTTP
 and HTTPS requests, effectively changing how many concurrent requests
 can be made at one time. Defaults to 50.
 
-> **Note:** Due to the behaviour of our web server (Jetty 10), this setting
+> **Note:** Due to the behaviour of our web server (Jetty 12), this setting
     must be higher then the number of CPUs on your system or it will
     stop processing any HTTP requests.
 

Follow-ups

  • 8.x: the Overview page's PostgreSQL requirement (11) and platform list are stale for 8.x too; separate small PR.
  • The copied pages carry legacy canonical: front matter pointing at /openvoxdb/latest/; the theme only reads canonical_url (set by _plugins/canonical_latest.rb), so it is inert. Could be stripped from both collections in a cleanup.

@miharp
miharp requested a review from a team as a code owner August 27, 2026 12:51
@miharp
miharp force-pushed the docs/openvoxdb9-cutover branch from c1c02d1 to a64da50 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>
Phase 1 of the major-version cutover in MAINTAINING.md for OpenVoxDB:
copy docs/_openvoxdb_8x to docs/_openvoxdb_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 9.0.0-beta1:

- index: prerelease notice, version note, Java 21 or 25 (17 dropped),
  platform list from the shared-actions main platform list (Debian
  11/12 dropped), OpenJDK 21/25 for custom installs, OpenVox Server
  naming in the server requirement plus the openvoxdb-termini package
  dependency (openvox-agent >= 8.26.2, no upper bound in beta1),
  PostgreSQL 14 minimum (oldest-supported-db in scf/storage.clj)
- puppetdb-faq: supported JDK versions
- install_from_source: JDK 21
- configure: the [jetty] note names Jetty 12
- release_notes: rewritten for the 9.0.0 prerelease series, including
  the bootstrap.cfg jetty10-service pitfall for upgrades from 8.14.0 or
  earlier

The shipped config templates (resources/ext/config) are identical
between 8.15.0 and 9.0.0-beta1 apart from the packaging dependency
change, so the configuration pages are otherwise unchanged. Known
issues and the versioning policy are not version-specific and are
unchanged.

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/openvoxdb9-cutover branch from a64da50 to e5772c4 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