Installation

LeapView publishes an authoring CLI and a multi-architecture server image. For local analytics authoring, follow Install the authoring CLI and the analytics development workflow. The CLI provisions its checkout-scoped local runtime through Docker.

For self-hosting, use the version-matched Compose operations package below. A server instance requires PostgreSQL control and DuckLake databases plus configured managed-object storage; the direct Compose flow uses an external provider, while the Linux host installer also offers an explicitly selected single-node bundled PostgreSQL profile. Its local volumes are not a complete recovery copy. Changing LeapView itself uses the separate contributor workflow.

Current controlled-testing release

The current alpha for controlled evaluation is v0.4.0-alpha.1, built from revision 4eb1476080d658ca545952865aab4e30ba556809. This release uses control schema 67. Before upgrading from v0.3.0-alpha.1, review Upgrades and migrations for migrations 029–067, replacement credentials, and paired-state recovery. It is an alpha for controlled testing, not GA or a production-readiness guarantee. Interfaces may change and workflows may be incomplete. Do not assume an in-place upgrade from the SQLite-era v0.2.0-rc.1 release; review the release compatibility notes and use a separately provisioned target for evaluation. Its immutable image is:

ghcr.io/flidai/leapview@sha256:d10eae33ff81b1cead0e83c3d105ae99d180d358518dcbc6c1c4b0c7f938f822

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, a selected PostgreSQL profile, and provider-native recovery storage.

Choose an installation

The self-hosting 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.4.0-alpha.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.

Direct Compose initialization uses PostgreSQL URLs and pool settings supplied in leapview.env and fails with the missing variable name when the clean-slate production contract is incomplete. The host installer may instead select the bundled profile in its private operator bootstrap input; the self-hosting guide describes its retry behavior and recovery limits. Both paths use the same delivery-pool admission and require reviewed physical-pool identity/evidence. 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 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-backed server. On a new database, the authenticated workflow creates private development credentials, stages the bundled managed-data fixture, and publishes the sample candidate. Subsequent starts reuse active managed data; task dev:publish explicitly publishes a fresh candidate with scoped authority while skipping data sync. The generated database credentials remain in .tmp/postgres-dev.env (mode 0600); do not reuse them outside this worktree. The browser uses a real local session by default. Open the login page and choose Continue as Local Developer; the loopback-only shortcut creates the same durable, audited browser session as password login. Use task dev:credentials only to reveal the worktree-private login stored under .tmp/dev-auth/ when explicitly testing the password flow; its separate, expiring publisher token is not displayed. The development URL is pinned across restarts and localhost cookies are isolated per worktree. Managed development sessions last up to 30 days, while production retains its eight-hour lifetime. Sign-out, browser-data clearing, database reset, or expiry requires another click. task dev:auth-smoke checks browser login, group-role activation after a fresh release, revocation, and cleanup. For a durable rollout, follow Develop, review, and publish. Use task dev:status, task dev:logs, and task dev:stop for lifecycle operations. Run task ci before handing off substantial changes.

Validate

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 --format 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 --format 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.