(tasks) Add package param to install task

By default, openvox_bootstrap::install will still install openvox-agent,
but you can override `package` to install another package, such as
openvox-server or openvoxdb from the collection.

Author: jpartlow

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,9 +62,15 @@ 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
 ```
 
@@ -85,3 +96,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

@@ -6,19 +6,25 @@
 
 ### Tasks
 
-* [`install`](#install): Installs the openvox-agent package.
+* [`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 openvox build artifact server. This can be used to help with testing builds prior to release. 
 
 ## Tasks
 
 ### <a name="install"></a>`install`
 
-Installs the openvox-agent package.
+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]`
@@ -51,17 +57,17 @@ Downloads and installs a package directly from openvox build artifact server. Th
 
 #### Parameters
 
-##### `version`
+##### `package`
 
 Data type: `String[1]`
 
-The version of the package to install.
+The name of the package to install.
 
-##### `package`
+##### `version`
 
 Data type: `String[1]`
 
-The name of the package to install.
+The version of the package to install.
 
 ##### `artifacts_source`
 

files/common.sh

@@ -260,6 +260,29 @@ set_package_type() {
   assigned 'package_file_suffix'
 }
 
+# Construct and echo the full debian package version string.
+# Echoing for $() capture rather than setting a 'global' $var
+# since this could be called multiple times for different packages.
+get_deb_package_version() {
+  local _version="$1"
+  local _family="${2:-${family}}"
+  local _full_version="${3-${full_version}}"
+
+  # Need the full packaging version for deb.
+  # As an example, for openvox-agent 8.14.0 on ubuntu 24.04:
+  # 8.14.0-1+ubuntu24.04
+  if [[ "${_version}" =~ - ]]; then
+    # Caller's version already has a '-' seprator, so we
+    # should respect that they have probably supplied some
+    # full package version string.
+    _package_version="${_version}"
+  else
+    _package_version="${_version}-1+${_family}${_full_version}"
+  fi
+
+  echo -n "${_package_version}"
+}
+
 # Install a local rpm or deb package file.
 install_package_file() {
   local _package_file="$1"
@@ -281,10 +304,13 @@ install_package_file() {
 }
 
 # Install a package using the system package manager.
+# The version is optional, and if not provided, the latest version
+# available in the repository will be installed.
 install_package() {
   local _package="$1"
   local _version="$2"
   local _family="${3:-${family}}"
+  local _full_version="${4:-${full_version}}"
 
   info "Installing ${_package} ${_version}"
 
@@ -296,7 +322,13 @@ install_package() {
     fi
     case $_family in
       debian|ubuntu)
-        _package_and_version="${_package}=${_version}"
+        if [[ -z "${_full_version}" ]]; then
+          set_platform
+          _full_version="${full_version}"
+        fi
+        local _deb_package_version
+        _deb_package_version=$(get_deb_package_version "${_version}" "${_family}" "${_full_version}")
+        _package_and_version="${_package}=${deb_package_version}"
         ;;
       *)
         _package_and_version="${_package}-${_version}"

tasks/install.json

@@ -1,6 +1,11 @@
 {
-  "description": "Installs the openvox-agent package.",
+  "description": "Installs an openvox package. By default, this will be the latest openvox-agent from the latest collection.",
   "parameters": {
+    "package": {
+      "description": "The name of the package to install.",
+      "type": "String[1]",
+      "default": "openvox-agent"
+    },
     "version": {
       "description": "The version of the openvox-agent package to install. Defaults to latest.",
       "type": "Optional[String]"

tasks/install_build_artifact.json

@@ -1,15 +1,15 @@
 {
   "description": "Downloads and installs a package directly from openvox build artifact server. This can be used to help with testing builds prior to release. (To install a released version, use the openvox_bootstrap::install task.)",
   "parameters": {
-    "version": {
-      "description": "The version of the package to install.",
-      "type": "String[1]"
-    },
     "package": {
       "description": "The name of the package to install.",
       "type": "String[1]",
       "default": "openvox-agent"
     },
+    "version": {
+      "description": "The version of the package to install.",
+      "type": "String[1]"
+    },
     "artifacts_source": {
       "description": "URL to the build artifacts server.",
       "type": "String[1]",

tasks/install_linux.sh

@@ -6,6 +6,8 @@ set -e
 # shellcheck disable=SC2154
 installdir=$PT__installdir
 # shellcheck disable=SC2154
+package=${PT_package:-'openvox-agent'}
+# shellcheck disable=SC2154
 version=${PT_version:-'latest'}
 # shellcheck disable=SC2154
 collection=${PT_collection:-'openvox8'}
@@ -72,41 +74,6 @@ install_release_package() {
   fi
 }
 
-# Installs the openvox-agent package using the system package manager.
-# The version is optional, and if not provided, the latest version
-# available in the repository will be installed.
-install_openvox_agent() {
-  local _version="$1"
-  local _family="$2"
-  local _full_version="$3"
-
-  local _package_version
-  if [[ -n "${_version}" ]] && [[ "${_version}" != 'latest' ]]; then
-    case $_family in
-      debian|ubuntu)
-        # Need the full packaging version for deb.
-        # As an example, for openvox-agent 8.14.0 on ubuntu 24.04:
-        # 8.14.0-1+ubuntu24.04
-        if [[ "${_version}" =~ - ]]; then
-          # Caller's version already has a '-' seprator, so we
-          # should respect that they have probably supplied some
-          # full package version string.
-          _package_version="${_version}"
-        else
-          _package_version="${_version}-1+${_family}${_full_version}"
-        fi
-        ;;
-      *)
-        # rpm packages should be fine so long as the shorter form
-        # matches uniquely.
-        _package_version="${_version}"
-        ;;
-    esac
-  fi
-
-  install_package openvox-agent "${_package_version}" "${_family}"
-}
-
 # Get platform information
 set_platform
 # Set collection release package url based on platform
@@ -119,4 +86,4 @@ download "${package_url}" "${local_release_package}"
 # packages from the collection using the platform package manager.
 install_release_package "${local_release_package}" "${package_type}"
 # Use the platform package manager to install openvox-agent
-install_openvox_agent "${version}" "${family}" "${full_version}"
+install_package "${package}" "${version}" "${family}" "${full_version}"