Installation

LeapView ships as a public multi-architecture container image. Pulling that image is the primary onboarding path; no source checkout, registry login, or installer is required. One running container with one persistent state volume is one LeapView instance.

Current controlled-testing release

The supported candidate is v0.2.0-rc.1, built from revision dfb3086d59284c6597180e99a7d07f41e36a7f7e. It is a release candidate for controlled testing, not GA. Its immutable image is:

ghcr.io/flidai/leapview@sha256:8b32fc291c86005c69c2ca1fa673dcaa4cb84d39cfc951e065a2775b122f81d9

Download the version-matched operations bundle and checksum for the machine that will run leapviewctl:

Before you begin

Install Docker Engine and Docker Compose. A public instance also needs a DNS name, HTTPS, durable secret storage, PostgreSQL, and provider-native recovery storage.

Choose an installation

The supported installation is the PostgreSQL-backed Compose deployment below. It uses the same native control, delivery, and recovery architecture in local, staging, and production environments; there is no embedded control-plane mode.

Run a durable production instance

The released Compose package is the recommended operations layer around the same public image. It is not a separate LeapView distribution. It supplies hardened container settings, generated production secrets, and optional Caddy HTTPS. Production PostgreSQL/DuckLake backup and restore remain provider-native operations covered by the PostgreSQL operations guide and Backup and restore guide; Compose does not provide image-and-state upgrade or rollback.

1. Select, download, verify, and extract the current platform archive:

VERSION='v0.2.0-rc.1'
case "$(uname -s)" in
  Linux) OS=linux ;;
  Darwin) OS=darwin ;;
  *) echo "unsupported OS: $(uname -s)" >&2; exit 1 ;;
esac
case "$(uname -m)" in
  x86_64|amd64) ARCH=amd64 ;;
  arm64|aarch64) ARCH=arm64 ;;
  *) echo "unsupported architecture: $(uname -m)" >&2; exit 1 ;;
esac
ARCHIVE="leapview-compose-${VERSION}-${OS}-${ARCH}.tar.gz"
BASE="https://github.com/flidai/leapview/releases/download/${VERSION}"
curl --fail --location --remote-name "$BASE/$ARCHIVE"
curl --fail --location --remote-name "$BASE/$ARCHIVE.sha256"
if command -v sha256sum >/dev/null 2>&1; then
  sha256sum --check "$ARCHIVE.sha256"
else
  shasum -a 256 --check "$ARCHIVE.sha256"
fi
tar -xzf "$ARCHIVE"
cd "${ARCHIVE%.tar.gz}"
if command -v sha256sum >/dev/null 2>&1; then
  sha256sum --check SHA256SUMS
else
  shasum -a 256 --check SHA256SUMS
fi

2. Confirm every checksum reports OK. The archive contains an immutable application image reference, the base Compose stack, an optional Caddy HTTPS overlay, and the native Go leapviewctl operations binary.

3. Copy the deployment and application templates. Before initialization, provision or select the external PostgreSQL provider, then fill in the control/DuckLake URLs, distinct roles, and target delivery-pool identities in leapview.env:

cp deployment.env.example deployment.env
cp leapview.env.example leapview.env
# Run pool bootstrap without --apply and copy its deterministic pool_id and
# compatibility_digest into leapview.env before init.
./leapviewctl init \
  --admin-email admin@example.com \
  --domain dash.example.com \
  --environment prod
# Now inject the operation-only DuckLake migrator credential and repeat the
# exact pool bootstrap command with --apply before starting the service.

4. Start the instance and consume the one-time credentials:

./leapviewctl start
./leapviewctl first-login

Before adoption, run ./leapviewctl qualify installed-candidate from the extracted archive. QUALIFICATION.md maps every automated assertion to the corresponding human check, including anonymous distribution, the five-minute sample, audited authorization denial, restart persistence, and recovery-readiness checks using the separately managed secret configuration.

Initialization treats --domain as the canonical public hostname and derives LEAPVIEW_PUBLIC_URL=https://<domain>, the allowed host, and the Caddy domain from it. It also generates production secrets, creates the persistent volume, validates the resulting production configuration, and atomically creates a forced-change local administrator plus a restricted publisher token. first-login prints and deletes that one-time credential file.

The Compose bundle does not include PostgreSQL. Initialization preserves the operator-supplied PostgreSQL and delivery-pool settings and fails with the missing variable name when the clean-slate production contract is incomplete. The pool-bootstrap dry run precedes initialization only to derive identities; the applying run follows initialization because it verifies the newly applied control baseline. Do not store the operation-only DuckLake migrator credential in the serving leapview.env.

leapviewctl is an optional production operations controller, not a prerequisite for pulling or running LeapView. It invokes the installed Docker Compose CLI and does not require Bash or direct access to the Docker socket API. You may manage the image with your existing container platform if it preserves the same single-process, persistent-home, initialization, provider-native recovery, and environment contracts.

Operators integrating the image directly must set the documented production environment first. The initialization command authenticates the dedicated control migrator, applies or verifies the exact control baseline, closes that owner-capable pool, and creates the first administrator through the ordinary control runtime role:

leapview admin initialize --format json > initial-credentials.json
# Store the mode-0600 file in the target secret manager before acknowledging it.
leapview admin initialize --acknowledge-credentials

leapview admin delivery pool bootstrap \
  --pool pool-identity.json \
  --evidence shared-pool-evidence.json
leapview admin delivery pool bootstrap \
  --pool pool-identity.json \
  --evidence shared-pool-evidence.json \
  --apply

Set LEAPVIEW_DELIVERY_PHYSICAL_POOL_ID and LEAPVIEW_DELIVERY_PHYSICAL_POOL_COMPATIBILITY_DIGEST to the exact values printed by the bootstrap command, then start leapview serve --production. Both initialization and pool bootstrap are exact-replay operations. After credential acknowledgement, initialization reports that the instance already exists and never returns the credential material again. The Compose controller performs the initialization and one-time credential handoff atomically; target provisioning must still supply the reviewed pool identity and evidence.

The Caddy overlay is enabled by default. Pass --no-https only when an existing trusted HTTPS proxy fronts the localhost-bound application port. This changes where TLS terminates, not the external scheme: the generated public URL remains HTTPS, secure cookies remain enabled, and forwarded host and scheme headers must come only from that trusted proxy.

Understand the instance boundary

Production authority is the PostgreSQL control plane and PostgreSQL-backed DuckLake catalog, with Parquet and managed objects protected in their configured object stores. The local volume contains runtime state and caches; it is not a PostgreSQL recovery artifact. Use provider-native PostgreSQL backup/PITR and DuckLake/object-store versioning or replication, coordinated to one recovery point.

Use separate Compose project directories and names for development, staging, and production. Never scale one project to multiple application containers or point two processes at the same volume.

The controller exposes only basic lifecycle operations:

./leapviewctl status
./leapviewctl logs
./leapviewctl start

Use the container platform's immutable image rollout and change-management workflow for upgrades or host rollback. The target-level leapview rollback command remains available for a retained serving generation, but it does not restore PostgreSQL, DuckLake, object-store, or Compose state. Those recovery operations are external; use the PostgreSQL operations guide and Backup and restore guide.

Contributor installation

Source checkout is the contributor workflow, not the production packaging path. Install the Go version from go.mod, Bun, and Task, then run:

task node:deps
task generate
task dev

task dev provisions a loopback-only PostgreSQL 18 service scoped to the worktree, runs the local physical-pool qualification/bootstrap once, and starts one native PostgreSQL target with the private authoring watcher. The generated credentials remain in .tmp/postgres-dev.env (mode 0600); do not reuse them outside this worktree. For a durable rollout, use the canonical plan, build, and publish CANDIDATE_ID commands shown above. Use task dev:status, task dev:logs, and task dev:stop for lifecycle operations. Run task ci before handing off substantial changes.

Validate

For the local image path, run docker inspect --format '{{.State.Health.Status}}' leapview and expect healthy. For Compose, run docker compose config --quiet and ./leapviewctl status. A production application container must report healthy, and its resolved image must include a sha256 digest.

For a released Compose archive, verify that every shipped surface has the same identity before trusting the deployment:

sha256sum --check leapview-compose-*.tar.gz.sha256
cat release-identity.json
./leapviewctl version --json
LEAPVIEW_IMAGE="$(cat image-reference.txt)"
docker image inspect "$LEAPVIEW_IMAGE" \
  --format '{{index .Config.Labels "org.opencontainers.image.version"}} {{index .Config.Labels "org.opencontainers.image.revision"}}'
docker run --rm "$LEAPVIEW_IMAGE" version --json

The semantic version and full Git revision must agree across release-identity.json, leapviewctl, the server binary, and the OCI labels. A release reports "dirty": false and "development": false; an ordinary local or candidate build reports version development and can never claim the release version. LeapView uses the release commit timestamp as buildTime so the identity remains reproducible.

After startup, compare the same identity through the authenticated capabilities endpoint using a token authorized to use the project:

curl --fail --silent --show-error \
  --header "Authorization: Bearer $LEAPVIEW_API_TOKEN" \
  "$LEAPVIEW_PUBLIC_URL/api/v1/capabilities"

The /api/v1/capabilities response fields buildVersion, buildRevision, buildTime, buildDirty, and buildDevelopment must match the packaged identity.

Verify

Open the configured HTTPS URL, sign in with the temporary administrator credentials, and change the password when prompted. Verify the instance identity and readiness through the authenticated capabilities endpoint; follow the PostgreSQL operations guide and Backup and restore guide for PostgreSQL/DuckLake protection.

Troubleshooting

Use ./leapviewctl logs when startup or health checks fail. A second process cannot open the same state volume, and an instance initialized for one environment cannot be started as another; use a separate Compose project and volume instead of changing LEAPVIEW_ENVIRONMENT.

Next steps

Continue with Self-hosting, Connect a data source, and Build your first dashboard.

The commands above illustrate the installation workflow. Use the generated admin CLI reference, serve CLI reference, and environment variable reference for the exact current command and runtime contracts.