### Add Post-Startup Monitoring Script

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Creates a post-startup script to execute after the server starts. This example adds a monitoring script that echoes a success message.

```bash
cat > init-post-startup.sh << 'EOF'
#!/bin/bash
echo "Puppet Server started successfully"
# Custom monitoring, metric initialization, etc.
EOF

docker run -v ./init-post-startup.sh:/container-custom-entrypoint.d/post-startup/01-monitor.sh ghcr.io/openvoxproject/openvoxserver
```

--------------------------------

### Create Release Branch and Install Dependencies

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/RELEASE.md

Use this command sequence to create a new release branch, install necessary gems, and generate the changelog.

```shell
export RELEASE_VERSION="X.Y.Z"
git switch main
git pull --rebase
git switch -c release-v$RELEASE_VERSION

bundle config set --local path vendor/bundle
bundle config set --local with 'release'
bundle install

CHANGELOG_GITHUB_TOKEN="token_MC_tokenface" bundle exec rake changelog

git commit --all --message "Release v${RELEASE_VERSION}"
git push --set-upstream origin HEAD
```

--------------------------------

### post_startup_handler()

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/03-entry-point-scripts.md

Executes custom scripts located in the `/container-custom-entrypoint.d/post-startup/` directory after the Puppet Server process has been successfully started.

```APIDOC
## post_startup_handler

### Description
Executes custom scripts after the Puppet Server process has been forked and started.

### Behavior
Runs scripts from `/container-custom-entrypoint.d/post-startup/`.

### Called by
Main initialization, after Puppet Server is started.
```

--------------------------------

### r10k Configuration File Example

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/README.md

This YAML file configures r10k for code deployment. It specifies pool size, deployment generation options, cache directory, and the Git repository for environments.

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

```

--------------------------------

### Docker Compose for Service Discovery

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Example Docker Compose configuration demonstrating how services like OpenVoxServer and PuppetDB can discover each other using container names. This setup is crucial for enabling communication between different components of the OpenVoxServer ecosystem.

```yaml
services:
  puppet:
    image: ghcr.io/openvoxproject/openvoxserver:latest
  puppetdb:
    image: ghcr.io/openvoxproject/openvoxdb:latest

# Puppet Server connects to PuppetDB at: https://puppetdb:8081
```

--------------------------------

### Run OpenVox Server with r10k Configuration

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

This command starts the OpenVox Server container and mounts a local r10k configuration file into the container. This prepares the container to use r10k for code deployment.

```bash
docker run -v ./r10k.yaml:/etc/puppetlabs/r10k/r10k.yaml \
  ghcr.io/openvoxproject/openvoxserver:8.14.1
```

--------------------------------

### Run OpenVox Container with r10k Mount

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/README.md

This command starts the OpenVox container, mounting a local r10k configuration directory into the container. This is part of the less recommended method for deploying code.

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

```

--------------------------------

### Docker Compose Deployment with PuppetDB

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

A Docker Compose setup including PostgreSQL, PuppetDB, and OpenVox Server, demonstrating integration with a database backend.

```yaml
version: '3.9'
services:
  postgres:
    image: postgres:14
    environment:
      POSTGRES_PASSWORD: puppetdb
    volumes:
      - postgres-data:/var/lib/postgresql/data

  puppetdb:
    image: ghcr.io/openvoxproject/openvoxdb:8.14.1
    depends_on:
      - postgres
    ports:
      - "8081:8081"
    environment:
      POSTGRES_PASSWORD: puppetdb

  puppet:
    image: ghcr.io/openvoxproject/openvoxserver:8.14.1
    hostname: openvox
    depends_on:
      - puppetdb
    ports:
      - "8140:8140"
    environment:
      OPENVOXSERVER_HOSTNAME: openvox
      CERTNAME: openvox
      OPENVOXDB_SERVER_URLS: https://puppetdb:8081
      USE_OPENVOXDB: "true"
    volumes:
      - ./code:/etc/puppetlabs/code
      - puppet-ca:/etc/puppetlabs/puppetserver/ca

volumes:
  postgres-data:
  puppet-ca:
```

--------------------------------

### Run OpenVox Server Container with Podman

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/README.md

Example of running an immutable OpenVox Server container release using Podman. This command mounts a local code directory to the container and names the container 'openvox'.

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

--------------------------------

### Replace server URLs with sed

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/04-puppet-server-configuration.md

Use 'sed' for direct text replacement in configuration files, such as updating server URLs. This example demonstrates replacing the 'server_urls' line.

```bash
sed -i "s@^server_urls.*@server_urls = ${OPENVOXDB_SERVER_URLS}@" file.conf
```

--------------------------------

### Set Java Heap Size via Environment Variable

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Configure the Java Virtual Machine's heap size for the OpenVoxServer container using the OPENVOXSERVER_JAVA_ARGS environment variable. This example sets a high-performance configuration with a larger heap.

```bash
docker run \
  -e OPENVOXSERVER_JAVA_ARGS="-Xms2g -Xmx4g" \
  ghcr.io/openvoxproject/openvoxserver:latest
```

--------------------------------

### Get OpenVox Server Configuration Value

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/03-entry-point-scripts.md

Retrieves a specific configuration key's value after ensuring the cache is loaded. It uses `sed` to extract the value from the cache file.

```bash
config_get ssldir
# Returns: /etc/puppetlabs/puppet/ssl
```

--------------------------------

### Deploy Code using r10k within Container

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/README.md

This command executes r10k within the running OpenVox container to deploy environment code. It is used after the container has been started with the r10k configuration mounted.

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

```

--------------------------------

### Tune Puppet Server Java Memory Arguments

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/04-puppet-server-configuration.md

Modify the JAVA_ARGS environment variable to tune Java VM memory settings for Puppet server. This example sets initial heap size to 512MB, maximum heap size to 4GB, and enables the G1 Garbage Collector.

```bash
JAVA_ARGS="-Xms512m -Xmx4g -XX:+UseG1GC"
```

--------------------------------

### Deploy Controlrepo with Docker Compose

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Configures volume mounts for Puppet code, CA, and SSL certificates within a docker-compose setup. Named volumes are used for CA and SSL persistence.

```yaml
services:
  puppet:
    image: ghcr.io/openvoxproject/openvoxserver:latest
    volumes:
      - ./controlrepo:/etc/puppetlabs/code
      - puppet-ca:/etc/puppetlabs/puppetserver/ca
      - puppet-ssl:/etc/puppetlabs/puppet/ssl

volumes:
  puppet-ca:
  puppet-ssl:
```

--------------------------------

### CSR Attributes Environment Variable Example

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/04-puppet-server-configuration.md

Example of the JSON string format for the CSR_ATTRIBUTES environment variable.

```bash
CSR_ATTRIBUTES='{"custom_attributes": {"challengePassword": "secret"}, "extension_requests": {"pp_project": "prod"}}'
```

--------------------------------

### Add Custom Pre-Startup Hook

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Mounts a local directory containing custom pre-default initialization scripts into the container. Ensure scripts are executable.

```bash
docker run -v ./custom/pre-default:/container-custom-entrypoint.d/pre-default ghcr.io/openvoxproject/openvoxserver
```

--------------------------------

### Initialize Configuration from Templates

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/03-entry-point-scripts.md

This script initializes configuration from template files on the first container run. It copies pristine template files to the Puppet configuration directory if they do not already exist, preserving manual edits across restarts.

```bash
#!/bin/bash

set -e

# Source common functions
. /opt/puppetlabs/bin/config_lib.sh

# Check if template files exist in /var/tmp/puppet/
if ls /var/tmp/puppet/*.conf > /dev/null 2>&1 || ls /var/tmp/puppet/*.yaml > /dev/null 2>&1; then
  echo "Initializing configuration from templates..."
  # Copy template files if they don't exist
  config_copy_template "/var/tmp/puppet/auth.conf" "$confdir/auth.conf"
  config_copy_template "/var/tmp/puppet/hiera.yaml" "$confdir/hiera.yaml"
  config_copy_template "/var/tmp/puppet/puppet.conf" "$confdir/puppet.conf"
  config_copy_template "/var/tmp/puppet/puppetdb.conf" "$confdir/puppetdb.conf"

  # Handle vendored JRuby gems upgrade
  if [ -d "/var/tmp/puppetserver/vendored-jruby-gems" ]; then
    echo "Upgrading vendored JRuby gems..."
    cp -a /var/tmp/puppetserver/vendored-jruby-gems "/opt/puppetlabs/server/data/puppetserver/"
    rm -rf "/var/tmp/puppetserver/vendored-jruby-gems"
  fi
else
  echo "No template files found in /var/tmp/puppet/. Skipping initialization."
fi

```

--------------------------------

### Add Graceful Shutdown Handler

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Creates a shutdown handler script to perform cleanup operations before the container terminates. This example echoes a cleanup message.

```bash
cat > shutdown-cleanup.sh << 'EOF'
#!/bin/bash
echo "Cleaning up resources before shutdown"
# Clean up temporary files, notify services, etc.
EOF

docker run -v ./shutdown-cleanup.sh:/container-custom-entrypoint.d/sigterm-handler/01-cleanup.sh ghcr.io/openvoxproject/openvoxserver
```

--------------------------------

### HOCON structure for auth.conf rules

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/04-puppet-server-configuration.md

An example of the HOCON structure for defining authorization rules in `auth.conf`. This defines rules for matching requests and determining access.

```hocon
authorization: {
  version: 1
  rules: [
    {
      match-request: {
        path: "/puppet/v3/catalog/([^/]+)"
        type: path
        method: [get]
      }
      allow: ["$1"]
      sort-order: 500
      name: "catalog"
    }
  ]
}
```

--------------------------------

### Configure JVM Arguments

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/02-configuration.md

Specify arguments passed directly to the Java Virtual Machine at startup. This is useful for memory tuning, garbage collection, and debugging.

```bash
OPENVOXSERVER_JAVA_ARGS="-Xms1024m -Xmx2048m -XX:+UseG1GC"
```

--------------------------------

### Basic Docker CLI Deployment

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

Run a basic OpenVox Server container with port mapping and code volume mount.

```bash
docker run --name openvox \
  --hostname openvox \
  -p 8140:8140 \
  -v /path/to/code:/etc/puppetlabs/code \
  ghcr.io/openvoxproject/openvoxserver:8.14.1
```

--------------------------------

### Set Storeconfigs Backend

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/02-configuration.md

Define the backend service for storing configuration state. 'puppetdb' is the standard and recommended choice.

```bash
OPENVOX_STORECONFIGS_BACKEND=puppetdb
```

--------------------------------

### Load OpenVox Server Configuration Cache

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/03-entry-point-scripts.md

Initializes the configuration cache if it doesn't exist. This function is called by `config_get` before reading any configuration values.

```bash
config_load
```

--------------------------------

### config_load()

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/03-entry-point-scripts.md

Initializes the configuration cache by checking for its existence and populating it with `puppet config print` output if it doesn't exist. It caches various SSL and configuration directory paths.

```APIDOC
## config_load()

### Description
Initializes the configuration cache. If the cache exists and is non-empty, it returns immediately. Otherwise, it creates the cache directory and populates it with output from `puppet config print`, caching specific values like `confdir`, `ssldir`, `certname`, etc.

### Behavior
- Checks for existing cache.
- Creates and populates cache if it does not exist.
- Caches: `confdir`, `ssldir`, `cadir`, `certname`, `csr_attributes`, `dns_alt_names`, `hostcert`, `hostprivkey`, `localcacert`, `hostcrl`, `cacert`.

### Cache Location
`/run/openvox/config-lib-cache`

### Called By
`config_get` before any read operation.
```

--------------------------------

### Run Container with SELinux Context for Bind Mounts

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

When using bind mounts with Podman and SELinux is enabled, use the ':Z' flag to ensure correct SELinux context for the mounted volume. This is an alternative to using named volumes, which manage permissions automatically.

```bash
podman run -v ./ca:/etc/puppetlabs/puppetserver/ca:Z ghcr.io/openvoxproject/openvoxserver:8.14.1
```

--------------------------------

### Run OpenVox Server with Bind Mount for Code

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

This command uses a bind mount to link a host directory to the container's code directory. This is suitable for development environments where direct host access to code is needed.

```bash
docker run -v /host/path:/etc/puppetlabs/code ghcr.io/openvoxproject/openvoxserver:8.14.1
```

--------------------------------

### Run OpenVox Server Container

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Basic command to run the OpenVox Server container. Replace VERSION with the desired tag.

```bash
docker run ghcr.io/openvoxproject/openvoxserver:VERSION
```

--------------------------------

### Configure Report Storage and Stored Configuration Backend

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/03-entry-point-scripts.md

Configures report storage and the stored configuration backend. Uses environment variables like OPENVOX_STORECONFIGS_BACKEND, OPENVOX_STORECONFIGS, OPENVOX_REPORTS, and USE_OPENVOXDB.

```bash
#!/bin/bash

# Configure report storage and stored configuration backend.
# Environment variables:
# OPENVOX_STORECONFIGS_BACKEND (default: puppetdb)
# OPENVOX_STORECONFIGS (default: true)
# OPENVOX_REPORTS (default: puppetdb)
# USE_OPENVOXDB (default: true)

# Configuration file: /etc/puppetlabs/puppet/puppet.conf
# Settings modified: server/ section

# Behavior:
# 1. If OPENVOX_STORECONFIGS_BACKEND is set: Updates server/storeconfigs_backend
# 2. If OPENVOX_STORECONFIGS is set: Updates server/storeconfigs
# 3. If OPENVOX_REPORTS is set: Updates server/reports
# 4. If USE_OPENVOXDB=false: Resets defaults unless already customized:
#    - If reports is still puppetdb: Changes to log
#    - If storeconfigs_backend is still puppetdb: Sets storeconfigs to false

# Uses: config_set from config_lib.sh

if [ -n "$OPENVOX_STORECONFIGS_BACKEND" ]; then
    config_set server storeconfigs_backend "$OPENVOX_STORECONFIGS_BACKEND"
fi

if [ -n "$OPENVOX_STORECONFIGS" ]; then
    config_set server storeconfigs "$OPENVOX_STORECONFIGS"
fi

if [ -n "$OPENVOX_REPORTS" ]; then
    config_set server reports "$OPENVOX_REPORTS"
fi

if [ "$USE_OPENVOXDB" = 'false' ]; then
    if [ "$(config_get server reports)" = 'puppetdb' ]; then
        config_set server reports log
    fi
    if [ "$(config_get server storeconfigs_backend)" = 'puppetdb' ]; then
        config_set server storeconfigs false
    fi
fi
```

--------------------------------

### Mount SSL and CA Directories for Rootless Podman

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/README.md

When using rootless Podman, mount the SSL and CA directories to avoid permission issues. The container attempts to correct ownership by default.

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

--------------------------------

### Deploy Controlrepo with Docker

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Mounts a local controlrepo directory into the container for Puppet code. Use this to manage your Puppet modules and configurations externally.

```bash
docker run \
  -v /path/to/controlrepo:/etc/puppetlabs/code \
  ghcr.io/openvoxproject/openvoxserver:latest
```

--------------------------------

### Run OpenVox Server with Direct Volume Mount for Control Repository

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

This command directly mounts a local directory containing Puppet code into the OpenVox Server container. This is a simple method for deploying static code directly from a local repository.

```bash
docker run -v ./controlrepo:/etc/puppetlabs/code \
  ghcr.io/openvoxproject/openvoxserver:8.14.1
```

--------------------------------

### Docker CLI Deployment with Custom Environment

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

Configure OpenVox Server with custom environment variables for hostname, certificate name, and CA enablement, including persistent CA storage and code volume mount.

```bash
docker run --name openvox \
  --hostname openvox \
  -e OPENVOXSERVER_HOSTNAME=puppet.example.com \
  -e CERTNAME=puppet.example.com \
  -e CA_ENABLED=true \
  -v puppet-ca:/etc/puppetlabs/puppetserver/ca \
  -v /path/to/code:/etc/puppetlabs/code \
  ghcr.io/openvoxproject/openvoxserver:8.14.1
```

--------------------------------

### Container Initialization Handler Directories

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Defines the directory structure for custom initialization scripts executed at different phases of the container lifecycle. Includes deprecated and current directory names.

```bash
/container-custom-entrypoint.d/
├── pre-default/              # Run before default scripts
├── *.sh                       # Run after default, before server start
├── post-startup/             # Run after server starts
├── sigterm-handler/          # Run on shutdown signal
└── post-execution/           # Run after server exits

**Deprecated (still supported):**
/docker-custom-entrypoint.d/   # Deprecated, use /container-custom-entrypoint.d/
```

--------------------------------

### Backup Configuration Files

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

This command backs up configuration files from a specified volume to a tar.gz archive. Adjust the volume and path as needed.

```bash
# Backup puppet.conf and related
docker run --rm -v puppet-ssl:/data \
  -v $(pwd):/backup \
  ubuntu tar czf /backup/puppet-config.tar.gz -C /data ..
```

--------------------------------

### Enable Graphite Metrics Export

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/03-entry-point-scripts.md

Enables Graphite metrics export for the server. Requires CERTNAME, OPENVOXSERVER_GRAPHITE_HOST, and OPENVOXSERVER_GRAPHITE_PORT to be set when enabled. Generates a metrics.conf file.

```bash
#!/bin/bash

# Enable Graphite metrics export.
# Environment variables:
# OPENVOXSERVER_GRAPHITE_EXPORTER_ENABLED (default: false)
# CERTNAME (Required if enabled)
# OPENVOXSERVER_GRAPHITE_HOST (default: exporter)
# OPENVOXSERVER_GRAPHITE_PORT (default: 9109)

# Configuration file generated: /etc/puppetlabs/puppetserver/conf.d/metrics.conf

# Behavior:
# - Validates that CERTNAME is set (exits with code 1 if missing when feature is enabled)
# - Validates that both GRAPHITE_HOST and GRAPHITE_PORT are set (exits with code 99 if missing)
# - Processes template file 84-metrics.conf.tmpl with sed substitutions:
#   - GRAPHITE_HOST -> OPENVOXSERVER_GRAPHITE_HOST
#   - GRAPHITE_PORT -> OPENVOXSERVER_GRAPHITE_PORT
#   - server-id: localhost -> server-id: ${CERTNAME}

# Template location: openvoxserver/files/container-entrypoint.d/84-metrics.conf.tmpl

# Exit codes:
# - 0 - Success
# - 1 - CERTNAME not set when graphite exporter enabled
# - 99 - Graphite host or port not set

if [ "$OPENVOXSERVER_GRAPHITE_EXPORTER_ENABLED" = "true" ]; then
    if [ -z "$CERTNAME" ]; then
        echo "Error: CERTNAME must be set when OPENVOXSERVER_GRAPHITE_EXPORTER_ENABLED is true."
        exit 1
    fi

    GRAPHITE_HOST=${OPENVOXSERVER_GRAPHITE_HOST:-exporter}
    GRAPHITE_PORT=${OPENVOXSERVER_GRAPHITE_PORT:-9109}

    if [ -z "$GRAPHITE_HOST" ] || [ -z "$GRAPHITE_PORT" ]; then
        echo "Error: OPENVOXSERVER_GRAPHITE_HOST and OPENVOXSERVER_GRAPHITE_PORT must be set when OPENVOXSERVER_GRAPHITE_EXPORTER_ENABLED is true."
        exit 99
    fi

    sed -e "s/GRAPHITE_HOST/$GRAPHITE_HOST/g" \
        -e "s/GRAPHITE_PORT/$GRAPHITE_PORT/g" \
        -e "s/server-id: localhost/server-id: $CERTNAME/g" \
        /openvoxserver/files/container-entrypoint.d/84-metrics.conf.tmpl > /etc/puppetlabs/puppetserver/conf.d/metrics.conf
fi
```

--------------------------------

### pre_execution_handler()

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/03-entry-point-scripts.md

Handles the pre-execution phase of the container initialization. This includes running custom pre-default scripts, deprecated docker-entrypoint.d scripts, default container-entrypoint.d scripts, and main custom handler scripts.

```APIDOC
## pre_execution_handler

### Description
Manages the execution of scripts before the main Puppet Server process starts. It orchestrates the running of various custom and default entry point scripts in a specific order.

### Execution order
1. Run pre-default custom handler scripts.
2. Run deprecated docker-entrypoint.d scripts (if directory exists).
3. Run default container-entrypoint.d scripts.
4. Run main custom handler scripts.

### Called by
Main initialization process.
```

--------------------------------

### Check Container Logs

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

View logs for a specific container. Use the -f flag to follow the logs in real-time.

```bash
docker logs <container-name>
docker logs -f <container-name>  # Follow
```

--------------------------------

### Use Named Volume for CA Persistence with Rootless Podman

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/README.md

For easier permission management and migration, use a named volume for the CA directory. Podman handles permissions automatically with named volumes.

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

--------------------------------

### Run OpenVox Server Container

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/README.md

Basic command to run the OpenVox Server container. The container is named 'openvox' and uses the '8.13.0' tag.

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

--------------------------------

### Multi-Container Deployment with Load Balancing

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Set up a multi-container OpenVoxServer deployment using Docker Compose, including a central Certificate Authority (CA) server, multiple compile servers, and a load balancer. This configuration enables high availability and scalability.

```yaml
services:
  puppet-ca:
    image: ghcr.io/openvoxproject/openvoxserver:latest
    environment:
      CA_ENABLED: "true"
    volumes:
      - puppet-ca-data:/etc/puppetlabs/puppetserver/ca
      - puppet-code:/etc/puppetlabs/code

  puppet-compile-1:
    image: ghcr.io/openvoxproject/openvoxserver:latest
    environment:
      CA_ENABLED: "false"
      CA_HOSTNAME: puppet-ca
    volumes:
      - puppet-code:/etc/puppetlabs/code

  puppet-compile-2:
    image: ghcr.io/openvoxproject/openvoxserver:latest
    environment:
      CA_ENABLED: "false"
      CA_HOSTNAME: puppet-ca
    volumes:
      - puppet-code:/etc/puppetlabs/code

  load-balancer:
    image: haproxy:latest
    ports:
      - "8140:8140"
    # Route to puppet-compile-1 and puppet-compile-2

volumes:
  puppet-ca-data:
  puppet-code:
```

--------------------------------

### Run Custom Entry Point Handler Scripts

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/03-entry-point-scripts.md

Executes shell scripts from custom handler directories. It supports running scripts from a specified handler subdirectory or the root directory if no handler name is provided. All matching .sh files are executed in sort order.

```bash
run_custom_handler pre-default      # Run /container-custom-entrypoint.d/pre-default/*.sh
```

```bash
run_custom_handler post-startup     # Run /container-custom-entrypoint.d/post-startup/*.sh
```

```bash
run_custom_handler                  # Run /container-custom-entrypoint.d/*.sh
```

--------------------------------

### Pull OpenVox Server from Docker Hub

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

These commands demonstrate how to pull the OpenVox Server image from Docker Hub. The second command uses the implicit default registry.

```bash
docker pull docker.io/voxpupuli/openvoxserver:8.14.1
docker pull voxpupuli/openvoxserver:8.14.1  # Implicit docker.io
```

--------------------------------

### Product-Specific Settings in product.conf

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/04-puppet-server-configuration.md

Configure product-specific settings like update checks. This file is modified during container build.

```hocon
product: {
  check-for-updates: false
}
```

--------------------------------

### Create Named Docker Volume for Puppet SSL

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

Use this command to create a named Docker volume for storing Puppet SSL certificates and keys. This is recommended for portability and easier backups.

```bash
docker volume create puppet-ssl
```

--------------------------------

### Docker CLI Deployment with CA Persistence

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

Deploy OpenVox Server with persistent storage for CA and SSL certificates, along with code volume mount.

```bash
docker run --name openvox \
  --hostname openvox \
  -v puppet-ca:/etc/puppetlabs/puppetserver/ca \
  -v puppet-ssl:/etc/puppetlabs/puppet/ssl \
  -v /path/to/code:/etc/puppetlabs/code \
  ghcr.io/openvoxproject/openvoxserver:8.14.1
```

--------------------------------

### Enable Configuration State Storage

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/02-configuration.md

Control whether the server stores configuration state from agents. Enabling this allows querying exported resources and cross-node dependencies.

```bash
OPENVOX_STORECONFIGS=true
```

--------------------------------

### Run OpenVox Server with Custom Code Mount

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/README.md

Command to run the OpenVox Server container and mount a local directory containing custom Puppet code to '/etc/puppetlabs/code' inside the container.

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

--------------------------------

### Run OpenVox Server with Named Volumes

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

This command runs the OpenVox Server container, mounting the previously created named volumes for CA and SSL data. This ensures persistence and portability of critical server configurations.

```bash
docker run -v puppet-ca:/etc/puppetlabs/puppetserver/ca ghcr.io/openvoxproject/openvoxserver:8.14.1
```

--------------------------------

### Supported Platforms Configuration

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

Defines the target architectures for building container images. This configuration is used by the build matrix to ensure compatibility across different environments.

```yaml
platforms:
  - linux/amd64
  - linux/arm64
  - linux/arm/v7
```

--------------------------------

### Backup and Restore Named Volume

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

Use these commands to back up a named volume to a tar.gz archive and restore it. Ensure the volume is mounted correctly.

```bash
# Backup named volume
docker run --rm -v puppet-ca:/data \
  -v $(pwd):/backup \
  ubuntu tar czf /backup/puppet-ca.tar.gz -C /data .

# Restore from backup
docker run --rm -v puppet-ca:/data \
  -v $(pwd):/backup \
  ubuntu tar xzf /backup/puppet-ca.tar.gz -C /data
```

--------------------------------

### Relabel Host Directory for Rootless Podman with SELinux

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/README.md

If permission issues persist with rootless Podman, use the ':Z' flag to relabel the host directory. This is particularly useful when SELinux is enabled.

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

--------------------------------

### Minimal Docker Compose Deployment

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

A minimal Docker Compose configuration for OpenVox Server, specifying image, hostname, port, environment variables, and volume mounts.

```yaml
version: '3.9'
services:
  puppet:
    image: ghcr.io/openvoxproject/openvoxserver:8.14.1
    hostname: openvox
    ports:
      - "8140:8140"
    environment:
      OPENVOXSERVER_HOSTNAME: openvox
      CERTNAME: openvox
      CA_ENABLED: "true"
    volumes:
      - ./code:/etc/puppetlabs/code
      - puppet-ca:/etc/puppetlabs/puppetserver/ca
      - puppet-ssl:/etc/puppetlabs/puppet/ssl

volumes:
  puppet-ca:
  puppet-ssl:
```

--------------------------------

### Run Container with Named Volume for CA in Rootless Podman

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Mounts a named volume for CA persistence in a rootless Podman environment. This leverages automatic ownership fixing for the 'puppet' user (UID 1001).

```bash
podman run \
  -v puppet-ca:/etc/puppetlabs/puppetserver/ca \
  ghcr.io/openvoxproject/openvoxserver:latest
```

--------------------------------

### Enable Graphite Exporter

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/02-configuration.md

Set this variable to 'true' to enable sending Puppet Server metrics to a Graphite server. Requires CERTNAME, OPENVOXSERVER_GRAPHITE_HOST, and OPENVOXSERVER_GRAPHITE_PORT to be set.

```bash
OPENVOXSERVER_GRAPHITE_EXPORTER_ENABLED=true
```

--------------------------------

### config_get()

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/03-entry-point-scripts.md

Retrieves a configuration value from the cache. It first ensures the cache is loaded by calling `config_load` and then uses `sed` to extract the value associated with the provided key.

```APIDOC
## config_get() <key>

### Description
Retrieves a configuration value from the cache. This function first ensures the configuration cache is loaded by calling `config_load` and then extracts the value for the specified key using `sed`.

### Parameters
#### Path Parameters
- **key** (String) - Required - Configuration key name (e.g., `certname`, `ssldir`).

### Returns
The configuration value as a string.

### Behavior
- Calls `config_load` to ensure cache is present.
- Uses `sed` to extract the value for the given key from the cache file.

### Example
```bash
config_get ssldir
# Returns: /etc/puppetlabs/puppet/ssl
```
```

--------------------------------

### Configure PuppetDB Server URLs

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/02-configuration.md

Specify the URL(s) for the PuppetDB server(s). This is used for report storage and querying. Multiple URLs can be provided as a comma-separated list.

```bash
OPENVOXDB_SERVER_URLS=https://openvoxdb:8081
```

```bash
OPENVOXDB_SERVER_URLS=https://puppetdb1:8081,https://puppetdb2:8081
```

--------------------------------

### Enable PuppetDB Integration

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/02-configuration.md

Master control for PuppetDB integration. Setting this to 'false' will automatically set reports to 'log' and storeconfigs to 'false' if the backend is 'puppetdb'.

```bash
USE_OPENVOXDB=true
```

--------------------------------

### OpenVox Server Version Pinning in Containerfile

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/06-build-and-deployment.md

This directive in the Containerfile specifies the version of OpenVox Server to be used. Renovate automatically updates this value.

```dockerfile
# renovate: datasource=custom.voxpupuli-artifacts depName=openvox-server
ARG OPENVOXSERVER_VERSION=8.14.1
```

--------------------------------

### Docker Compose with Custom Network

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Illustrates how to define and use a custom Docker bridge network for the OpenVoxServer container. This allows for more controlled network isolation and communication within your containerized environment.

```yaml
services:
  puppet:
    image: ghcr.io/openvoxproject/openvoxserver:latest
    networks:
      - puppet-network

networks:
  puppet-network:
    driver: bridge
```

--------------------------------

### PuppetDB Connection Configuration in puppetdb.conf

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/04-puppet-server-configuration.md

Configure the connection to PuppetDB, including server URLs and error handling. Modified by a shell script.

```ini
[main]
server_urls = https://puppetdb:8081
soft_write_failure = true
```

--------------------------------

### Configure PuppetDB Server URL

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/03-entry-point-scripts.md

This script configures the PuppetDB server URL in puppetdb.conf. It only executes if the OPENVOXDB_SERVER_URLS environment variable is set, using sed to update the server_urls setting.

```bash
#!/bin/bash

set -e

# Source common functions
. /opt/puppetlabs/bin/config_lib.sh

if [ -n "$OPENVOXDB_SERVER_URLS" ]; then
  echo "Configuring PuppetDB server URLs..."
  config_set "main/server_urls" "$OPENVOXDB_SERVER_URLS"
  echo "PuppetDB server URLs configured."
else
  echo "OPENVOXDB_SERVER_URLS environment variable not set. Skipping PuppetDB configuration."
fi

```

--------------------------------

### Tag and Push Release

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/RELEASE.md

After merging the release branch, use these commands to tag the release and push the tags to the remote repository.

```shell
git switch main
git pull --rebase
git tag v$RELEASE_VERSION -m "v$RELEASE_VERSION"
git push --tags
```

--------------------------------

### Enable Certificate Authority Service

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/02-configuration.md

Set CA_ENABLED to true to enable the Certificate Authority service. If set to false, the instance will act as a compiler connecting to a remote CA.

```bash
CA_ENABLED=true
```

--------------------------------

### Configure Intermediate CA Bundle Path

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/02-configuration.md

Set INTERMEDIATE_CA_BUNDLE to the file path of the complete CA certificate bundle when using an intermediate CA.

```bash
INTERMEDIATE_CA_BUNDLE=/etc/puppetlabs/intermediate/ca.pem
```

--------------------------------

### File Serving Endpoints

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Endpoints for serving files from modules and accessing file bucket storage.

```APIDOC
## GET /puppet/v3/file_content/<module>/<path>

### Description
Serves files from modules.

### Method
GET

### Endpoint
/puppet/v3/file_content/<module>/<path>

### Parameters
#### Path Parameters
- **module** (string) - Required - The name of the module.
- **path** (string) - Required - The path to the file within the module.
```

```APIDOC
## GET /puppet/v3/file_bucket_file/...

### Description
Provides access to file bucket storage.

### Method
GET

### Endpoint
/puppet/v3/file_bucket_file/...
```

--------------------------------

### Configure Hiera Configuration File Path

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/03-entry-point-scripts.md

This script configures the Hiera configuration file path. It uses the HIERACONFIG environment variable, defaulting to '$confdir/hiera.yaml', to set the 'server/hiera_config' setting in puppet.conf. The default value is a literal string that Puppet expands at runtime.

```bash
#!/bin/bash

set -e

# Source common functions
. /opt/puppetlabs/bin/config_lib.sh

HIERACONFIG=${HIERACONFIG:-$confdir/hiera.yaml}

echo "Setting Hiera config path to '$HIERACONFIG'..."
config_set "server/hiera_config" "$HIERACONFIG"

echo "Hiera config path set to '$HIERACONFIG'."

```

--------------------------------

### Catalog Endpoint

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Endpoint for compiling Puppet catalogs for agents.

```APIDOC
## POST /puppet/v3/catalog/<hostname>

### Description
Compiles Puppet catalogs for agents.

### Method
POST

### Endpoint
/puppet/v3/catalog/<hostname>

### Parameters
#### Path Parameters
- **hostname** (string) - Required - The hostname of the agent for which to compile the catalog.

### Authentication
Client certificate
```

--------------------------------

### Persist CA Data with Podman

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/README.md

Use this command to run the OpenVox Server container and persist the CA directory. This prevents key and certificate changes on restart.

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

--------------------------------

### Set Environment Variables from a File with Docker

Source: https://github.com/openvoxproject/container-openvoxserver/blob/main/_autodocs/05-container-interface.md

Use the --env-file flag to load environment variables from a specified file when running a Docker container.

```bash
docker run --env-file ./puppetserver.env ghcr.io/openvoxproject/openvoxserver
```