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/yacobolo/leapview@sha256:8b32fc291c86005c69c2ca1fa673dcaa4cb84d39cfc951e065a2775b122f81d9

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

Before you begin

Install Docker Engine. The five-minute path below needs no source checkout, registry login, Go, Bun, Task, manual YAML, or external dataset. A public production instance additionally needs Docker Compose, a DNS name, HTTPS, durable secret storage, and off-host backups.

Run the five-minute evaluation

Pull the public image and start its self-contained evaluator:

IMAGE='ghcr.io/yacobolo/leapview@sha256:8b32fc291c86005c69c2ca1fa673dcaa4cb84d39cfc951e065a2775b122f81d9'
docker pull "$IMAGE"
docker run --detach --name leapview-evaluate --init \
  --publish 127.0.0.1:8080:8080 \
  --volume leapview-evaluate:/var/lib/leapview \
  "$IMAGE" evaluate

The evaluator generates private runtime secrets, creates a forced-change local administrator, stages the small synthetic dataset shipped in the image, and atomically deploys one disposable workspace. It prints no secret to the container log. Wait for the health check, then consume the credentials once:

docker exec leapview-evaluate leapview healthcheck
docker exec leapview-evaluate leapview evaluate first-login

Open http://localhost:8080, sign in, and change the temporary password. Choose Five-minute Sales Evaluation, select a State, and confirm that the Orders KPI, revenue chart, and governed order table update together. This exercises authentication, immutable serving-state deployment, managed data, semantic query planning, DuckDB execution, filters, and table rendering.

The 127.0.0.1 publish address is part of the security boundary. Evaluation mode intentionally uses local HTTP and generated local secrets; do not expose it on a LAN or the internet and do not treat the synthetic workspace as production seeding.

Persistence, diagnostics, and cleanup

The named volume preserves the initialized instance, changed password, managed data, and active deployment:

docker restart leapview-evaluate
docker exec leapview-evaluate leapview healthcheck

If initialization does not become healthy, inspect the deterministic bootstrap log and container state:

docker logs leapview-evaluate
docker inspect --format '{{.State.Health.Status}}' leapview-evaluate

first-login is deliberately one-time. If its output was lost, reset the disposable evaluator. Removing the container does not remove its volume:

docker rm --force leapview-evaluate

Delete the persisted evaluation instance only when a full reset is intended:

docker volume rm leapview-evaluate

The evaluator is pinned to the supported candidate digest so that the instructions, runtime, and retained evidence cannot drift independently.

Move beyond the sample

The bundled synthetic project exists only to qualify the product journey. To connect real data, start with Connect a data source. For a durable or externally reachable instance, use the versioned Compose release below; it adds immutable image pinning, HTTPS, backups, and state-aware upgrades.

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, optional Caddy HTTPS, validated backup and restore, and paired image-and-state 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 template and initialize the instance:

cp deployment.env.example deployment.env
./leapviewctl init \
  --admin-email admin@example.com \
  --domain dash.example.com \
  --environment prod

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

./leapviewctl start
./leapviewctl first-login

Before adoption, run the archive's bundled ./qualification/qualify.sh. QUALIFICATION.md maps every automated assertion to the corresponding human check, including anonymous distribution, the five-minute sample, audited authorization denial, restart persistence, and an isolated restore 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.

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, backup, and environment contracts.

Operators integrating the image directly must set the documented production environment first, run leapview admin initialize --format json, store its one-time output securely, acknowledge that output, and then start leapview serve --production. The Compose controller performs those steps atomically.

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

All application-owned local state is under /var/lib/leapview in one named volume. External customer sources such as S3 remain external and are not included in instance backups. Local managed uploads are included; S3-backed managed uploads require bucket-native backup and versioning.

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.

Common operations are:

./leapviewctl status
./leapviewctl logs
./leapviewctl backup
./leapviewctl restore backups/leapview-<timestamp>.tar.gz
./leapviewctl upgrade ghcr.io/flidai/leapview@sha256:<digest>
./leapviewctl rollback --confirm

Upgrades create a state checkpoint. A failed health check restores both the previous image and state; manual rollback requires confirmation because it discards state created after the checkpoint.

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

Use task dev:status, task dev:logs, and task dev:stop for the worktree-local server. 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 a workspace:

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. Then create a backup with ./leapviewctl backup and confirm that both the archive and its checksum exist in backups/.

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.