voxpupuli/openvoxserver repository overview

⁠OpenVox Server container

• OpenVox Server container⁠
  • Informations⁠
    • End of Life for OpenVox Server 7⁠
    • Migration⁠
  • Note about environment caching⁠
  • Version schema⁠
  • Configuration⁠
  • Initialization Scripts⁠
  • Persistence⁠
    • Permissions⁠
      • Rootless Podman⁠
      • Docker⁠
  • How to deploy OpenVox/Puppet code⁠
    • ✅ Preferred way to deploy your code⁠
    • 🔥 Not recommended way, but often used, pattern from the non-container world⁠
  • How to Release the container⁠
  • How to contribute⁠

This project hosts the Containerfile and the required scripts to build a OpenVox Server container image. See the OpenVox Packages⁠ for available versions.

You can run a copy of Puppet Server with the following Docker command:

podman run --name openvox --hostname openvox ghcr.io/openvoxproject/openvoxserver:8.13.0

Although it is not strictly necessary to name the container openvox, this is useful when working with the other OpenVox images, as they will look for a server on that hostname by default.

If you would like to start the OpenVox Server with your own Puppet code, you can mount your own directory at /etc/puppetlabs/code:

podman run --name openvox --hostname openvox -v ./code:/etc/puppetlabs/code ghcr.io/openvoxproject/openvoxserver:8.13.0

For compose file see: CRAFTY⁠

⁠Informations

⁠End of Life for OpenVox Server 7

⚠️ On February 28, 2025, OpenVox/Puppet 7 entered its end-of-life phase. Consequently, no new OpenVox Server 7 releases will be build. Existing versions will be retained for continued access.

⁠Migration

Before updating to a newer version of your container, you should check the migration document⁠

⁠Note about environment caching

⚠️ The OpenVox Server has the environment caching⁠ enabled by default. You should explicitly call the API endpoint to clear the cache when a new environment is deployed. See the curl example below.

curl -i --cert $(puppet config print hostcert) \
--key $(puppet config print hostprivkey) \
--cacert $(puppet config print cacert) \
-X DELETE \
https://$(puppet config print server):8140/puppet-admin-api/v1/environment-cache?environment=production

Another option is to disable the environment caching by setting the OPENVOXSERVER_ENVIRONMENT_TIMEOUT environment variable to zero (0).

⁠Version schema

Images are published to ghcr.io/openvoxproject/openvoxserver and docker.io/voxpupuli/openvoxserver. Ubuntu is the default image variant and therefore has no operating system suffix. Alpine images use the -alpine suffix.

Builds from the main branch are additionally tagged as <openvox.version>-main and <openvox.version>-main-alpine.

Example using an immutable container release:

podman run --name openvox --hostname openvox -v ./code:/etc/puppetlabs/code/ ghcr.io/openvoxproject/openvoxserver:8.13.0-v1.2.3

The OpenVox version describes the server version contained in the image. The container version follows semantic versioning and describes changes to the container image independently of the OpenVox version.

⁠Configuration

The following environment variables are supported:

⁠Initialization Scripts

If you would like to do additional initialization, add a directory called /container-custom-entrypoint.d/ and fill it with .sh scripts.

You can also create sub-directories in /container-custom-entrypoint.d/ for scripts that have to run at different stages.

• /container-custom-entrypoint.d/pre-default/ - scripts that run before the default entrypoints scripts.
• /container-custom-entrypoint.d/ - scripts that run after the default entrypoint scripts, but before the openvoxserver service is started.
• /container-custom-entrypoint.d/post-startup/ - scripts that run after the openvoxserver service is started.
• /container-custom-entrypoint.d/sigterm-handler/ - scripts that run when the container receives a SIGTERM signal.
• /container-custom-entrypoint.d/post-execution/ - scripts that run after the openvoxserver service has stopped.

⁠Persistence

If you plan to use the in-server CA, restarting the container can cause the server's keys and certificates to change, causing agents and the server to stop trusting each other. To prevent this, you can persist the default cadir, /etc/puppetlabs/puppetserver/ca. For example:

podman run -v $PWD/ca-ssl:/etc/puppetlabs/puppetserver/ca ghcr.io/openvoxproject/openvoxserver:8.13.0

or in compose:

services:
  puppet:
    image: ghcr.io/openvoxproject/openvoxserver:8.13.0
    # ...
    volumes:
      - ./ca-ssl:/etc/puppetlabs/puppetserver/ca

⁠Permissions

⁠Rootless Podman

When using rootless Podman, the OpenVox Server process runs directly as the non-root puppet user (UID 1001) with the root group (GID 0). This can lead to permission issues with bind mount volumes, which you may want to use for the OpenVox SSL and CA directories. For example:

-v ./openvoxserver-ssl:/etc/puppetlabs/puppet/ssl
-v ./openvoxserver-ca:/etc/puppetlabs/puppetserver/ca

By default the container will attempt to correct permissions. For a large number of files it may spend a long time at "Adjusting mounted CA directory ownership". This is normal. If this still runs into permissions issues please check selinux and related security layers. You can relabel the host directory using the :Z flag:

-v ./openvoxserver-ca:/etc/puppetlabs/puppetserver/ca:Z

Please be careful not to mount any vital system directories when using this flag.

If you're starting from scratch we instead recommend using a named volume. For example, note that the left value is not a path:

-v puppet_ca:/etc/puppetlabs/puppetserver/ca

Permissions are managed for you, and from there the volume can be migrated using podman volume export and podman volume import commands.

⁠Docker

Docker always runs rootfull, and does not need permissions adjustments.

⁠How to deploy OpenVox/Puppet code

⁠✅ Preferred way to deploy your code

We recommend to use the r10k⁠ container and use a shared volume to deploy your code to the OpenVox Server.

Example usage: https://github.com/voxpupuli/crafty/blob/main/openvox/r10k/README.md⁠

The r10k container can be scheduled to run at regular intervals to keep your OpenVox Server up to date with the latest code changes. Or you use the r10k-webhook⁠ container to trigger a deployment when a new commit is pushed to your repository.

⁠🔥 Not recommended way, but often used, pattern from the non-container world

At the moment the container has r10k installed. You can use it to deploy your code from within the container.

🚧 Please be informed that this might change, and we’re considering removing the r10k installation from the container in the future.

Create a r10k.yaml file with the following content and mount it to the container at /etc/puppetlabs/r10k/r10k.yaml:

---
pool_size: 8
deploy:
  generate_types: true
  exclude_spec: true
  incremental: true
  purge_levels: [ 'deployment', 'environment', 'puppetfile' ]
cachedir: "/opt/puppetlabs/puppet/cache/r10k"
sources:
  puppet:
    basedir: "/etc/puppetlabs/code/environments"
    remote: https://github.com/voxpupuli/controlrepo.git

Run the main container with the following command, which mounts the r10k.yaml file to the container:

podman run -it --rm --name openvox -v ./r10k:/etc/puppetlabs/r10k:ro ghcr.io/openvoxproject/openvoxserver:latest

Then you can run the following command to deploy your code.

podman exec openvox r10k deploy environment -mv

⁠How to Release the container

see here⁠

⁠How to contribute

see here⁠