Skip to content

One-command POC on a single VM

Stand up the full KDBL Context Lake (K-Lake) stack — database, work queue, workers, API, web console, and a CPU content extractor — on one Docker/Podman VM, with a demo tenant created and its PAT printed, in a single command. This is the fastest path to an evaluable system; for a production cluster, contact your KDBL representative for the installation bundle.

Licence required. The stack is fail-closed — it refuses to start without a valid licence. Ask your KDBL representative for a 30-day evaluation licence and set it before running:

export KDBL_LICENCE='KDBLLIC1.<...the blob KDBL provided...>'

Run the single-command evaluation installer included in your evaluation bundle. It provisions a self-contained single-node Kubernetes environment on the VM, applies the evaluation configuration, and onboards a demo tenant. When it finishes it prints the web console URL, the cluster-admin token, and the demo tenant's PAT, and maps the VM's ports 80/443 onto the cluster so the console is served at http://<vm-ip>/ with no extra setup.

Sizing

The box runs several memory tenants at once — the database, the content extractor, and the Kubernetes control plane.

Profile vCPU RAM Disk
Comfortable (full minimal stack) 8 16 GB 80 GB SSD
Hard floor (demo/eval, small docs) 4 16 GB 60 GB SSD

Do not go below 16 GB RAM. 8 GB looks plausible on paper but gets squeezed the moment the extractor parses a real PDF while the database is ingesting. Two things bite specifically on a single VM:

  • Disk, not RAM, is the usual first failure. The worker and especially the content-extractor images are multi-GB; image churn on a small root disk can trigger eviction of pods. Give it ≥60–80 GB on SSD.
  • The database's shared memory. The default container shared-memory size is too small for eval and can surface as crawl stalls rather than an obvious OOM. The evaluation configuration sizes it appropriately; raise it further if you see stalls under a heavier corpus.

This is eval-scale guidance. Large-corpus ingest (10M+ rows) is a different, much larger sizing conversation, and a GPU extractor changes the picture entirely.

How the evaluation configuration differs from production

The evaluation configuration re-skins the production deployment for a single small node — it is additive and leaves the production manifests untouched:

  • One replica of every component (no autoscaling).
  • Database sized for eval rather than production throughput.
  • Worker at reduced concurrency on the direct write path (the high-throughput path is overkill at eval scale).
  • Extractor at single-file concurrency with a per-file size ceiling to bound memory.

Options

The installer accepts a few flags:

  • Bring up infrastructure only and skip tenant onboarding.
  • Name the demo tenant (defaults to demo).
  • Skip the content extractor.
  • Tear the whole environment down.

See --help on the installer for the exact flag names.

Private images

During the evaluation period the K-Lake container images may be private. If so, the installer accepts registry credentials (server, username, read token) and creates an image pull secret for you. Once the images are made public for open evaluation, no token is needed and they are pulled anonymously.

After it's up

The installer prints a web console URL, a cluster-admin token, and the demo tenant's PAT. Point the kdbl-control CLI at the instance to verify health and onboard your first source:

export KDBL_URL=http://<vm-ip>
export KDBL_TOKEN=<ADMIN_TOKEN>   # cluster-admin token printed by the installer

# Health check
kdbl-control --api-url "$KDBL_URL" --api-token "$KDBL_TOKEN" doctor

# First source + crawl, as the demo tenant (use the demo PAT it printed)
kdbl-control --api-url "$KDBL_URL" --api-token "<DEMO_PAT>" init

Then open http://<vm-ip>/ and follow the quick start to get a grounded, verifiable answer.

Troubleshooting

Symptom Fix
Pods Pending on Insufficient cpu/memory VM too small — see sizing above.
Pods ImagePullBackOff Private images need a pull token — supply registry credentials (see "Private images"); check the package exists for this version.
Crawl stalls The database's shared-memory size is too small — raise it (see sizing).
Extractor pod slow to start The content-extractor image is multi-GB; the first pull can take minutes. Startup doesn't block on it.
Re-running the installer Safe. The environment is reused and onboarding reuses the tenant.