Start here · v0.0.1

Installation overview

Select a supported topology, prepare dependencies, and use the release-owned preflight and verification surfaces.

AudiencePlatform administrators, SRE, infrastructureReading time14 minCommands in context5 guided stepsReviewed sourcefcc5871 · 30 July 2026

Exact release scope. This page documents the reviewed v0.0.1 source at fcc5871. Check release status before enabling a gated capability.

Choose a deployment profile

Profile	Use when	Critical requirements
`profile-single-node`	Evaluation or a controlled small installation where one host is acceptable.	One API/worker placement; durable PostgreSQL and artifacts still required.
`profile-split`	API, worker, database, artifact storage, and agent need separate placement.	Documented network paths, time sync, TLS trust, and explicit secret delivery.
`profile-ha-ready`	The control plane must tolerate instance loss.	External HA PostgreSQL, shared filesystem or S3-compatible artifacts, leader election, multiple replicas.

Required dependencies

✓
Signed release bundle with checksums, compatibility manifest, release metadata, and digest-pinned API and agent images.
✓
Durable PostgreSQL reachable from the API and workers. The Helm chart intentionally does not install PostgreSQL.
✓
Artifact storage using a durable filesystem or S3-compatible service. More than one replica requires shared storage.
✓
Secrets protection key containing exactly 32 random bytes, base64 encoded, with a managed non-development key ID.
✓
Trusted time source for every API and agent host. Default agent rejection begins when reported skew exceeds 30 seconds.
✓
TLS and name resolution for the user-facing endpoint and every API-to-agent, provider, registry, database, and object-store path.

Baseline capacity and storage decisions

The Helm chart starts with conservative container requests of 100m CPU and 256 MiB memory, and limits of 1 CPU and 1 GiB. These are scheduling defaults—not a production sizing guarantee. Size from your expected concurrent OperationRuns, evidence volume, retention, provider latency, and add-on/conformance workload.

Data class	Placement	Backup requirement
Control-plane state	External PostgreSQL	Consistent database backup and restore test
Run logs and artifacts	Durable filesystem or S3-compatible storage	Back up or replicate with checksums and retention metadata
Secrets master key	External secret manager or protected Kubernetes Secret	Separate encrypted escrow; never store only beside the database dump
Release evidence	Immutable artifact store or release bundle	Retain exact checksums, signatures, SBOM, and provenance used by the environment

Required installation flow

01
Verify the release
Validate checksums, signed compatibility metadata, image signatures, and the exact digests you will deploy.
02
Prepare configuration and secret references
Keep credentials outside values files, command history, logs, and support bundles. Use Kubernetes Secret references or the supported external delivery boundary.
03
Run preflight-only
Do not begin with installation. Resolve every hard failure in storage, database, trust, clock, ports, or release integrity first.
04
Run dry-run or render review
Review the final Compose/Helm configuration and confirm replica, storage, ingress, and feature-gate values.
05
Install and verify
Require both /health and /ready, inspect build information, and create the bootstrap administrator only through the supported onboarding path.
06
Capture a baseline backup
Verify a restorable backup before registering production credentials or starting lifecycle work.

Commands for this step

Verify the release before any installation

Run these checks against the downloaded release artifacts before Helm, Compose, or an installer is allowed to process them.

Run in orderComplete each step successfully before continuing.

01
Read-onlyLinux
Verify release checksums
Reject a damaged or substituted release bundle and Helm chart before extraction or installation.
Before you run it
- Release files and their canonical .sha256 sidecars are in the current directory
- GNU coreutils
Linux · release-checksums
```
sha256sum -c clusterpilot-release-metadata-<releaseVersion>.tar.gz.sha256
sha256sum -c clusterpilot-<releaseVersion>.tgz.sha256
```
Expected result
Both files report OK. Any mismatch stops the installation.
Reviewed sourcedocs/operations/supply-chain-security.md

Read-onlyLinux

Verify the release bundle signature

Verify the detached ClusterPilot release-bundle signature with the release public key.

Before you run it

Python 3
OpenSSL
Canonical release signing public key

Linux · release-bundle-signature

python3 - <<'PY'
from pathlib import Path
import base64

line = Path('clusterpilot-release-metadata-<releaseVersion>.tar.gz.sig').read_text(encoding='utf-8').splitlines()[3]
Path('bundle.sig.bin').write_bytes(base64.b64decode(line.split('=', 1)[1]))
PY
openssl dgst -sha256 -verify release-signing-public-key.pem \
  -signature bundle.sig.bin \
  clusterpilot-release-metadata-<releaseVersion>.tar.gz

Expected result

OpenSSL prints Verified OK.

Reviewed sourcedocs/operations/supply-chain-security.md

Read-onlyLinux

Verify the Helm chart signature

Verify the detached chart archive signature before Helm processes the chart.

Before you run it

Python 3
OpenSSL
Canonical release signing public key

Linux · release-chart-signature

python3 - <<'PY'
from pathlib import Path
import base64

line = Path('clusterpilot-<releaseVersion>.tgz.sig').read_text(encoding='utf-8').splitlines()[3]
Path('chart.sig.bin').write_bytes(base64.b64decode(line.split('=', 1)[1]))
PY
openssl dgst -sha256 -verify release-signing-public-key.pem \
  -signature chart.sig.bin \
  clusterpilot-<releaseVersion>.tgz

Expected result

OpenSSL prints Verified OK.

Reviewed sourcedocs/operations/supply-chain-security.md

04
Read-onlyLinux
Verify the signed metadata index
Verify the release identity, artifact map and runtime component metadata before using them.
Before you run it
- Python 3
- OpenSSL
- Canonical release signing public key
Linux · release-metadata-signature
```
python3 - <<'PY'
from pathlib import Path
import base64

line = Path('release-metadata-index.json.sig').read_text(encoding='utf-8').splitlines()[3]
Path('metadata.sig.bin').write_bytes(base64.b64decode(line.split('=', 1)[1]))
PY
openssl dgst -sha256 -verify release-signing-public-key.pem \
  -signature metadata.sig.bin \
  release-metadata-index.json
```
Expected result
OpenSSL prints Verified OK and the metadata remains byte-for-byte unchanged.
Reviewed sourcedocs/operations/supply-chain-security.md

Read-onlyCross-platform

Verify API and agent image signatures

Verify both digest-pinned runtime subjects against the release workflow identity.

Before you run it

Cosign
Exact image digests from signed release metadata
Registry reachability or mirrored signature material

Cross-platform · release-image-signatures

cosign verify \
  --certificate-identity-regexp '^https://github.com/<owner>/<repo>/.github/workflows/release.yml@.*$' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  ghcr.io/<owner>/clusterpilot-api@sha256:<digest>

cosign verify \
  --certificate-identity-regexp '^https://github.com/<owner>/<repo>/.github/workflows/release.yml@.*$' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  ghcr.io/<owner>/clusterpilot-agent@sha256:<digest>

Expected result

Both subjects verify with the expected issuer and workflow identity.

Reviewed sourcedocs/operations/supply-chain-security.md

Helm or Compose?

Decision	Helm	Compose
Best fit	Existing Kubernetes platform and enterprise scheduling controls	Single Linux host or first controlled evaluation
Scale	Supports multi-replica API/worker topology with external dependencies	Single-node profile
Secrets	Kubernetes Secret references	Protected environment file and/or file references
Ingress	Optional chart-managed Ingress	Operator-managed reverse proxy or local bind
Upgrade	Chart values, signed target release, staged rollout	Release-owned installer entrypoint and Compose manifest

Install with Helm →Install with Compose →

Installation overview

Choose a deployment profile

Required dependencies

Baseline capacity and storage decisions

Required installation flow

Verify the release

Prepare configuration and secret references

Run preflight-only

Run dry-run or render review

Install and verify

Capture a baseline backup

Helm or Compose?