container-openvoxserver

KO | EN

gitlite — search

#react #ai #typescript #golang #go #machine-learning #rust #linux #nodejs #java #windows #vue #security #open-source

container-openvoxserver

(★ 28)

Container builds for the OpenVox server

container-openvoxserver Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# OpenVox Server container

[![CI](https://github.com/openvoxproject/container-openvoxserver/actions/workflows/ci.yaml/badge.svg)](https://github.com/openvoxproject/container-openvoxserver/actions/workflows/ci.yaml)
[![License](https://img.shields.io/github/license/openvoxproject/container-openvoxserver.svg)](https://github.com/openvoxproject/container-openvoxserver/blob/main/LICENSE)
[![Sponsored by betadots GmbH](https://img.shields.io/badge/Sponsored%20by-betadots%20GmbH-blue.svg)](https://www.betadots.de)

---

- [OpenVox Server container](#openvox-server-container)
  - [Informations](#informations)
    - [End of Life for OpenVox Server 7](#end-of-life-for-openvox-server-7)
    - [Migration](#migration)
  - [Note about environment caching](#note-about-environment-caching)
  - [Version schema](#version-schema)
  - [Configuration](#configuration)
  - [Initialization Scripts](#initialization-scripts)
  - [Persistence](#persistence)
    - [Permissions](#permissions)
      - [Rootless Podman](#rootless-podman)
      - [Docker](#docker)
  - [How to deploy OpenVox/Puppet code](#how-to-deploy-openvoxpuppet-code)
    - [✅ Preferred way to deploy your code](#-preferred-way-to-deploy-your-code)
    - [🔥 Not recommended way, but often used, pattern from the non-container world](#-not-recommended-way-but-often-used-pattern-from-the-non-container-world)
  - [How to Release the container](#how-to-release-the-container)
  - [How to contribute](#how-to-contribute)

---

This project hosts the Containerfile and the required scripts to build a OpenVox Server container image.
See the [OpenVox Packages](https://github.com/orgs/OpenVoxProject/packages) for available versions.

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

```bash
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`:

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

For compose file see: [CRAFTY](https://github.com/voxpupuli/crafty/tree/main/openvox/oss)

## 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](MIGRATION.md)

## Note about environment caching

⚠️ The OpenVox Server has [the environment caching](https://www.puppet.com/docs/puppet/8/server/admin-api/v1/environment-cache.html) 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.

```bash
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.

| Tag | Example | Description |
| --- | --- | --- |
| `<openvox.version>-v<container.version>` | `8.13.0-v1.2.3` | Immutable Ubuntu container release |
| `<openvox.version>-v<container.version>-alpine` | `8.13.0-v1.2.3-alpine` | Immutable Alpine container release |
| `<openvox.version>` | `8.13.0` | Latest build for an OpenVox version, using Ubuntu |
| `<openvox.version>-alpine` | `8.13.0-alpine` | Latest Alpine build for an OpenVox version |
| `<openvox.major>` | `8` | Latest build for an OpenVox major version, using Ubuntu |
| `<openvox.major>-alpine` | `8-alpine` | Latest Alpine build for an OpenVox major version |
| `latest` | `latest` | Latest Ubuntu build from the `main` branch |
| `latest-alpine` | `latest-alpine` | Latest Alpine build from the `main` branch |

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

Example using an immutable container release:

```shell
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:

| Name | Usage / Default |
|---------------------------------------------| --------------- |
| __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_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`. Defaults to `false` |
| __CA_ENABLED__ | Whether or not this openvoxserver instance has a running CA (Certificate Authority) Defaults to `true` |
| __CA_HOSTNAME__ | The DNS hostname for the openvoxserver running the CA. Does nothing unless `CA_ENABLED=false` Defaults to `puppet` |
| __CA_PORT__ | The listening port of the CA. Does nothing unless `CA_ENABLED=false` Defaults to `8140` |
| __CA_TTL__ | CA expire date (in seconds or with suffix `s`, `m`, `h`, `d`, `y`) Defaults to `157680000` |
| __CERTNAME__ | The DNS name used on the servers SSL certificate - sets the `certname` in puppet.conf Defaults to unset. |
| __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": {...}}'` |
| __DNS_ALT_NAMES__ | Additional DNS names to add to the servers SSL certificate __Note__ only effective on initial run when certificates are generated |
| __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` |
| __INTERMEDIATE_CA__ | Allows to import an existing intermediate CA. Needs `INTERMEDIATE_CA_BUNDLE`, `INTERMEDIATE_CA_CHAIN` and `INTERMEDIATE_CA_KEY`. See [Puppet Intermediat CA](https://www.puppet.com/docs/puppet/latest/server/intermediate_ca.html) |
| __INTERMEDIATE_CA_BUNDLE__ | File path and name to the complete CA bundle (signing CA + Intermediate CA) |
| __INTERMEDIATE_CA_KEY__ | File path and name to the private CA key |
| __INTERMEDIATE_CRL_CHAIN__ | File path and name to the complete CA CRL chain |
| __OPENVOX_REPORTS__ | Sets `reports` in puppet.conf Defaults to `puppetdb` |
| __OPENVOX_STORECONFIGS__ | Sets `storeconfigs` in puppet.conf Defaults to `true` |
| __OPENVOX_STORECONFIGS_BACKEND__ | Sets `storeconfigs_backend` in puppet.conf Defaults to `puppetdb` |
| __OPENVOXDB_SERVER_URLS__ | The URL of the OpenVoxDB servers. This is used to connect to the OpenVoxDB server. Defaults to `https://openvoxdb:8081` Please note that within a compose file, you must provide all environment variables as Hash and not as Array! environment: `OPENVOXDB_SERVER_URLS: 'https://openvoxdb:8081'` |
| __OPENVOXSERVER_ENABLE_ENV_CACHE_DEL_API__ | Enable the puppet admin api endpoint via certificates to allow clearing environment caches Defaults to `true` |
| __OPENVOXSERVER_ENVIRONMENT_TIMEOUT__ | Configure the environment timeout Defaults to `unlimited` |
| __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_HOSTNAME__ | The DNS name used on the servers SSL certificate - sets the `server` in puppet.conf Defaults to unset. |
| __OPENVOXSERVER_JAVA_ARGS__ | Arguments passed directly to the JVM when starting the service Defaults to `-Xms1024m -Xmx1024m` |
| __OPENVOXSERVER_MAX_ACTIVE_INSTANCES__ | The maximum number of JRuby instances allowed Defaults to `1` |
| __OPENVOXSERVER_MAX_REQUESTS_PER_INSTANCE__ | The maximum HTTP requests a JRuby instance will handle in its lifetime (disable instance flushing) Defaults to `0` |
| __OPENVOXSERVER_PORT__ | The port of the openvoxserver Defaults to `8140` |
| __USE_OPENVOXDB__ | Whether to connect to puppetdb Sets `OPENVOX_REPORTS` to `log` and `OPENVOX_STORECONFIGS` to `false` if `OPENVOX_STORECONFIGS_BACKEND` is `puppetdb`. Defaults to `true` |

## 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:

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

or in compose:

```yaml
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 64604) 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:

```shell
-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:

```shell
-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:

```shell
-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](https://github.com/voxpupuli/container-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](https://github.com/voxpupuli/container-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`:

```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:

```shell
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.

```shell
podman exec openvox r10k deploy environment -mv
```

## How to Release the container

[see here](RELEASE.md)

## How to contribute

[see here](https://github.com/voxpupuli/crafty/blob/main/CONTRIBUTING.md)

container-openvoxserver

container-openvoxserver Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

container-openvoxserver

container-openvoxserver Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README