Documentation / Start here
Start here · v0.0.1 Install with Docker Compose Use the release-owned Linux entrypoint for a controlled single-node installation with explicit preflight and verification.
Audience Linux administrators, evaluatorsReading time 14 minCommands in context 10 guided stepsReviewed source fcc5871 · 30 July 2026
RC Exact release scope. This page documents the reviewed v0.0.1 source at fcc5871. Check release status before enabling a gated capability.
Supported scope The Compose release path implements the profile-single-node topology. It is appropriate for a controlled evaluation or an installation whose availability objective permits a single control-plane host. PostgreSQL and artifact data must still be durable and backed up.
The packaged manifest does not publish PostgreSQL to the host by default. Expose a database port only through an operator-reviewed override.
Run preflight and install The bundle verifies checksums, the signed compatibility manifest, signed release metadata, and digest pinning before starting the packaged Compose topology.
Do not skip the decision gates A successful preflight is followed by a dry-run. Only the final install command changes container state. Stop on any integrity, compatibility, secret-permission, port, storage, or startup-guard failure.
Commands for this step Optional Compose preflight invocation styles The config-file sequence below is the repeatable enterprise default. Use one preflight-only alternative only for a deliberate interactive or fully explicit review.
Use when needed Do not run these commands unless the described condition applies.
01
Read-only Linux
Run an interactive Compose preflight Use this when Use for a guided first evaluation on an interactive host.
Prompt for missing Compose and signed release metadata inputs while guaranteeing that services are not started.
Before you run it Docker Engine Docker Compose v2 curl Python 3 Interactive terminal on the approved Compose host Linux · compose-interactive-preflight Copy
./scripts/clusterpilot-selfhosted-install.sh \
--input-mode interactive \
--mode preflight-only✓ Expected result Configuration, signatures, release identity and Compose inputs validate with no service mutation.
Stop conditions and operator notes Use non-interactive ConfigPath mode for repeatable production automation. Reviewed source scripts/clusterpilot-selfhosted-install.sh02
Read-only Linux
Preflight every explicit Compose override Use this when Use when every Compose path and verification override must be visible.
Exercise the complete explicit installer surface in interactive input mode without starting services.
Before you run it Exact signed release files Protected environment file Docker Engine and Compose v2 Linux · compose-explicit-preflight Copy
./scripts/clusterpilot-selfhosted-install.sh \
--input-mode interactive \
--mode preflight-only \
--compose-file ./manifests/docker-compose.yml \
--env-file ./env/clusterpilot.env \
--project-name clusterpilot \
--profile production \
--public-key-file ./release-signing-public-key.pem \
--compatibility-manifest-file ./compatibility-manifest.json \
--compatibility-signature-file ./compatibility-manifest.json.sig \
--release-metadata-file ./release-metadata-index.json \
--release-metadata-signature-file ./release-metadata-index.json.sig \
--expected-release-version <release-version> \
--verify-timeout-seconds 300 \
--api-health-url http://127.0.0.1:8080/health✓ Expected result Every explicit input resolves and verifies; no container is started or replaced.
Stop conditions and operator notes Non-interactive mode requires --config-file and rejects these explicit Compose, verification and release-metadata overrides. The timeout range is 30–3600 seconds. Add --quiet only when the JSON result is retained. Reviewed source scripts/clusterpilot-selfhosted-install.shCommands for this step Run the supported Compose installation sequence Preflight and dry-run must pass before the installer creates or changes containers.
Run in order Complete each step successfully before continuing.
01
Read-only Linux
Run Compose preflight only Verify checksums, signatures, metadata, configuration and Compose inputs without starting services.
Before you run it Docker Engine Docker Compose v2 curl Python 3 Configured schema-versioned install JSON Linux · compose-preflight Copy
./scripts/clusterpilot-selfhosted-install.sh \
--input-mode non-interactive \
--mode preflight-only \
--config-file ./clusterpilot-selfhosted-install.json✓ Expected result Exit 0. Exit 10 is input validation; 11 is preflight failure.
Reviewed source scripts/clusterpilot-selfhosted-install.sh02
Read-only Linux
Run the Compose dry-run Render and validate the Compose mutation contract without starting the release.
Linux · compose-dry-run Copy
./scripts/clusterpilot-selfhosted-install.sh \
--input-mode non-interactive \
--mode dry-run \
--config-file ./clusterpilot-selfhosted-install.json✓ Expected result Exit 0 with no running service mutation.
Reviewed source scripts/clusterpilot-selfhosted-install.sh03
Changes state Linux
Install the single-node Compose profile Install and verify the release-owned Compose topology after a clean preflight.
Before you run it Release verification, preflight and dry-run pass Durable volumes and backup target ready Local API health bind is intentional Linux · compose-install Copy
./scripts/clusterpilot-selfhosted-install.sh \
--input-mode non-interactive \
--mode install \
--config-file ./clusterpilot-selfhosted-install.json✓ Expected result Exit 0. Exit 12 means mutation failure; 13 means post-install verification failure.
Reviewed source scripts/clusterpilot-selfhosted-install.shVerify and record the baseline ✓ All expected services are running and restart policies are active.
✓ The local health endpoint reports the expected release identity.
✓ PostgreSQL is durable, not accidentally host-published, and included in a tested backup.
✓ The artifact root is durable, protected, has sufficient capacity, and survives service restart.
✓ A reverse proxy terminates approved TLS before access is opened beyond localhost.
Commands for this step Verify and inspect the Compose deployment Use the release entrypoint for the acceptance decision and the detailed inspection commands for retained operational evidence.
Run in order Complete each step successfully before continuing.
01
Read-only Linux
Verify Compose without mutation Run the official verification mode against the existing installation.
Before you run it Existing Compose deployment Linux · compose-verify-only Copy
./scripts/clusterpilot-selfhosted-install.sh \
--input-mode non-interactive \
--mode verify-only \
--config-file ./clusterpilot-selfhosted-install.json✓ Expected result The API container is running and the configured health URL becomes successful before timeout.
Reviewed source scripts/clusterpilot-selfhosted-install.sh02
Read-only Linux
Run the canonical Compose verifier Verify a custom Compose path, project name, profile, timeout and health endpoint.
Before you run it Existing release bundle and Compose deployment Linux · compose-verify-script Copy
./scripts/clusterpilot-selfhosted-verify.sh \
--compose-file ./manifests/docker-compose.yml \
--env-file ./env/clusterpilot.env \
--project-name clusterpilot \
--profile production \
--timeout-seconds 300 \
--api-health-url http://127.0.0.1:8080/health✓ Expected result A JSON result identifies the running API container and reports status ready.
Reviewed source scripts/clusterpilot-selfhosted-verify.sh03
Read-only Linux
Inspect Compose services and logs Diagnose service state without dumping the protected environment file.
Before you run it Access to the Compose host Linux · compose-inspect Copy
docker compose --project-name clusterpilot \
--file ./manifests/docker-compose.yml \
--env-file ./env/clusterpilot.env \
--profile production ps
docker compose --project-name clusterpilot \
--file ./manifests/docker-compose.yml \
--env-file ./env/clusterpilot.env \
--profile production logs --tail 200 api✓ Expected result The API service is running; logs contain no raw secret values.
Reviewed source scripts/clusterpilot-selfhosted-verify.shProduction startup guards Production and Preprod fail closed when the database connection, artifact provider, secrets master key, key ID, or other mandatory safety settings are absent. Do not work around PRODUCTION_STARTUP_GUARD_FAILED or STARTUP_INVALID_CONFIGURATION by switching to a development environment.
Resolve startup and dependency failures → Commands for this step Stop the control plane without deleting durable data Use this only for an approved maintenance stop. It deliberately retains the database and artifact data.
Use when needed Do not run these commands unless the described condition applies.
01
Changes state Linux
Stop Compose while retaining durable data Stop the control plane for a maintenance window without deleting named volumes.
Before you run it Approved maintenance window No active lifecycle operations Backup complete Linux · compose-stop Copy
docker compose --project-name clusterpilot \
--file ./manifests/docker-compose.yml \
--env-file ./env/clusterpilot.env \
--profile production stop✓ Expected result Services stop and durable database/artifact volumes remain present.
Reviewed source docker-compose.selfhosted-release.yml