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; when you're ready for a real cluster, see the production deployment guide.

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 (recommended) 8 16 GB 80 GB SSD
Hard floor (demo/eval, small docs) 6 16 GB 60 GB SSD

4 vCPU is not viable, and earlier releases of this page said it was. The evaluation stack reserves just over 5 vCPU before anything starts, so on a 4-vCPU box the scheduler simply never places the last pods and they sit Pending — which looks like a hang rather than a sizing problem. Six fits the stack at rest; eight leaves room for a rolling update to schedule a replacement pod before retiring the old one, which is why eight is the recommendation.

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. On 16 GB, memory is the tighter budget of the two — the stack reserves close to 13 GB, so it runs out of RAM before it runs out of CPU. Three 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.
  • It must be free where container storage lives, not merely on the disk. Stock RHEL/LVM images cap /var at 10 GB and leave the rest of the volume group unallocated, so a "100 GB" VM still fails partway through the image pulls with no space left on device. Check df -h /var before you start, and extend the logical volume if it is short.
  • 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.

On a Podman host, run the installer with sudo. The single-node Kubernetes environment needs the system-level container socket and cannot set the host parameters it requires from inside a rootless user namespace. It installs a kubeconfig you own, so your ordinary kubectl works afterwards without sudo. Docker hosts need no sudo.

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 is a self-contained single-node install, separate from the production Helm deployment — it re-skins the same product for one small node and shares no state with a production cluster:

  • 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.
  • Survives reboots. The stack is configured to restart automatically, so closing a laptop lid or rebooting the cloud VM brings K-Lake back up on its own — no need to re-run the installer.
  • MCP enabled by default. The MCP server is on out of the box and reachable through the console's ingress, so you can connect an AI client immediately. (Production leaves MCP opt-in.)

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.