Merge pull request #11 from jpartlow/add-package-parameter-to-install

(doc) Add and test for current REFERENCE.md using puppet-strings

Author: jpartlow

.github/actions/container_task_prep/action.yaml

@@ -17,31 +17,18 @@ runs:
         source openvox_bootstrap/files/common.sh
 
         # Ensure wget is installed.
-        if exists 'apt'; then
-          exec_and_capture apt update
-        elif exists 'apt-get'; then
-          exec_and_capture apt-get update
-        elif exists 'dnf'; then
-          exec_and_capture dnf clean all
-        elif exists 'yum'; then
-          exec_and_capture yum clean all
-        elif exists 'zypper'; then
-          exec_and_capture zypper refresh
-        else
-          echo "No package manager found."
-          exit 1
-        fi
+        refresh_package_cache
         install_package wget
 
         # Deal with missing package dependencies in the containers.
         # ...possibly this should be moved into the
         # install_build_artifact task scripts.
-        set_platform
+        set_platform_globals
         if [[ "${platform}" == 'Rocky' ]]; then
           # The Rocky9 container, at least, is missing openvox-agent's
           # systemd dependency...
           exec_and_capture dnf install -y systemd
-          if [[ "${major_version}" == '8' ]]; then
+          if [[ "${os_major_version}" == '8' ]]; then
             # ...and the Rocky8 container is missing findutils.
             exec_and_capture dnf install -y findutils
           fi

.github/workflows/pr_testing.yaml

@@ -26,6 +26,22 @@ jobs:
       - name: Run ShellCheck
         run: shellcheck -x tasks/*.sh files/*.sh
 
+  reference-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          # Not testing 3.4 yet, puppet fails to load here:
+          # bundler: failed to load command: puppet (/home/jpartlow/.rbenv/versions/3.4.3/lib/ruby/gems/3.4.0/bin/puppet)
+          # /home/jpartlow/.rbenv/versions/3.4.3/lib/ruby/gems/3.4.0/bundler/gems/puppet-6992edd1da38/lib/puppet/feature/base.rb:21:in '<top (required)>': Cannot determine basic system flavour (Puppet::Error)
+          ruby-version: '3.3'
+          bundler-cache: true
+      - name: Regenerate REFERENCE.md
+        run: bundle exec puppet strings generate --format markdown
+      - name: Check whether REFERENCE.md has uncommitted changes
+        run: git diff --exit-code REFERENCE.md
+
   test-install-task-on-ubuntu:
     strategy:
       matrix:
@@ -115,3 +131,67 @@ jobs:
         env:
           PT_version: "8.14.0"
         run: ./openvox_bootstrap/tasks/install_linux.sh
+
+  test-install-package:
+    strategy:
+      matrix:
+        image:
+          - rockylinux:9
+          # openvox-server not currently built for fedora
+          #          - fedora:41
+          - debian:12
+          - ubuntu:24.04
+          # Need to pull in the repo GPG keys for sles
+          #          - registry.suse.com/suse/sle15:15.6
+    needs: shellcheck
+    runs-on: ubuntu-latest
+    container: ${{ matrix.image }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: openvox_bootstrap
+      - id: prep
+        uses: ./openvox_bootstrap/.github/actions/container_task_prep
+      - name: Run openvox-agent install task manually
+        env:
+          PT_package: "openvox-server"
+        run: ./openvox_bootstrap/tasks/install_linux.sh
+      - name: Verify openvox-server is installed
+        run: /opt/puppetlabs/bin/puppetserver --version | grep -E '8\.[0-9]+'
+      - name: Verify idempotency
+        env:
+          PT_package: "openvox-server"
+        run: ./openvox_bootstrap/tasks/install_linux.sh
+
+  test-install-package-version:
+    strategy:
+      matrix:
+        image:
+          - rockylinux:9
+          # openvox-server not currently built for fedora
+          #- fedora:41
+          - debian:12
+          - ubuntu:24.04
+          # Need to pull in the repo GPG keys for sles
+          #          - registry.suse.com/suse/sle15:15.6
+    needs: shellcheck
+    runs-on: ubuntu-latest
+    container: ${{ matrix.image }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: openvox_bootstrap
+      - id: prep
+        uses: ./openvox_bootstrap/.github/actions/container_task_prep
+      - name: Run openvox-agent install task manually
+        env:
+          PT_package: "openvox-server"
+          PT_version: "8.8.0"
+        run: ./openvox_bootstrap/tasks/install_linux.sh
+      - name: Verify openvox-server is installed
+        run: /opt/puppetlabs/bin/puppetserver --version | grep '8.8.0'
+      - name: Verify idempotency
+        env:
+          PT_package: "openvox-server"
+          PT_version: "8.8.0"
+        run: ./openvox_bootstrap/tasks/install_linux.sh

.gitignore

@@ -3,4 +3,6 @@
 .rerun.json
 .resource_types
 .task_cache.json
+.yardoc
+Gemfile.lock
 Puppetfile

Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+group :development do
+  # For puppet-strings, with some juggling to avoid the old puppet gem.
+  gem 'openvox', git: 'https://github.com/openvoxproject/puppet.git', tag: '8.17.0'
+  gem 'puppet', path: './puppet-stub'
+  gem 'racc'
+  # For REFERENCE.md generation.
+  gem 'puppet-strings'
+end

README.md

@@ -1,12 +1,11 @@
 # openvox_bootstrap
 
-[Bolt](https://www.puppet.com/docs/bolt/latest/bolt.html) module for
-bootstrapping installation of the openvox-agent package.
+[Bolt] module for bootstrapping installation of the [openvox]
+(Puppet<sup>:tm:</sup>) packages.
 
 Provides some of the functionality of the [puppet_agent::install
-tasks](https://github.com/puppetlabs/puppetlabs-puppet_agent/tree/main?tab=readme-ov-file#puppet_agentinstall)
-for [openvox](https://voxpupuli.org/openvox/) packages from
-https://apt.voxpupuli.org, https://yum.voxpupuli.org.
+tasks] for [openvox] packages from https://apt.voxpupuli.org,
+https://yum.voxpupuli.org.
 
 The puppet_agent module makes use of the Perforce repositories and
 collections instead.
@@ -17,28 +16,34 @@ Assumes you have Bolt installed.
 
 ### openvox_boostrap::install
 
-Installs the openvox8 collection by default (Puppet<sup>:tm:</sup> 8).
+Installs the platform appropriate openvox8 collection release package
+and the openvox-agent package by default (Puppet<sup>:tm:</sup> 8).
 
 ```sh
 bolt task run openvox_bootstrap::install \
   --targets <target> \
   --run-as root
 ```
+#### parameters
+
+By default the task will install the openvox-agent package, but this
+can be overridden by setting the `package` parameter to install
+openvox-server, openvoxdb or another package from the openvox
+collection.
+
+See the [install task](./REFERENCE.md#install) for details.
 
 #### Usage with Bolt apply_prep() function
 
-Bolt's
-[apply_prep](https://www.puppet.com/docs/bolt/latest/plan_functions#apply-prep)
-function ensures that the latest version of Puppet<sup>:tm:</sup> is installed on
-a node by calling the puppet_agent::install task if the agent is not
-detected on the node.
+Bolt's [apply_prep] function ensures that the latest version of
+Puppet<sup>:tm:</sup> is installed on a node by calling the
+`puppet_agent::install` task if the agent is not detected on the node.
 
-The openvox_bootstrap::install task can be used in its place to
+The `openvox_bootstrap::install` task can be used in its place to
 instead ensure that openvox-agent is installed.
 
-The apply_prep() function relies on Bolt's
-[puppet_library](https://www.puppet.com/docs/bolt/latest/using_plugins#puppet-library-plugins)
-plugin configuration.
+The apply_prep() function relies on Bolt's [puppet_library] plugin
+configuration.
 
 To use openvox_bootstrap instead, configure your bolt_project.yaml
 with:
@@ -57,12 +62,22 @@ task that can be used to install a build artifact package directly
 from the https://artifact.voxpupuli.org repository for testing
 prior to release.
 
+Minimally, you must supply the `version` parameter, but generally you
+would also supply `package` unless you are installing the
+openvox-agent package.
+
+See [task ref](./REFERENCE.md#install_build_artifact) for details.
+
 ```sh
-bolt task run openvox_bootstrap::install \
-  --targets <target> \
+bolt task run openvox_bootstrap::install_build_artifact \
+  --targets <target> --version=8.17.0 \
   --run-as root
 ```
 
+## Reference
+
+See [REFERENCE.md](./REFERENCE.md) for the generated reference doc.
+
 ## TODO
 
 * Windows support
@@ -85,3 +100,9 @@ GNU Affero General Public License for more details.
 
 You should have received a copy of the GNU Affero General Public License
 along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+[bolt]: https://puppet.com/docs/bolt/latest/bolt.html
+[openvox]: https://voxpupuli.org/openvox/
+[puppet_agent::install tasks]: https://github.com/puppetlabs/puppetlabs-puppet_agent/tree/main?tab=readme-ov-file#puppet_agentinstall
+[apply_prep]: https://www.puppet.com/docs/bolt/latest/plan_functions#apply-prep
+[puppet_library]: https://www.puppet.com/docs/bolt/latest/using_plugins#puppet-library-plugins

REFERENCE.md

@@ -0,0 +1,77 @@
+# Reference
+
+<!-- DO NOT EDIT: This document was generated by Puppet Strings -->
+
+## Table of Contents
+
+### Tasks
+
+* [`install`](#install): Installs an openvox package. By default, this will be the latest openvox-agent from the latest collection.
+* [`install_build_artifact`](#install_build_artifact): Downloads and installs a package directly from the openvox build artifact server.
+
+## Tasks
+
+### <a name="install"></a>`install`
+
+Installs an openvox package. By default, this will be the latest openvox-agent from the latest collection.
+
+**Supports noop?** false
+
+#### Parameters
+
+##### `package`
+
+Data type: `String[1]`
+
+The name of the package to install.
+
+##### `version`
+
+Data type: `Optional[String]`
+
+The version of the openvox-agent package to install. Defaults to latest.
+
+##### `collection`
+
+Data type: `Optional[String]`
+
+The openvox collection to install from.
+
+##### `apt_source`
+
+Data type: `Optional[String]`
+
+The apt source repository to retrieve deb packages from.
+
+##### `yum_source`
+
+Data type: `Optional[String]`
+
+The yum source repository to retrieve rpm packages from.
+
+### <a name="install_build_artifact"></a>`install_build_artifact`
+
+Downloads and installs a package directly from the openvox build artifact server.
+
+**Supports noop?** false
+
+#### Parameters
+
+##### `package`
+
+Data type: `String[1]`
+
+The name of the package to install.
+
+##### `version`
+
+Data type: `String[1]`
+
+The version of the package to install.
+
+##### `artifacts_source`
+
+Data type: `String[1]`
+
+URL to the build artifacts server.
+