Product Installation

This page describes the intended on-prem installation flow. The product distribution is Restic-backed: release bundles are published to a Restic repository and restored by the installer or runtime scripts.

Install Topology

Component	Role
Control plane	Postgres, PostgREST, WebUI, schema, seed data, report endpoints, package endpoints.
Worker host	Agent daemon, benchmark tools, framework runtime, telemetry collection.
Optional console agent	Browser/terminal interface for assisted benchmark workflows.

Control-Plane Prerequisites

• Linux host with Docker Engine and Docker Compose plugin.
• curl, jq, and shell access.
• Network/DNS name for WebUI and PostgREST.
• Persistent disk for Postgres.
• Restic repository credentials provided out-of-band.
• Authentication provider configuration for browser users.

Restore Product Bundle

The exact release command depends on how your distribution repository is provisioned. The expected shape is:

export RESTIC_REPOSITORY="<restic-repository-url>"
export RESTIC_PASSWORD="<restic-password>"
export METRUM_RELEASE_TAG="<release-tag>"

mkdir -p /opt/metrum-insights
cd /opt/metrum-insights
restic restore latest --target . --tag "$METRUM_RELEASE_TAG"

Never paste Restic secrets into tickets, docs, or chat. Store them in the host secret manager or deployment environment.

Restore External Docs

The corporate docs web server restores static docs from the same Restic-backed distribution process. The restore container or maintenance shell needs:

Setting	Required	Notes
RESTIC_REPOSITORY	Yes	Restic repository URL. For REST backend deployments this includes the Restic REST user and REST endpoint.
RESTIC_PASSWORD or RESTIC_PASSWORD_FILE	Yes	Restic repository encryption password or a file containing it. Prefer a mounted secret file in containers.
VERSION	Yes	Docs version to restore, for example v4.0.rc4.
Backend credentials	Maybe	S3, B2, or other backend-specific environment variables if the repository URL requires them.

Docs snapshots are tagged with docs-releases, metrum-insights-docs, the version tag, the Restic environment tag, and optionally latest. Restore the versioned docs archive, verify its SHA256 file, extract it under the Caddy web root, and update /metrum-insights/versions.json.

The docs-serving Caddy container does not need TLS if the corporate front-door Caddy instance terminates TLS and reverse-proxies to the internal docs container.

Configure Runtime

Create the runtime environment file with:

• database credentials and volume paths;
• PGRST_JWT_SECRET;
• public WebUI URL and public PostgREST URL;
• Firebase/OIDC/OAuth configuration;
• credential encryption key;
• Restic repository settings for worker bootstrap;
• cloud provider credentials if managed cloud onboarding is enabled.

Authentication choices:

Mode	Use when
Firebase/OIDC browser auth	Users log in through the WebUI.
Service JWT	Workers and internal services call PostgREST.
Internal API key	Trusted service-to-service WebUI endpoints such as onboarding bootstrap.

Start And Verify

Bring up the stack and check health:

docker compose up -d
docker compose ps

curl -fsS "$METRUM_WEBUI_URL/api/health" | jq
curl -fsS "$METRUM_API_URL/" | jq

Verify:

• Postgres is healthy and persistent.
• PostgREST responds and has the expected schema.
• WebUI health is green.
• Browser login works.
• API bearer token can call POST /rpc/get_current_user_context.
• /api/packages can serve worker artifacts if worker onboarding is enabled.

Worker Installation

For on-prem worker hosts:

1. Register the server config and instance.
2. Generate onboarding bootstrap from WebUI.
3. Run the install command on the worker.
4. Verify agent registration and heartbeat.
5. Run a small smoke benchmark.

For GPU workers, install the vendor driver and container runtime before running GPU benchmarks. Worker installation should report GPU detection issues as warnings; the control-plane install should not silently assume GPU readiness.

Operations

Routine operations should include:

• backup/restore validation;
• schema migration rehearsal;
• docker compose ps and health checks;
• auth provider token validation;
• worker heartbeat checks;
• support bundle collection before upgrades.