OpenVox Server container

---

• OpenVox Server container
  • Note about environment caching
  • Version schema
  • Configuration
  • Initialization Scripts
  • Persistence
  • How to Release the container
  • How to contribute

---

This project hosts the Containerfile and the required scripts to build a OpenVox Server container image.

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

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

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.8.0-latest

For compose file see: CRAFTY

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

The version schema has the following layout:

<openvox.major>.<openvox.minor>.<openvox.patch>-v<container.major>.<container.minor>.<container.patch>

Example usage:

podman run --name openvox --hostname openvox -v ./code:/etc/puppetlabs/code/ ghcr.io/OpenVoxProject/openvoxserver:8.8.0-v1.0.0

Name	Description
openvox.major	Describes the contained major OpenVox version (7 or 8)
openvox.minor	Describes the contained minor OpenVox version
openvox.patch	Describes the contained patchlevel OpenVox version
container.major	Describes the major version of the base container (Ubunutu 24.04) or incompatible changes
container.minor	Describes new features or refactoring with backward compatibility
container.patch	Describes if minor changes or bugfixes have been implemented

Configuration

The following environment variables are supported:

Name	Usage / Default
OPENVOXSERVER_HOSTNAME	The DNS name used on the servers SSL certificate - sets the server in puppet.conf Defaults to unset.
CERTNAME	The DNS name used on the servers SSL certificate - sets the certname in puppet.conf Defaults to unset.
DNS_ALT_NAMES	Additional DNS names to add to the servers SSL certificate Note only effective on initial run when certificates are generated
OPENVOXSERVER_PORT	The port of the openvoxserver 8140
AUTOSIGN	Whether or not to enable autosigning on the openvoxserver instance. Valid values are true, false, and /path/to/autosign.conf. Defaults to true.
CA_ENABLED	Whether or not this openvoxserver instance has a running CA (Certificate Authority) true
CA_TTL	CA expire date (in seconds or with suffix s, m, h, d, y) 157680000
CA_HOSTNAME	The DNS hostname for the openvoxserver running the CA. Does nothing unless CA_ENABLED=false puppet
CA_PORT	The listening port of the CA. Does nothing unless CA_ENABLED=false 8140
CA_ALLOW_SUBJECT_ALT_NAMES	Whether or not SSL certificates containing Subject Alternative Names should be signed by the CA. Does nothing unless CA_ENABLED=true. false
INTERMEDIATE_CA	Allows to import an existing intermediate CA. Needs INTERMEDIATE_CA_BUNDLE, INTERMEDIATE_CA_CHAIN and INTERMEDIATE_CA_KEY. See Puppet Intermediat CA
INTERMEDIATE_CA_BUNDLE	File path and name to the complete CA bundle (signing CA + Intermediate CA)
INTERMEDIATE_CRL_CHAIN	File path and name to the complete CA CRL chain
INTERMEDIATE_CA_KEY	File path and name to the private CA key
PUPPET_REPORTS	Sets reports in puppet.conf puppetdb
PUPPET_STORECONFIGS	Sets storeconfigs in puppet.conf true
PUPPET_STORECONFIGS_BACKEND	Sets storeconfigs_backend in puppet.conf puppetdb
OPENVOXSERVER_MAX_ACTIVE_INSTANCES	The maximum number of JRuby instances allowed 1
OPENVOXSERVER_MAX_REQUESTS_PER_INSTANCE	The maximum HTTP requests a JRuby instance will handle in its lifetime (disable instance flushing) 0
OPENVOXSERVER_JAVA_ARGS	Arguments passed directly to the JVM when starting the service -Xms1024m -Xmx1024m
USE_PUPPETDB	Whether to connect to puppetdb Sets PUPPET_REPORTS to log and PUPPET_STORECONFIGS to false if those unset true
PUPPETDB_SERVER_URLS	The server_urls to set in /etc/puppetlabs/puppet/puppetdb.conf https://puppetdb:8081
PUPPETDB_HOSTNAME	The DNS name of the puppetdb Defaults to puppetdb
PUPPETDB_SSL_PORT	The TLS port of the puppetdb Defaults to 8081
OPENVOXSERVER_GRAPHITE_EXPORTER_ENABLED	Activate the graphite exporter. Also needs OPENVOXSERVER_GRAPHITE_HOST and OPENVOXSERVER_GRAPHITE_PORT Defaults to false
OPENVOXSERVER_GRAPHITE_HOST	Only used if OPENVOXSERVER_GRAPHITE_EXPORTER_ENABLED is set to true. FQDN or Hostname of the graphite server where puppet should push metrics to. Defaults to exporter
OPENVOXSERVER_GRAPHITE_PORT	Only used if OPENVOXSERVER_GRAPHITE_EXPORTER_ENABLED is set to true. Port of the graphite server where puppet should push metrics to. Default to 9109
OPENVOXSERVER_ENVIRONMENT_TIMEOUT	Configure the environment timeout Defaults to unlimited
OPENVOXSERVER_ENABLE_ENV_CACHE_DEL_API	Enable the puppet admin api endpoint via certificates to allow clearing environment caches Defaults to true
ENVIRONMENTPATH	Set an environmentpath Defaults to /etc/puppetlabs/code/environments
HIERACONFIG	Set a hiera_config entry in puppet.conf file Defaults to $confdir/hiera.yaml
CSR_ATTRIBUTES	Provide a JSON string of the csr_attributes.yaml content. e.g. CSR_ATTRIBUTES='{"custom_attributes": { "challengePassword": "foobar" }, "extension_requests": { "pp_project": "foo" } }' Defaults to empty JSON object {} Please note that within a compose file, you must provide all environment variables as Hash and not as Array! environment: CSR_ATTRIBUTES: '{"extension_request": {...}}'

Initialization Scripts

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

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

• /docker-custom-entrypoint.d/ - scripts that run after the default entrypoint scripts, but before the openvoxserver service is started.
• /docker-custom-entrypoint.d/post-startup/ - scripts that run after the openvoxserver service is started.
• /docker-custom-entrypoint.d/sigterm-handler/ - scripts that run when the container receives a SIGTERM signal.
• /docker-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.6.1-latest

or in compose:

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

How to Release the container

see here

How to contribute

see here