voxpupuli/voxbox

voxpupuli/voxbox repository overview

⁠Vox Pupuli

⁠Introduction

This container should be used to test voxpupuli OpenVox/Puppet modules. It has the voxpupuli-test, -acceptance, -release gems and all dependencies installed.

⁠Breaking changes

⚠ On February 28, 2025, OpenVox/Puppet 7 entered its end-of-life phase. Consequently, no new VoxBox:7 releases will be build. Existing versions will be retained for continued access.
⚠ On March 20, 2026, Onceover was removed from this container. If you need Onceover, please use the dedicated container for this: https://github.com/voxpupuli/container-onceover⁠.
⚠ On May 27, 2026, We seperated the VoxBox gems from the system ruby and moved it into a local bundle. This means that you have to use bundle exec to execute the gems. This was done to avoid conflicts with the system ruby and to have more control over the gem versions.
⚠ Starting with VoxBox 10.0.0, release tags use the new <voxbox.version>-openvox<version> schema, for example 10.1.2-openvox8 or 10.1.2-openvox8.28.0. The latest tag now points to the newest release, while builds from the main branch use main and sha-<git.sha>. Existing legacy tags remain available but are no longer updated.

⁠Included rubygems

see: Gemfile⁠

hiera-eyaml
librarian
modulesync
openfact
openvox
puppet-ghostbuster
r10k
rubocop
voxpupuli-acceptance
voxpupuli-release
voxpupuli-test

⁠Additionally included tools

curl
git
gpg
jig
jq
ssh-client
yamllint

⁠Versions

Too see which tool versions are included in the container, see:

Containerfile⁠

⁠Usage

⁠EasyVoxBox (evb)

The evb script⁠ shortens the commands to be typed for running voxbox. Additionally, it does not care about the sequence of options, which can be useful for setting shell aliases. To run the command you must change into any subdirectory of an openvox module (with a metadata.json file) or a control repository (with a Puppetfile).

Display the evb help message:

$ evb help
Usage: /usr/local/bin/evb [options] [command]

available options:
  --noop        : print the command to run, but do not run it
  --entrypoint  : use a different entrypoint
                  examples for available endpoints are:
                  ash, puppet, yamllint, jq, curl, rubocop
                  default: no entrypoint specified
  --image image : use a different image (default ghcr.io/voxpupuli/voxbox:latest)
  --env VAR=val : specify environment variables (can be used multiple times)
                  Remark: the term './' in a assignment will be replaced with
                  the correct path to be used in the container.
                  Example: if you start the script in ~/openvox-supermodule/spec/classes
                           and set --env SPEC=./supermodule_spec.rb we will
                           run VoxBox with -e SPEC=spec/classes/supermodule_spec.rb
  --volume vol  : specify an additional volume to put into the container
                  see podman man page how to specify 'vol'. (no path magic is done ;))
  --runcmd      : this lets you change the program used to start the container
                  if not set explicit it looks for podman or docker.

available command:
   help  : print this help message and exit

commands/options not listed here are passed to VoxBox as is.
use the '--noop' option to print the detailed call to VoxBox.

See the command that would be executed (dropping the --noop option will run the command):

evb --noop                                     # for rake -T
evb --noop spec                                # for rake spec
evb --noop --env SPEC=./example_spec.rb spec   # for only a specific spec in the current subdirectory

# or the release rake task
evb --volume ~/.gitconfig:/etc/gitconfig:ro \
    --volume ~/.ssh:/root/.ssh \
    --volume ${SSH_AUTH_SOCK}:${SSH_AUTH_SOCK} \
    --env  SSH_AUTH_SOCK="${SSH_AUTH_SOCK}" \
    release --noop

⁠Rake

Change into the root of a OpenVox/Puppet module and run the container. Make sure to mount the current directory into the container under /repo. The default entrypoint is rake. Without any arguments it will run rake -f /opt/voxbox/Rakefile -T. You can specify a rake task as argument. See Available rake tasks⁠ for more information.

To guarantee a consistent rake environment, we use -f /opt/voxbox/Rakefile to explicitly specify a Rakefile, rather than relying on potentially outdated versions in a repository. The Rakefile being used can be viewed here⁠.

cd puppet-example

evb      # rake -T
evb spec # rake spec

podman run -it --rm -v $PWD:/repo:Z ghcr.io/voxpupuli/voxbox:latest      # rake -T
podman run -it --rm -v $PWD:/repo:Z ghcr.io/voxpupuli/voxbox:latest spec # rake spec

⁠release Task

Using the release rake task:

podman run -it --rm \
   -v $PWD:/repo:Z \
   -v ~/.gitconfig:/etc/gitconfig:ro \
   -v ~/.ssh:/root/.ssh \
   -v ${SSH_AUTH_SOCK}:${SSH_AUTH_SOCK} \
   -e SSH_AUTH_SOCK="${SSH_AUTH_SOCK}" \
   ghcr.io/voxpupuli/voxbox:latest release

⁠spec Task

Running only a specific spec:

evb --env "SPEC=spec/classes/init_spec.rb" spec

podman run -it --rm -e "SPEC=spec/classes/example_spec.rb" -v $PWD:/repo:Z ghcr.io/voxpupuli/voxbox:latest spec

⁠Available rake tasks

rake beaker                                                                     # Run RSpec code examples
rake build                                                                      # Build puppet module package
rake build:pdk                                                                  # Build Puppet module with PDK
rake check                                                                      # Run static pre release checks
rake check:dot_underscore                                                       # Fails if any ._ files are present in directory
rake check:git_ignore                                                           # Fails if directories contain the files specified in .gitignore
rake check:symlinks                                                             # Fails if symlinks are present in directory
rake check:test_file                                                            # Fails if .pp files present in tests folder
rake check:trailing_whitespace                                                  # Check for trailing whitespace
rake check_changelog                                                            # Check Changelog
rake clean                                                                      # Clean a built module package
rake compute_dev_version                                                        # Print development version of module
rake generate_fixtures                                                          # Generate -fixtures.yml based on Puppetfile
rake generate_vendor_cache                                                      # Fetches the core modules which are usually bundled in AIO agent
rake help                                                                       # Display the list of available rake tasks
rake lint                                                                       # Run puppet-lint
rake lint_fix                                                                   # Run puppet-lint
rake metadata_lint                                                              # Run metadata-json-lint
rake module:build                                                               # Build the module using puppet-modulebuilder
rake module:bump                                                                # Bump module version to the next patch
rake module:bump:full                                                           # Bump module version to the next FULL version
rake module:bump:major                                                          # Bump module version to the next MAJOR version
rake module:bump:minor                                                          # Bump module version to the next MINOR version
rake module:bump:patch                                                          # Bump module version to the next PATCH version
rake module:bump_commit                                                         # Bump version and git commit
rake module:bump_commit:full                                                    # Bump module version to the next FULL version and git commit
rake module:bump_commit:major                                                   # Bump module version to the next MAJOR version and git commit
rake module:bump_commit:minor                                                   # Bump module version to the next MINOR version and git commit
rake module:bump_commit:patch                                                   # Bump module version to the next PATCH version and git commit
rake module:bump_to_version[new_version]                                        # Bump module to specific version number
rake module:clean                                                               # Runs clean again
rake module:dependency[module_name,version]                                     # Set specific module dependency version
rake module:push                                                                # Push module to the Puppet Forge
rake module:release                                                             # Release the Puppet module, doing a clean, build, bump_commit, tag, push and git push
rake module:tag                                                                 # Git tag with the current module version
rake module:version                                                             # Get current module version
rake module:version:next                                                        # Get next module version
rake module:version:next:major                                                  # Get the next MAJOR version
rake module:version:next:minor                                                  # Get the next MINOR version
rake module:version:next:patch                                                  # Get the next PATCH version
rake parallel_spec                                                              # Run spec tests in parallel and clean the fixtures directory if successful
rake parallel_spec_standalone                                                   # Parallel spec tests
rake r10k:dependencies                                                          # Print outdated forge modules
rake r10k:deprecation                                                           # Validate that no forge modules are deprecated
rake r10k:duplicates                                                            # Check Puppetfile for duplicates
rake r10k:install                                                               # Install modules specified in Puppetfile
rake r10k:print_git_conversion                                                  # Convert and print forge modules to git format
rake r10k:solve_dependencies[allow_major_bump]                                  # Find missing or outdated module dependencies
rake r10k:syntax                                                                # Syntax check Puppetfile
rake r10k:validate                                                              # Validate the git urls and branches, refs, or tags
rake release                                                                    # Release via GitHub Actions
rake release:prepare                                                            # Prepare a release
rake release_checks                                                             # Runs all necessary checks on a module in preparation for a release
rake rubocop                                                                    # Run RuboCop
rake rubocop:autocorrect                                                        # Autocorrect RuboCop offenses (only when it's safe)
rake rubocop:autocorrect_all                                                    # Autocorrect RuboCop offenses (safe and unsafe)
rake spec                                                                       # Run spec tests and clean the fixtures directory if successful
rake spec:simplecov                                                             # Run spec tests with ruby simplecov code coverage
rake spec_clean                                                                 # Clean up the fixtures directory
rake spec_clean_symlinks                                                        # Clean up any fixture symlinks
rake spec_list_json                                                             # List spec tests in a JSON document
rake spec_prep                                                                  # Create the fixtures directory
rake spec_standalone                                                            # Run RSpec code examples
rake strings:generate[patterns,debug,backtrace,markup,json,markdown,yard_args]  # Generate Puppet documentation with YARD
rake strings:generate:reference[patterns,debug,backtrace]                       # Generate Puppet Reference documentation
rake strings:gh_pages:update                                                    # Update docs on the gh-pages branch and push to GitHub
rake strings:validate:reference[patterns,debug,backtrace]                       # Validate the reference is up to date
rake syntax                                                                     # Syntax check for Puppet manifests, templates and Hiera
rake syntax:hiera                                                               # Syntax check Hiera config files
rake syntax:manifests                                                           # Syntax check Puppet manifests
rake syntax:templates                                                           # Syntax check Puppet templates
rake test                                                                       # Run tests
rake travis_release                                                             # Deprecated: use the "release" task instead
rake validate                                                                   # Check syntax of Ruby files and call :syntax and :metadata_lint
rake voxpupuli:custom:lint_all                                                  # Lint with all puppet-lint checks

⁠Shell

If you need a shell, you have to override the entrypoint:

evb --entrypoint ash

podman run -it --rm -v $PWD:/repo:Z --entrypoint ash ghcr.io/voxpupuli/voxbox:latest

⁠OpenVox/Puppet

If you want to execute puppet change the entrypoint to puppet and pass subcommands/parameters to it.

evb --entrypoint bundle exec puppet --help

podman run -it --rm -v $PWD:/repo:Z --entrypoint bundle ghcr.io/voxpupuli/voxbox:latest exec puppet --help

⁠OpenVox/Puppet Strings

evb --entrypoint bundle exec puppet strings --help

podman run -it --rm -v $PWD:/repo:Z --entrypoint bundle ghcr.io/voxpupuli/voxbox:latest exec puppet strings --help

⁠puppet-ghostbuster

If you want to execute puppet-ghostbuster change the entrypoint to ash and pass the command to the container. Ghostbuster needs a connection to the OpenVoxDB/PuppetDB, so you have to provide the environment variables. You can find them in the documentation of the puppet-ghostbuster⁠ repository.

Ghostbuster supports the following checks:

ghostbuster_classes
ghostbuster_defines
ghostbuster_facts
ghostbuster_files
ghostbuster_functions
ghostbuster_hiera_files
ghostbuster_templates
ghostbuster_types

They can be combined with --only-checks and listed in a comma separated list.

podman run -it --rm -v $PWD:/repo:Z --entrypoint ash ghcr.io/voxpupuli/voxbox:latest
find . -type f -exec bundle exec puppet-lint --only-checks ghostbuster_classes,ghostbuster_facts {} \+

⁠YAMLlint

If you want to execute yamllint change the entryoint to yamllint and pass a folder to the container, f.e. ..

evb --entrypoint yamllint .

podman run -it --rm -v $PWD:/repo:Z --entrypoint yamllint ghcr.io/voxpupuli/voxbox:latest .

⁠JQ

If you want to execute jq change the entrypoint to jq and pass a query/parameter to the container.

evb --entrypoint jq --help

podman run -it --rm -v $PWD:/repo:Z --entrypoint jq ghcr.io/voxpupuli/voxbox:latest --help

⁠cURL

If you want to execute curl change the entrypoint to curl and pass a query/parameter to the container.

evb --entrypoint curl --help

podman run -it --rm -v $PWD:/repo:Z --entrypoint curl ghcr.io/voxpupuli/voxbox:latest --help

⁠RuboCop

If you want to execute RuboCop directly change the entrypoint to rubocop and pass a subcommands/parameter to the container.

evb --entrypoint bundle exec rubocop
evb --entrypoint bundle exec rubocop --auto-gen-config

podman run -it --rm -v $PWD:/repo:Z --entrypoint bundle ghcr.io/voxpupuli/voxbox:latest exec rubocop
podman run -it --rm -v $PWD:/repo:Z --entrypoint bundle ghcr.io/voxpupuli/voxbox:latest exec rubocop --auto-gen-config

⁠Librarian

If you want to execute librarian change the entrypoint to librarian-puppet and pass a query/parameter to the container.

evb --entrypoint bundle exec librarian-puppet help

podman run -it --rm -v $PWD:/repo:Z --entrypoint bundle ghcr.io/voxpupuli/voxbox:latest exec librarian-puppet help

⁠hiera-eyaml

If you want to encrypt/decrypt data using plain eyaml, change the entrypoint like so :

evb --entrypoint bundle exec eyaml edit /repo/

podman run -it --rm -v $PWD:/repo:Z --entrypoint bundle ghcr.io/voxpupuli/voxbox:latest exec eyaml edit /repo/

⁠jig

PDK Scaffolding (and more) replacement https://github.com/voxpupuli/jig⁠

If you want to execute jig change the entrypoint to jig and pass a query/parameter to the container.

evb --entrypoint jig --help

podman run -it --rm -v $PWD:/repo:Z --entrypoint jig ghcr.io/voxpupuli/voxbox:latest --help

⁠Dealing with PDK

If you have a module which was created with PDK, you might run into some issues.

useful tips:

PDK Command	VoxBox Command
pdk validate	evb validate
pdk test unit	evb spec
pdk new	evb --entrypoint jig new⁠
pdk convert	evb --entrypoint jig convert⁠
pdk update	evb --entrypoint jig renew⁠
pdk build	evb --entrypoint jig build⁠

For more jig commands also see: https://github.com/voxpupuli/jig/blob/main/docs/README.md#commands⁠

⁠puppetlabs_spec_helper

Your Gemfile or spec files might require puppetlabs_spec_helper.

This will not work with VoxBox because it neither includes nor requires the puppetlabs_spec_helper gem. These references need to be removed or commented out.

You may even be able to remove the Gemfile and Rakefile entirely. VoxBox provides its own Gemfile and Rakefile for running tests. However, you should only do this if you don't need them for any Ruby-based testing outside of VoxBox.

Alternatively, you can run jig convert to handle the conversion automatically.

⁠GitLab

⁠Example GitLab CI configuration

see .gitlab-ci.yml⁠

⁠GitLab Codequality Report

Example usage:

code-quality:
  image:
    name: ghcr.io/voxpupuli/voxbox:latest
    entrypoint: [""]
  stage: verify
  script:
    - bundle exec rake -f /opt/voxbox/Rakefile voxpupuli:custom:lint_all
  variables:
    # setting this variable makes puppet-lint create the json file
    # needed for the code quality report
    CODECLIMATE_REPORT_FILE: "gl-code-quality-report.json"
  artifacts:
    when: always
    reports:
      codequality: gl-code-quality-report.json
    expire_in: 1 week

⁠GitLab Unit Test Report

add to .rspec file:

--format RspecJunitFormatter
--out rspec.xml

add to .gitlab-ci.yml:

rspec:
  image:
    name: ghcr.io/voxpupuli/voxbox:latest
    entrypoint: [""]
  stage: test
  script:
    - bundle exec rake -f /opt/voxbox/Rakefile spec
  artifacts:
    when: always
    reports:
      junit: rspec.xml
    expire_in: 1 week

⁠Media

For some images, see media/⁠ folder. These are the official images used in the documentation and the README.

⁠Version Schema

VoxBox releases use their own semantic version, independent of the OpenVox version contained in the image. Container versions start at 10.0.0 to avoid conflicts with the existing OpenVox/Puppet major-version tags. Bare numeric tags such as 10 are not published.

<container.version>-openvox<openvox.version>
<container.version>-openvox<openvox.major>
latest
main
sha-<git.sha>

Example usage:

podman pull ghcr.io/voxpupuli/voxbox:10.1.2-openvox8.28.0
podman pull ghcr.io/voxpupuli/voxbox:10.1.2-openvox8
podman pull ghcr.io/voxpupuli/voxbox:latest
podman pull ghcr.io/voxpupuli/voxbox:main

Tag	Description
`10.1.2-openvox8.28.0`	Immutable release with an exact VoxBox and OpenVox version
`10.1.2-openvox8`	Immutable VoxBox release for an OpenVox major version
`latest`	Newest published VoxBox release across all OpenVox flavors
`main`	Most recent build from the `main` branch; may change without a release
`sha-<git.sha>`	Immutable build from a specific Git revision

⁠Semantic versioning

The VoxBox version describes compatibility of the container's documented interface, not just the versions of its individual tools and gems:

Major: Existing users must change a documented command, configuration, path, mount, environment variable, or tag. Examples include removing a Rake task or bundled tool, changing the entrypoint or /opt/voxbox paths, dropping an architecture, or moving latest to an incompatible OpenVox major version.
Minor: Backward-compatible functionality is added, such as a new tool, Rake task, or optional configuration.
Patch: Backward-compatible bug fixes, security updates, and dependency updates without user-visible changes.

A major update of an included dependency does not automatically require a VoxBox major release. The resulting change must be evaluated by its effect on the documented container interface and existing module workflows.

latest is only mov

Tag summary

Recent tags

Content type

Image

Digest

sha256:704dfe406…

Size

123.7 MB

Last updated

about 1 month ago

docker pull voxpupuli/voxbox

This week's pulls

Pulls:

229

Last week

Learn more⁠