### Docker Quickstart for Puppetboard

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Run Puppetboard with Docker for a quick setup. Basic setup requires only the PuppetDB host and a secret key. Full SSL setup involves mounting configuration files and enabling specific views.

```bash
docker run -it \
  -e PUPPETDB_HOST=localhost \
  -e PUPPETDB_PORT=8080 \
  -e SECRET_KEY=$(ruby -e "require 'securerandom'; puts SecureRandom.hex(32)") \
  --net=host \
  ghcr.io/voxpupuli/puppetboard
```

```bash
docker run -it \
  -v /etc/puppetboard:/etc/puppetboard:ro \
  -e PUPPETDB_HOST=puppet.example.com \
  -e PUPPETDB_PORT=8081 \
  -e PUPPETDB_SSL_VERIFY=false \
  -e PUPPETDB_KEY=/etc/puppetboard/key.pem \
  -e PUPPETDB_CERT=/etc/puppetboard/cert.pem \
  -e ENABLE_CATALOG=true \
  -e ENABLE_CLASS=true \
  -e DEFAULT_ENVIRONMENT='*' \
  -e SECRET_KEY=my-long-random-secret \
  --net=host \
  ghcr.io/voxpupuli/puppetboard
```

```bash
docker build -t puppetboard .
```

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

### Install Prerequisites and Puppetboard

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Debian-Jessie.md

Installs necessary packages like python-pip and git, creates a directory, clones the Puppetboard repository, and installs Puppetboard using pip.

```bash
$ apt-get install python-pip git

$ mkdir /opt/voxpupuli-puppetboard/
$ cd /opt/voxpupuli-puppetboard/
$ git clone https://github.com/voxpupuli/puppetboard
$ cd /opt/voxpupuli-puppetboard/puppetboard
$ pip install puppetboard

```

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

### Start uWSGI for Puppetboard

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md

Use this command to start the uWSGI application server for Puppetboard. Ensure the settings file is correctly configured and owned by the uWSGI user.

```bash
$ uwsgi --socket :9090 --wsgi-file /var/www/puppetboard/wsgi.py
```

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

### Install Development Dependencies

Source: https://github.com/voxpupuli/puppetboard/blob/master/README.md

Install project requirements and testing dependencies, including type checking with mypy.

```bash
pip install --upgrade wheel setuptools
pip install -e .
pip install --upgrade -r requirements-test.txt
mypy --install-types --non-interactive puppetboard/ test/
```

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

### Configure Bundler and Install Dependencies

Source: https://github.com/voxpupuli/puppetboard/blob/master/RELEASE.md

Configure Bundler to install gems locally and with the 'release' group, then install them. This is part of the release process on a fork.

```shell
bundle config set --local path .vendor
bundle config set --local with 'release'
bundle install
```

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

### Manual Installation and Configuration

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Install Puppetboard using pip and configure it via a settings file. Ensure to set the PUPPETBOARD_SETTINGS environment variable before running the Flask application.

```bash
python -m venv venv
. venv/bin/activate
pip install puppetboard
```

```bash
cat > /etc/puppetboard/settings.py <<'EOF'
PUPPETDB_HOST = 'puppetdb.example.com'
PUPPETDB_PORT = 8080
SECRET_KEY = 'replace-with-long-random-string'
DEFAULT_ENVIRONMENT = 'production'
ENABLE_CATALOG = True
ENABLE_CLASS  = True
LOGLEVEL = 'info'
EOF
```

```bash
export PUPPETBOARD_SETTINGS=/etc/puppetboard/settings.py
flask run --host 0.0.0.0 --port 8080
```

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

### Puppetboard Production Settings Example

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Example configuration for a production environment, covering PuppetDB connection details, application behavior, feature flags, and display options. These settings can be overridden via `PUPPETBOARD_SETTINGS` or environment variables.

```python
# /etc/puppetboard/settings.py — production example

# PuppetDB connection
PUPPETDB_HOST        = 'puppetdb.example.com'
PUPPETDB_PORT        = 8081
PUPPETDB_PROTO       = 'https'
PUPPETDB_SSL_VERIFY  = True
PUPPETDB_KEY         = '/etc/puppetboard/key.pem'
PUPPETDB_CERT        = '/etc/puppetboard/cert.pem'
PUPPETDB_TIMEOUT     = 30          # seconds; increase for large environments

# App behavior
SECRET_KEY           = 'replace-with-long-random-string-same-across-all-replicas'
DEFAULT_ENVIRONMENT  = 'production' # or '*' for all environments
UNRESPONSIVE_HOURS   = 2           # hours before a node is "unreported"
LOGLEVEL             = 'info'      # debug | info | warning | critical

# Feature flags
ENABLE_QUERY         = True        # show Query tab
ENABLE_CATALOG       = True        # show Catalogs tab (resource-heavy)
ENABLE_CLASS         = True        # show Classes tab

# Query page
ENABLED_QUERY_ENDPOINTS = ['pql', 'nodes', 'facts', 'reports', 'events']
QUERY_PRESETS_FILE   = '/etc/puppetboard/query_presets.yaml'

# Display
PAGE_TITLE           = 'Puppetboard'
SHOW_ERROR_AS        = 'friendly'  # or 'raw'
CODE_PREFIX_TO_REMOVE = '/etc/puppetlabs/code/environments(/.*?/modules)?'
LOCALISE_TIMESTAMP   = True
REFRESH_RATE         = 30          # seconds, overview auto-refresh
GRAPH_TYPE           = 'pie'       # or 'donut'
WITH_EVENT_NUMBERS   = True        # False gives performance benefit in large envs
OFFLINE_MODE         = False       # True to serve JS/CSS from local server

# Table pagination
NORMAL_TABLE_COUNT   = 100
LITTLE_TABLE_COUNT   = 10
TABLE_COUNT_SELECTOR = [10, 20, 50, 100, 500]
```

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

### Endpoint-Specific Queries for Fact Names and Environments

Source: https://github.com/voxpupuli/puppetboard/blob/master/QUERY_PRESETS.md

Examples for retrieving all fact names and environments. Use 'raw_json: true' to get the raw API response.

```yaml
# Get all fact names as JSON
- name: "All Fact Names"
  description: "List all available fact names"
  query: ""
  endpoint: fact-names
  raw_json: true

# Get all environments
- name: "All Environments"
  description: "List all Puppet environments"
  query: ""
  endpoint: environments
  raw_json: true
```

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

### PQL Query Examples

Source: https://github.com/voxpupuli/puppetboard/blob/master/QUERY_PRESETS.md

Demonstrates various PQL queries including simple node listing, filtering by OS, aggregation, and event filtering.

```yaml
# Simple node query
- name: "All Nodes"
  query: 'nodes[certname, catalog_timestamp, facts_timestamp] {}'
  endpoint: pql

# Filtered query
- name: "Ubuntu Nodes"
  query: 'inventory[certname, facts.os.release.full] { facts.os.name = "Ubuntu" }'
  endpoint: pql

# Aggregation query
- name: "Node Count by Environment"
  query: |
    nodes[count(), catalog_environment] {
      group by catalog_environment
    }
  endpoint: pql

# Filtered query with condition
- name: "Failed Events"
  query: |
    events[certname, resource_type, message, timestamp] {
      status = "failure"
    }
  endpoint: pql
```

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

### GET / and GET /<env>/ — Overview / Index

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Displays the dashboard, including node status, summary statistics, and a list of non-unchanged nodes.

```APIDOC
## GET / and GET /<env>/ — Overview / Index

### Description
Displays the dashboard: node status pie-chart, summary statistics (total nodes, resources, avg resources/node), and a list of non-unchanged nodes.

### Method
GET

### Endpoint
/ or /<env>/

### Example
```bash
# Default environment (production)
curl http://localhost:8080/

# Specific environment
curl http://localhost:8080/staging/

# All environments
curl http://localhost:8080/%2A/
```
```

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

### Install Puppetboard Manually with Virtualenv

Source: https://github.com/voxpupuli/puppetboard/blob/master/README.md

Install Puppetboard in a dedicated Python virtual environment using pip. This method is recommended for manual deployments.

```bash
virtualenv -p python3 venv
. venv/bin/activate
pip install puppetboard
```

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

### AST Query Example for Nodes Endpoint

Source: https://github.com/voxpupuli/puppetboard/blob/master/QUERY_PRESETS.md

Shows how to query the nodes endpoint using an Abstract Syntax Tree (AST) format. Puppetboard automatically adds brackets if needed.

```yaml
# AST query for nodes endpoint
- name: "AST - Ubuntu Nodes"
  description: "Find Ubuntu nodes using AST query"
  query: '"=", "facts.os.name", "Ubuntu"'
  endpoint: nodes
  raw_json: false
```

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

### Run Gunicorn for Puppetboard

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md

Command to start Gunicorn to serve the Puppetboard application. Ensure you are in the correct directory and the environment variable PUPPETBOARD_SETTINGS is set.

```bash
$ cd /usr/local/lib/pythonX.Y/dist-packages/puppetboard
$ gunicorn -b 127.0.0.1:9090 puppetboard.app:app
```

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

### Query PuppetDB with GET or POST

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Submit arbitrary PQL or AST queries to PuppetDB. The GET request renders an empty query form, while POST allows direct query submission with specified endpoints and JSON output options.

```bash
# GET renders empty query form
curl http://localhost:8080/query
```

```bash
# POST with PQL query (table view)
curl -X POST http://localhost:8080/query \
  -d "query=nodes[certname, catalog_timestamp] { latest_report_status = \"failed\" }" \
  -d "endpoints=pql" \
  -d "rawjson=false"
```

```bash
# POST with AST query on nodes endpoint (raw JSON view)
curl -X POST http://localhost:8080/query \
  -d 'query=["=", "latest_report_status", "failed"]' \
  -d "endpoints=nodes" \
  -d "rawjson=true"
```

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

### Supervisor Configuration for Gunicorn

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md

Example Supervisor configuration to run Gunicorn in the background, setting the necessary environment variable for Puppetboard settings.

```ini
[program:puppetboard]
command=gunicorn -b 127.0.0.1:9090 puppetboard.app:app
user=www-data
stdout_logfile=/var/log/supervisor/puppetboard/puppetboard.out
stderr_logfile=/var/log/supervisor/puppetboard/puppetboard.err
environment=PUPPETBOARD_SETTINGS="/var/www/puppetboard/settings.py"
```

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

### Create WSGI configuration for nginx

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md

Create a `wsgi.py` file in your Puppetboard directory for use with uwsgi/gunicorn when deploying behind nginx. This is a minimal example.

```python
from __future__ import absolute_import
import os


```

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

### GET /inventory

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Displays a tabular inventory of all nodes, with configurable fact columns defined by `INVENTORY_FACTS` in settings.

```APIDOC
## GET /inventory — Inventory table

Displays a tabular inventory of all nodes with configurable fact columns defined by `INVENTORY_FACTS`.

### Method
GET

### Endpoint
/inventory
/env_name/inventory

### Example
```bash
curl http://localhost:8080/inventory
curl http://localhost:8080/staging/inventory
```
```

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

### Get Environments List

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Query PuppetDB for all known environments and return an ordered dictionary with display metadata, prioritizing favorite environments.

```python
from puppetboard.core import environments

envs = environments()
# Returns dict like:
# {
#   'All Environments': {'url': '/?env=*', 'icon': 'server', 'divider': True},
#   'production':       {'url': '/?env=production', 'icon': 'star', 'divider': True},
#   'staging':          {'url': '/?env=staging', 'icon': 'star', 'divider': False},
#   'dev':              {'url': '/?env=dev', 'icon': '', 'divider': True},
# }
```

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

### Gunicorn Configuration for Systemd

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md

Example Gunicorn configuration file used with systemd. This specifies bind address, worker count, working directory, and environment variables.

```ini
import multiprocessing

bind    = '127.0.0.1:9090'
workers = multiprocessing.cpu_count() * 2 + 1
chdir   = '/usr/lib/pythonX.Y/site-packages/puppetboard'
raw_env = ['PUPPETBOARD_SETTINGS=/var/www/puppetboard/settings.py', 'http_proxy=']
```

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

### GET /query and POST /query

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Allows submitting arbitrary PQL or AST queries against PuppetDB endpoints. Supports query presets loaded from a YAML file.

```APIDOC
## GET /query and POST /query — Free-form PuppetDB query interface

### Description
Allows submitting arbitrary PQL or AST queries against PuppetDB endpoints. Supports query presets loaded from a YAML file.

### Method
GET, POST

### Endpoint
/query

### Parameters
#### Query Parameters (for GET)
- **query** (string) - Optional - The PQL or AST query to submit.
- **endpoints** (string) - Optional - The PuppetDB endpoint to query (e.g., `pql`, `nodes`).
- **rawjson** (boolean) - Optional - Whether to return raw JSON output.

#### Request Body (for POST)
- **query** (string) - Required - The PQL or AST query to submit.
- **endpoints** (string) - Required - The PuppetDB endpoint to query (e.g., `pql`, `nodes`).
- **rawjson** (boolean) - Required - Whether to return raw JSON output.

### Request Example
```bash
# GET renders empty query form
curl http://localhost:8080/query

# POST with PQL query (table view)
curl -X POST http://localhost:8080/query \
  -d "query=nodes[certname, catalog_timestamp] { latest_report_status = \"failed\" }" \
  -d "endpoints=pql" \
  -d "rawjson=false"

# POST with AST query on nodes endpoint (raw JSON view)
curl -X POST http://localhost:8080/query \
  -d 'query=["=", "latest_report_status", "failed"]' \
  -d "endpoints=nodes" \
  -d "rawjson=true"
```
```

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

### Configure Class View Caching

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Set the cache type and timeout for class events. 'SimpleCache' is suitable for single-worker setups, while 'MemcachedCache' is recommended for multi-worker deployments.

```python
CLASS_EVENTS_STATUS_COLUMNS = [('failure', 'Failure'), ('success', 'Success'), ('noop', 'Noop')]
CACHE_TYPE            = 'SimpleCache'   # or 'MemcachedCache' for multi-worker
CACHE_DEFAULT_TIMEOUT = 3600            # 1 hour
```

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

### Configure Scheduled Class Event Cache Builder

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Example configuration for APScheduler to periodically build and cache resource events of all latest reports, grouped by Puppet class. Ensure `SCHEDULER_ENABLED` is True and `CACHE_TYPE` is set for multi-worker setups.

```python
# settings.py — configure scheduler to call this every 5 minutes
SCHEDULER_ENABLED = True
CACHE_TYPE = 'MemcachedCache'  # required for multi-worker setups
SCHEDULER_JOBS = [{
    'id': 'build_class_cache',
    'func': 'puppetboard.schedulers.classes:build_async_cache',
    'trigger': 'interval',
    'seconds': 300,
}]
```

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

### Run Puppetboard Application

Source: https://github.com/voxpupuli/puppetboard/blob/master/README.md

Set the settings file path and run the Flask development server.

```bash
export PUPPETBOARD_SETTINGS=$PWD/settings.py # See bellow
flask run
```

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

### Configure WSGI Entry Point for Puppetboard

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Debian-Jessie.md

Sets up the WSGI entry point script for Puppetboard, ensuring the correct Python path is appended.

```python
from __future__ import absolute_import
import os

import sys
sys.path.append('/opt/voxpupuli-puppetboard/puppetboard')

from puppetboard.app import app as application

```

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

### GET /failures and GET /<env>/failures — Failures view

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Streams a page listing all currently-failing nodes with the first error message from their latest report.

```APIDOC
## GET /failures and GET /<env>/failures — Failures view

### Description
Streams a page listing all currently-failing nodes with the first error message from their latest report.

### Method
GET

### Endpoint
/failures or /<env>/failures

### Example
```bash
# Friendly (human-readable) error formatting (default)
curl http://localhost:8080/failures
curl http://localhost:8080/failures/friendly

# Raw error formatting (unmodified from PuppetDB)
curl http://localhost:8080/failures/raw
curl http://localhost:8080/production/failures/raw
```
```

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

### Run Flask with Host and Port Options

Source: https://github.com/voxpupuli/puppetboard/blob/master/README.md

Alternatively, specify the host and port directly as command-line arguments for the Flask development server.

```bash
flask run --host '0.0.0.0' --port '8000'
```

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

### Deploy Puppetboard with OpenShift Template

Source: https://github.com/voxpupuli/puppetboard/blob/master/README.md

Use this command to create a basic Puppetboard application using the provided OpenShift template, connecting to a specified PuppetDB host.

```bash
oc new-app -p PUPPETDB_HOST=puppetdb.fqdn.com \
           --template=puppetboard-template
```

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

### GET /nodes and GET /<env>/nodes — Node list

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Streams an HTML table of all active nodes with their latest report status. Supports filtering by status via query string.

```APIDOC
## GET /nodes and GET /<env>/nodes — Node list

### Description
Streams an HTML table of all active nodes with their latest report status. Supports filtering by status via query string.

### Method
GET

### Endpoint
/nodes or /<env>/nodes

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filters nodes by status (e.g., `failed`, `changed`, `unchanged`, `unreported`).

### Example
```bash
# All active nodes in production
curl http://localhost:8080/nodes

# Filter by status: failed | changed | unchanged | unreported
curl "http://localhost:8080/nodes?status=failed"
curl "http://localhost:8080/staging/nodes?status=changed"
```
```

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

### Create Directories for nginx + uwsgi/gunicorn

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md

Use this command to create the necessary directory for Puppetboard when deploying with nginx and uwsgi/gunicorn.

```bash
$ mkdir -p /var/www/puppetboard

```

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

### GET /status

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Health check endpoint that returns a plain-text 'OK' response.

```APIDOC
## GET /status — Health check endpoint

### Description
Returns a plain-text `OK` response. Suitable for load balancer health checks.

### Method
GET

### Endpoint
/status

### Response
#### Success Response (200)
- **OK** (string) - Plain text indicating the service is healthy.

### Request Example
```bash
curl http://localhost:8080/status
```

### Response Example
```
OK
```
```

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

### Create Directories for Apache + mod_passenger

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md

Use this command to create the necessary directories for Puppetboard when deploying with Apache and mod_passenger.

```bash
$ mkdir -p /var/www/puppetboard/{tmp,public}
```

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

### GET /catalogs

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Lists nodes that have compiled catalogs. This feature requires `ENABLE_CATALOG` to be set to `True` in the settings.

```APIDOC
## GET /catalogs — Catalog list (requires `ENABLE_CATALOG=True`)

Lists nodes with compiled catalogs and supports side-by-side comparison.

### Method
GET

### Endpoint
/catalogs
/catalogs/compare/<node1>...<node2>

### Example
```bash
# Must enable in settings: ENABLE_CATALOG = True
curl http://localhost:8080/catalogs
curl "http://localhost:8080/catalogs/compare/agent1.example.com"
```
```

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

### Build Puppetboard Docker Image Locally

Source: https://github.com/voxpupuli/puppetboard/blob/master/README.md

Build the Puppetboard Docker image from the provided Dockerfile in the project directory.

```bash
docker build -t puppetboard .
```

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

### GET /radiator

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Retrieves JSON statistics for external monitoring integration, including changed, failed, and unchanged counts.

```APIDOC
## GET /radiator

### Description
Retrieves JSON statistics for external monitoring integration, including changed, failed, and unchanged counts.

### Method
GET

### Endpoint
/radiator

### Response
#### Success Response (200)
- **changed** (integer) - Number of changed resources.
- **changed_percent** (float) - Percentage of changed resources.
- **failed** (integer) - Number of failed resources.
- **failed_percent** (float) - Percentage of failed resources.
- **unchanged** (integer) - Number of unchanged resources.
- **unchanged_percent** (float) - Percentage of unchanged resources.
- **unreported** (integer) - Number of unreported nodes.
- **unreported_percent** (float) - Percentage of unreported nodes.
- **noop** (integer) - Number of noop resources.
- **noop_percent** (float) - Percentage of noop resources.
- **skipped** (integer) - Number of skipped resources.
- **skipped_percent** (float) - Percentage of skipped resources.

### Request Example
```bash
curl -H "Accept: application/json" http://localhost:8080/radiator
```

### Response Example
```json
{
  "changed": 5, "changed_percent": 10,
  "failed": 2,  "failed_percent": 4,
  "unchanged": 40, "unchanged_percent": 80,
  "unreported": 3, "unreported_percent": 6,
  "noop": 0, "noop_percent": 0,
  "skipped": 0, "skipped_percent": 0
}
```
```

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

### Create Puppetboard Directory

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md

Use this command to create the necessary directory for Puppetboard files before copying configuration.

```bash
mkdir -p /var/www/html/puppetboard
```

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

### GET /metric/<metric>

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Retrieves detailed information, including all attributes and their values, for a specific JMX MBean metric.

```APIDOC
## GET /metric/<metric> — Single metric detail

Displays all attributes and their values for a specific MBean metric.

### Method
GET

### Endpoint
/metric/<metric>

### Parameters
#### Path Parameters
- **metric** (string) - Required - The name of the MBean metric (e.g., 'puppetlabs.puppetdb.population:name=num-nodes').

### Example
```bash
curl http://localhost:8080/metric/puppetlabs.puppetdb.population:name=num-nodes
curl http://localhost:8080/metric/puppetlabs.puppetdb.command-processing:name=discarded
```
```

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

### Using Multi-line YAML String Syntax for Complex Queries

Source: https://github.com/voxpupuli/puppetboard/blob/master/QUERY_PRESETS.md

Demonstrates how to use YAML's multi-line string syntax ('|') for writing complex and readable queries.

```yaml
query: |
  nodes[certname, facts.os.name, facts.os.release.full] {
    facts.os.name ~ "(?i)ubuntu"
    order by catalog_timestamp desc
  }
```

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

### GET /metrics

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Lists all available JMX MBean metrics within PuppetDB, accessible via the Jolokia endpoint.

```APIDOC
## GET /metrics — Metrics list

Lists all JMX MBean metrics available in PuppetDB (via the Jolokia endpoint).

### Method
GET

### Endpoint
/metrics

### Example
```bash
curl http://localhost:8080/metrics
# Displays sorted list of domain:property metric names, e.g.:
# puppetlabs.puppetdb.population:name=num-nodes
# puppetlabs.puppetdb.population:name=num-resources
```
```

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

### Create and Activate Virtual Environment

Source: https://github.com/voxpupuli/puppetboard/blob/master/README.md

Use this to create a Python virtual environment for development. Run `deactivate` to exit the environment.

```bash
python -m venv venv
. venv/bin/activate # run `deactivate` to exit the virtualenv
```

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

### Enable Apache Site Configuration

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Debian-Jessie.md

Enables the Apache virtual host configuration file for Puppetboard.

```bash
$ a2ensite voxpupuli-puppetboard.conf

```

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

### Get JSON Statistics

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Retrieve statistics in JSON format for external monitoring. Ensure the Accept header is set to application/json.

```bash
curl -H "Accept: application/json" http://localhost:8080/radiator
```

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

### GET /class_resource/<class_name>

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Lists all nodes that had at least one resource event for a specified Puppet class in their latest report.

```APIDOC
## GET /class_resource/<class_name> — Class detail

Lists all nodes that had at least one resource event for a given Puppet class in their latest report.

### Method
GET

### Endpoint
/class_resource/<class_name>

### Parameters
#### Path Parameters
- **class_name** (string) - Required - The name of the Puppet class.

### Example
```bash
curl "http://localhost:8080/class_resource/Apache"
curl "http://localhost:8080/production/class_resource/Postgresql::Server"
```
```

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

### GET /reports

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Retrieves a paginated, searchable, and sortable list of all Puppet run reports. It can also be scoped to a specific node.

```APIDOC
## GET /reports — Reports list

Displays a paginated, searchable, sortable table of all Puppet run reports.

### Method
GET

### Endpoint
/reports
/reports/<node_name>
/env_name/reports

### Example
```bash
curl http://localhost:8080/reports
curl http://localhost:8080/reports/agent1.example.com   # node-scoped
curl http://localhost:8080/staging/reports
```
```

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

### Import OpenShift Template

Source: https://github.com/voxpupuli/puppetboard/blob/master/README.md

Import the Puppetboard OpenShift template file into your OpenShift environment to deploy the web interface.

```bash
# Import the template into OpenShift
oc create -f puppetboard-s2i-template.yaml
```

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

### Configure Passenger WSGI for Puppetboard

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md

Create a `passenger_wsgi.py` file in your Puppetboard directory to configure the application for Passenger. Ensure logging is configured here for startup issue diagnosis.

```python
from __future__ import absolute_import
import os
import logging

logging.basicConfig(filename='/path/to/file/for/logging', level=logging.INFO)

# Needed if a settings.py file exists
os.environ['PUPPETBOARD_SETTINGS'] = '/var/www/puppetboard/settings.py'

try:
    from puppetboard.app import app as application
except Exception, inst:
    logging.exception("Error: %s", str(type(inst)))

```

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

### Deploy Puppetboard with Custom Parameters

Source: https://github.com/voxpupuli/puppetboard/blob/master/README.md

Deploy Puppetboard with specific versions and connection details by setting environment variables for the PuppetDB host, port, repository reference, and service name.

```bash
oc new-app -p PUPPETDB_HOST=puppetdb.fqdn.com \
           -p PUPPETDB_PORT=3456 \
           -p PUPPETBOARD_SOURCE_REPOSITORY_REF="v5.4.0" \
           -p PUPPETBOARD_SERVICE_NAME=prod_puppetboard \
           --template=puppetboard-template
```

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

### Puppetfile Module Dependencies

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/EL7.md

List of Puppet modules required for Puppetboard installation, specified in a Puppetfile. Ensure these modules are available in your Puppet environment.

```ruby
mode 'apache',
  :git => 'https://github.com/puppetlabs/puppetlabs-apache.git',
  :ref => '3.4.0'

mod 'apt',
  :git => 'https://github.com/puppetlabs/puppetlabs-apt.git',
  :ref => '6.2.1'

mod 'concat',
  :git => 'https://github.com/puppetlabs/puppetlabs-concat.git',
  :ref => '5.1.0'

mod 'epel',
  :git => 'https://github.com/stahnma/puppet-module-epel.git',
  :ref => '1.3.1'

mod 'firewall',
  :git => 'https://github.com/puppetlabs/puppetlabs-firewall.git',
  :ref => '1.14.0'

mod 'inifile',
  :git => 'https://github.com/puppetlabs/puppetlabs-inifile.git',
  :ref => '2.4.0'

mod 'postgresql',
  :git => 'https://github.com/puppetlabs/puppet-postgresql.git',
  :ref => '5.11.0'

mod 'puppetdb',
  :git => 'https://github.com/puppetlabs/puppetlabs-puppetdb.git',
  :ref => '7.1.0'

mod 'puppetboard',
  :git => 'https://github.com/voxpupuli/puppet-puppetboard.git',
  :ref => 'v5.0.0'

mod 'python',
  :git => 'https://github.com/voxpupuli/puppet-python.git',
  :ref => 'v2.2.2'

mod 'selinux',
  :git => 'https://github.com/ghoneycutt/puppet-module-selinux.git',
  :ref => 'v2.2.0'

mod 'stdlib',
  :git => 'https://github.com/puppetlabs/puppetlabs-stdlib.git',
  :ref => '5.1.0'

mod 'translate',
  :git => 'https://github.com/puppetlabs/puppetlabs-translate.git',
  :ref => '1.2.0'
```

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

### Initialize Theme on Load

Source: https://github.com/voxpupuli/puppetboard/blob/master/puppetboard/templates/layout.html

Sets the initial theme based on local storage or system preference to prevent a flash of unstyled content. This script runs immediately when the page loads.

```javascript
(function() { var stored = localStorage.getItem('theme'); var systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches; var theme = stored || (systemDark ? 'dark' : 'light'); document.documentElement.setAttribute('data-theme', theme); })();
```

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

### GET /daily_reports_chart.json

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Returns a JSON array of per-day report counts (changed/unchanged/failed) for the past N days, used to render bar charts.

```APIDOC
## GET /daily_reports_chart.json — Daily reports chart data

### Description
Returns a JSON array of per-day report counts (changed/unchanged/failed) for the past N days, used to render bar charts on the overview and node pages.

### Method
GET

### Endpoint
/daily_reports_chart.json

### Parameters
#### Query Parameters
- **certname** (string) - Optional - The certname of the node to retrieve history for.

### Request Example
```bash
# All nodes, last 8 days (default DAILY_REPORTS_CHART_DAYS=8)
curl "http://localhost:8080/daily_reports_chart.json"

# Single node history
curl "http://localhost:8080/daily_reports_chart.json?certname=agent1.example.com"
curl "http://localhost:8080/staging/daily_reports_chart.json?certname=agent1.example.com"
```

### Response
#### Success Response (200)
- **result** (array) - An array of daily report statistics.
  - **day** (string) - The date of the report statistics.
  - **changed** (integer) - The number of changed resources for that day.
  - **unchanged** (integer) - The number of unchanged resources for that day.
  - **failed** (integer) - The number of failed resources for that day.

### Response Example
```json
{"result": [
  {"day": "2024-01-08", "changed": 3, "unchanged": 40, "failed": 1},
  {"day": "2024-01-07", "changed": 5, "unchanged": 38, "failed": 0},
  ...
]}
```
```

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

### GET /catalog/<node_name>

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Retrieves the complete compiled catalog for a specific node, including its resources, edges, and relationships. Requires `ENABLE_CATALOG = True`.

```APIDOC
## GET /catalog/<node_name> — Node catalog

Displays the full compiled catalog of a node (resources, edges, relationships). Requires `ENABLE_CATALOG = True`.

### Method
GET

### Endpoint
/catalog/<node_name>

### Parameters
#### Path Parameters
- **node_name** (string) - Required - The name of the node.

### Example
```bash
curl http://localhost:8080/catalog/agent1.example.com
```
```

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

### Apache mod_wsgi Configuration (Fedora)

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md

Sample Apache VirtualHost configuration for deploying Puppetboard with mod_wsgi on Fedora systems. Ensure Python version (X.Y) is correctly specified.

```apache
<VirtualHost *:80>
    ServerName puppetboard.example.tld
    WSGIDaemonProcess puppetboard user=apache group=apache threads=5
    WSGIScriptAlias / /var/www/html/puppetboard/wsgi.py
    ErrorLog logs/puppetboard-error_log
    CustomLog logs/puppetboard-access_log combined

    Alias /static /usr/lib/pythonX.Y/site-packages/puppetboard/static
    <Directory /usr/lib/pythonX.Y/site-packages/puppetboard/static>
        Satisfy Any
        Allow from all
    </Directory>

    <Directory /usr/lib/pythonX.Y/site-packages/puppetboard>
        WSGIProcessGroup puppetboard
        WSGIApplicationGroup %{GLOBAL}
        Require all granted
    </Directory>
</VirtualHost>
```

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

### Configure Listening Host and Port

Source: https://github.com/voxpupuli/puppetboard/blob/master/README.md

Set environment variables to specify the host and port for the Flask development server.

```bash
export FLASK_RUN_HOST=0.0.0.0
export FLASK_RUN_PORT=8000

flask run
```

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

### Flask Application Factory

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

The `get_app()` function creates and returns the Flask application instance. It loads default settings and applies overrides from the `PUPPETBOARD_SETTINGS` environment variable.

```python
# puppetboard/core.py
from puppetboard.core import get_app

app = get_app()
# app.config keys available after init:
# PUPPETDB_HOST, PUPPETDB_PORT, SECRET_KEY, DEFAULT_ENVIRONMENT,
# ENABLE_QUERY, ENABLE_CATALOG, ENABLE_CLASS, LOGLEVEL, ...

print(app.config['DEFAULT_ENVIRONMENT'])  # 'production'
print(app.config['ENABLE_QUERY'])          # True
```

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

### GET /catalogs/compare/<node1>...<node2>

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Performs a side-by-side comparison (diff) of the compiled catalogs of two specified nodes. Requires `ENABLE_CATALOG = True`.

```APIDOC
## GET /catalogs/compare/<node1>...<node2> — Catalog comparison

Side-by-side diff of two nodes' catalogs. Requires `ENABLE_CATALOG = True`.

### Method
GET

### Endpoint
/catalogs/compare/<node1>...<node2>

### Parameters
#### Path Parameters
- **node1** (string) - Required - The name of the first node.
- **node2** (string) - Required - The name of the second node.

### Example
```bash
curl "http://localhost:8080/catalogs/compare/agent1.example.com...agent2.example.com"
```
```

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

### GET /node/<node_name> — Single node dashboard

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Displays a node-specific page including facts, recent reports, and run history chart.

```APIDOC
## GET /node/<node_name> — Single node dashboard

### Description
Displays a node-specific page including facts, recent reports, and run history chart.

### Method
GET

### Endpoint
/node/<node_name>

### Example
```bash
curl http://localhost:8080/node/agent1.example.com
curl http://localhost:8080/production/node/agent1.example.com
```
```

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

### Configure Apache Virtual Host for Puppetboard

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md

Set up an Apache VirtualHost configuration to serve Puppetboard. This includes setting the ServerName, DocumentRoot, log files, and aliasing static files.

```apache
<VirtualHost *:80>
    ServerName puppetboard.example.tld
    DocumentRoot /var/www/puppetboard/public
    ErrorLog /var/log/apache2/puppetboard.error.log
    CustomLog /var/log/apache2/puppetboard.access.log combined

    RackAutoDetect On
    Alias /static /usr/local/lib/pythonX.Y/dist-packages/puppetboard/static
</VirtualHost>

```

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

### Configure WSGI Application

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md

Create a wsgi.py file to configure the Flask application and specify the settings file path. Ensure this file is readable by the webserver user.

```python
from __future__ import absolute_import
import os

# Needed if a settings.py file exists
os.environ['PUPPETBOARD_SETTINGS'] = '/var/www/html/puppetboard/settings.py'
from puppetboard.app import app as application
```

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

### Nginx Configuration for Gunicorn

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md

Configure Nginx to proxy requests to a Gunicorn application server. This setup differs from uWSGI by using traditional proxying and setting necessary headers.

```nginx
server {
    listen      80;
    server_name puppetboard.example.tld;
    charset     utf-8;

    location /static {
        alias /usr/local/lib/pythonX.Y/dist-packages/puppetboard/static;
    }

    location / {
        add_header Access-Control-Allow-Origin *;
        proxy_pass_header Server;
        proxy_set_header Host $http_host;
        proxy_redirect off;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_connect_timeout 10;
        proxy_read_timeout 10;
        proxy_pass http://127.0.0.1:9090;
    }
}
```

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

### Run Tests and Linting

Source: https://github.com/voxpupuli/puppetboard/blob/master/README.md

Execute tests with coverage reporting and run pylint for code quality checks.

```bash
pytest --cov=. --cov-report=xml --strict-markers --mypy puppetboard test
pylint --errors-only puppetboard test
```

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

### GET /inventory/json

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Provides inventory data in JSON format for the inventory table. It queries PuppetDB for facts, resolves dot-notation paths, and renders Jinja2 fact templates.

```APIDOC
## GET /inventory/json — Inventory data (DataTables JSON endpoint)

Backend for the inventory table, querying PuppetDB for facts defined in `INVENTORY_FACTS`, resolving dot-notation paths, and rendering Jinja2 fact templates.

### Method
GET

### Endpoint
/inventory/json

### Parameters
#### Query Parameters
- **draw** (integer) - Required - DataTables draw counter.

### Example
```bash
curl "http://localhost:8080/inventory/json?draw=1"
# Response:
# {
#   "draw": 1, "recordsTotal": 50, "recordsFiltered": 50,
#   "data": [["<a href='/node/...'>agent1</a>", "192.168.1.10", "Ubuntu", "x86_64", "5.15.0", "7.32.0"], ...]
# }
```
```

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

### GET /report/<node_name>/<report_id>

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Retrieves the full details of a single Puppet report, including events, logs, and metrics. The report_id can be the report hash or the configuration version.

```APIDOC
## GET /report/<node_name>/<report_id> — Single report

Shows a full report with events (resource changes), logs, and metrics. `report_id` may be the report hash or `configuration_version`.

### Method
GET

### Endpoint
/report/<node_name>/<report_id>
/report/<node_name>/<report_id>/friendly
/report/<node_name>/<report_id>/raw

### Parameters
#### Path Parameters
- **node_name** (string) - Required - The name of the node.
- **report_id** (string) - Required - The ID or configuration version of the report.

### Example
```bash
curl http://localhost:8080/report/agent1.example.com/abc123def456
curl http://localhost:8080/report/agent1.example.com/abc123def456/friendly
curl http://localhost:8080/report/agent1.example.com/abc123def456/raw
```
```

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

### Enable Scheduler Configuration

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Configure the scheduler to be enabled and set the lock bind port. Ensure the port is free on the host. Also configure the cache type and timeout for multi-worker deployments.

```python
SCHEDULER_ENABLED = True
SCHEDULER_LOCK_BIND_PORT = 49100   # must be free on the host
CACHE_TYPE = 'MemcachedCache'      # use shared cache for multi-worker deployments
CACHE_DEFAULT_TIMEOUT = 3600
```

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

### PuppetDB Connection Singleton

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

The `get_puppetdb()` function provides a singleton instance of the pypuppetdb connection. It configures the User-Agent header and uses settings from `app.config` for connection parameters.

```python
from puppetboard.core import get_puppetdb

puppetdb = get_puppetdb()
# Backed by app.config values:
#   PUPPETDB_HOST, PUPPETDB_PORT, PUPPETDB_PROTO,
#   PUPPETDB_SSL_VERIFY, PUPPETDB_KEY, PUPPETDB_CERT, PUPPETDB_TIMEOUT

# Direct PuppetDB access (bypassing the web views):
nodes = list(puppetdb.nodes())
print(nodes[0].name)         # 'agent1.example.com'
print(nodes[0].status)       # 'changed' | 'unchanged' | 'failed' | 'unreported'
```

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

### GET /facts — Facts index

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Displays all known fact names in an alphabetical multi-column layout. Structured facts are shown as collapsible parents with lazy-loaded children.

```APIDOC
## GET /facts — Facts index

### Description
Displays all known fact names in an alphabetical multi-column layout. Structured facts (dict values) are shown as collapsible parents with lazy-loaded children.

### Method
GET

### Endpoint
/facts

### Example
```bash
curl http://localhost:8080/facts
curl http://localhost:8080/production/facts
```
```

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

### Configure Favorite Environments

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Set a list of environments that should appear first in the environment dropdown. This prioritizes frequently used environments.

```python
FAVORITE_ENVS = ['production', 'staging', 'qa', 'test', 'dev']
```

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

### Nginx Configuration for uWSGI

Source: https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md

Configure Nginx to proxy requests to the uWSGI application server. This setup includes serving static files directly and passing dynamic requests to uWSGI.

```nginx
upstream puppetboard {
    server 127.0.0.1:9090;
}

server {
    listen      80;
    server_name puppetboard.example.tld;
    charset     utf-8;

    location /static {
        alias /usr/local/lib/pythonX.Y/dist-packages/puppetboard/static;
    }

    location / {
        uwsgi_pass puppetboard;
        include    /path/to/uwsgi_params/probably/etc/nginx/uwsgi_params;
    }
}
```

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

### Get Daily Reports Chart Data

Source: https://context7.com/voxpupuli/puppetboard/llms.txt

Fetch daily report counts for a specified number of days, used for generating bar charts. Supports filtering by node name.

```bash
# All nodes, last 8 days (default DAILY_REPORTS_CHART_DAYS=8)
curl "http://localhost:8080/daily_reports_chart.json"
```

```bash
# Single node history
curl "http://localhost:8080/daily_reports_chart.json?certname=agent1.example.com"
```

```bash
curl "http://localhost:8080/staging/daily_reports_chart.json?certname=agent1.example.com"
```

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

### Run Puppetboard with Docker

Source: https://github.com/voxpupuli/puppetboard/blob/master/README.md

Use this command to run the Puppetboard Docker image. Ensure you provide a secret key. The `PUPPETDB_HOST` and `PUPPETDB_PORT` should match your PuppetDB instance.

```bash
docker run -it \
  -e PUPPETDB_HOST=localhost \
  -e PUPPETDB_PORT=8080 \
  -e SECRET_KEY=XXXXXXXX \
  --net=host \
  ghcr.io/voxpupuli/puppetboard
```