rpki/deploy/docker-installer/docs/README.en.md

ours RP Docker Installer Guide (__PACKAGE_ARCH__ / __PACKAGE_PLATFORM__)

Goal

This package deploys ours RP on Linux servers whose host architecture matches the packaged installer metadata, using Docker Compose and continuous all-five RIR validation.

The package includes four architecture-matched images: ours RP runtime, artifact metrics, Prometheus, and Grafana. Deployment does not need to pull application images on the target host. Runtime state, run artifacts, logs, Prometheus data and Grafana data are persisted through host bind mounts.

Every installer build rebuilds the ours RP runtime and artifact metrics images. The deliverable name is ours-rp-installer-{arch}-{git8}-{YYYYMMDDTHHMMSSZ}.tar.gz, and both ours RP image tags use the current source commit. PACKAGE-MANIFEST.env records the full commit, UTC build time, dirty state, and image archive hashes; ./scripts/status.sh --brief displays that provenance after installation.

By default the host architecture must match PACKAGE_ARCH from PACKAGE-MANIFEST.env. If you intentionally want to run this package on a different host architecture through QEMU/binfmt, set:

ALLOW_CROSS_ARCH=1

Compose Template Source

compose/ is the single production Docker Compose template source. The Docker installer build script copies this directory directly. Do not maintain a second copy of the Compose, Prometheus, or Grafana dashboard files elsewhere.

The legacy direct Compose deployment entry point has been removed. For either amd64 or arm64, build the matching installer package with scripts/docker/build_docker_installer_package.sh, then use scripts/install.sh, scripts/start.sh, and scripts/status.sh as described here.

Quick Start

tar -xzf ours-rp-installer-__PACKAGE_ARCH__-*.tar.gz
cd ours-rp-installer-__PACKAGE_ARCH__-*

./scripts/install.sh
cp .env.example .env   # install.sh creates .env automatically if missing
vim .env
./scripts/start.sh
./scripts/status.sh

Defaults:

• PACKAGE_ARCH=__PACKAGE_ARCH__
• PACKAGE_PLATFORM=__PACKAGE_PLATFORM__
• RIRS=afrinic,apnic,arin,lacnic,ripe
• MAX_RUNS=-1
• INTERVAL_SECS=600
• TAL_INPUT_MODE=file-live-ta
• RESOURCE_VALIDATION_MODE=validation-update-03
• LIVE_TA_REFRESH_BEFORE_SNAPSHOT=1
• PERIODIC_SNAPSHOT_RESET=0
• PERIODIC_SNAPSHOT_MAX_DELTAS=100
• HOST_DATA_DIR=__HOST_DATA_DIR__
• SOAK_RESTART_POLICY=unless-stopped
• RPKI_IMAGE=__RUNTIME_IMAGE__
• METRICS_IMAGE=__METRICS_IMAGE__
• METRICS_PLATFORM=__PACKAGE_PLATFORM__
• MONITOR_PLATFORM=__PACKAGE_PLATFORM__
• ALLOW_CROSS_ARCH=0
• RTR_REPORT_DIR=__HOST_DATA_DIR__/empty-rtr-report, which mounts an empty fallback directory by default; after deploying a separate RTR service, register its same-host report directory through scripts/register_rtr_monitor.sh

First Start Semantics

If there is no successful run under HOST_DATA_DIR/runs, start.sh starts the core ours-rp-soak service first and waits for the first snapshot to succeed before starting metrics, Prometheus and Grafana.

Container/image mapping:

• ours-rp-soak uses RPKI_IMAGE
• artifact-metrics uses METRICS_IMAGE
• prometheus / grafana use their monitor images

The first snapshot refreshes live TA certificates before starting the RP process.

Resource Validation Mode

New knob:

RESOURCE_VALIDATION_MODE=validation-update-03

Supported values:

• validation-update-03: default behavior, using the current validation-update draft semantics;
• rfc6487: switch back to the original RFC 6487 resource containment behavior.

The installer / soak runner passes --resource-validation-mode to every rpki child start. When an upgraded deployment reuses an older .env that does not contain this key, the new package .env.example default validation-update-03 remains in the final .env; an empty final value fails before Docker operations.

Architecture Guardrails

The key scripts read:

• PACKAGE_ARCH / PACKAGE_PLATFORM from .env
• PACKAGE-MANIFEST.env
• the current host uname -m

Default behavior:

1. matching host and package architectures: run natively;
2. mismatched host and package architectures: fail with an explicit error;
3. only when ALLOW_CROSS_ARCH=1 is set do the scripts attempt to enable matching binfmt/qemu.

That means an arm64 package on an x86_64 host does not silently switch to emulation by default.

Ports

Default ports:

• metrics: http://<host>:9556/metrics
• Prometheus: http://<host>:9090
• Grafana: http://<host>:3000

Grafana credentials come from .env:

GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=admin

Change the password and restrict public access for production deployments.

Optional RTR report metrics input

If a separately deployed RTR service on the same host continuously writes rtr-source-*, rtr-runtime-*, and rtr-clients-* JSON reports, run:

./scripts/register_rtr_monitor.sh --report-dir /root/rpki/report

The command accepts only an absolute path on the same host, validates the candidate Compose mount, and atomically updates .env. It recreates only artifact-metrics, Prometheus, and Grafana; it does not restart or recreate ours-rp-soak. The artifact-metrics container mounts the directory read-only and reads it through RPKI_METRICS_RTR_REPORT_DIR, producing ours_rp_rtr_* metrics. By default, RTR_REPORT_DIR points at an empty fallback directory under the installer data root, so the metrics container also starts cleanly without an RTR service.

CCR artifact format check metrics

The metrics image ships the official rpki-client 9.8. For every newly completed run, artifact-metrics runs rpki-client -f result.ccr once and exports ours_rp_ccr_format_check_* metrics (cumulative pass/ccr_parse_error/tool_error counters, latest check result, check duration, consecutive failures). The Grafana Ours RP Soak Overview dashboard shows them in a dedicated panel row. On service start only the latest existing run is checked; older history is not backfilled.

Related environment variables (normally no need to change): CCR_CHECK_BIN (defaults to the in-image /opt/ours-rp/bin/rpki-client) and CCR_CHECK_TIMEOUT_SECS (default 120 seconds).

Data Directory

Default host directory:

__HOST_DATA_DIR__/
  state/
  runs/
  logs/
  tmp/
  prometheus/
  grafana/

Each runs/run_XXXX/ directory contains report.json, result.ccr, input.cir, vrps.csv, vaps.csv, stage-timing.json, logs and metadata.

Periodic Snapshot Reset

New knobs:

PERIODIC_SNAPSHOT_RESET=0
PERIODIC_SNAPSHOT_MAX_DELTAS=100

Semantics:

• disabled by default, keeping previous behavior unchanged;
• when enabled, one successful snapshot is followed by at most N successful delta runs;
• after the threshold is reached, the next run is forced to snapshot;
• before that forced snapshot, only the active state/db is reset, while runs/, logs/, state/rsync-mirror, .env, and Prometheus/Grafana data are preserved;
• the counter is persisted independently in HOST_DATA_DIR/state/run-lifecycle-state.json, so it does not depend on retained runs/ history;
• if that lifecycle file is corrupt, it is backed up as run-lifecycle-state.json.corrupt.<timestamp>.<pid> before best-effort bootstrap from retained runs;
• after a successful forced snapshot, the old DB staging is deleted so disk usage does not keep growing elsewhere.

Check the latest run-meta.json for:

• sync_mode
• snapshot_reason
• periodic_snapshot_delta_count
• periodic_snapshot_forced
• reset_db_cleanup_status

Common Commands

./scripts/status.sh
./scripts/logs.sh ours-rp-soak --tail 200
./scripts/restart.sh
./scripts/stop.sh
./scripts/cleanup.sh --keep-runs 100 --execute
./scripts/uninstall.sh

For finite acceptance tests, for example MAX_RUNS=3, also set:

SOAK_RESTART_POLICY=no

Otherwise Compose unless-stopped will restart the container after it exits successfully.

uninstall.sh keeps data by default. Use the following only when you really want to delete HOST_DATA_DIR:

./scripts/uninstall.sh --purge-data