Skip to main content
Version: Next

TUI Installer

The Lakehousecat TUI Installer (lhc-installer) is the fastest way to run Lakehousecat locally. It is a terminal application that guides you through the complete setup — from system check to a running instance — with no manual Kubernetes or Helm commands required.

Recommended for evaluation

The TUI Installer is the recommended path for local evaluation. It handles Minikube cluster creation, operator deployment, and instance configuration automatically.

Prerequisites​

Before starting, ensure the following are installed and running:

RequirementMinimumNotes
Operating SystemmacOS, Linux, or Windows 11macOS on Apple Silicon (arm64), Linux (amd64/arm64), Windows 11 (amd64). Intel-based Macs and Windows on ARM64 are not supported
RAM16 GB minimum, 24 GB recommendedAvailable to Docker — checked via docker info. Below 16 GB installation is blocked; 16–24 GB shows a warning
CPU8 cores minimum, 10 cores recommendedAvailable to Docker — checked via docker info. Below 8 cores installation is blocked; 8–9 cores shows a warning
Disk50 GB freeSSD strongly recommended
DockerAny recent versionMust be running before launch. On Windows: Docker Desktop required — see Windows — Setting Up Prerequisites
MinikubeAny recent versionMust be installed. macOS: brew install minikube · Windows: winget install --id Kubernetes.minikube --accept-package-agreements --accept-source-agreements
kubectlAny recent versionMust be installed. macOS: brew install kubectl · Windows: winget install -e --id Kubernetes.kubectl · Linux: see the official install docs
Helm3.xMust be installed. macOS: brew install helm · Windows: winget install -e --id Helm.Helm · Linux: see the official install docs

kubectl and helm are not installed automatically by the TUI installer — like Docker and Minikube, the Dependency Check step (Step 3) only verifies they're present on your PATH and tells you what to run if they're missing.

Install the TUI​

macOS and Linux​

Download and run the installer with a single command:

curl -fsSL https://install.lakehousecat.com | bash

Alternatively, download the binary directly and make it executable:

chmod +x lhc-installer
./lhc-installer

Windows​

Run the following command in PowerShell 5.1 or later:

iex (iwr https://install.lakehousecat.com/install.ps1).Content

This downloads the lhc-installer.exe binary and launches the TUI installer.

Windows Prerequisites

Docker Desktop must be installed and running before launching the installer. Minikube runs inside Docker Desktop and uses it as its driver — no separate VM configuration is required beyond what Docker Desktop sets up automatically.

The installer supports Windows 11 on AMD64 (Intel/AMD) devices. Windows on ARM64 (Snapdragon/Qualcomm) is not supported; the bootstrap script stops with a clear message on such devices.

Windows — Setting Up Prerequisites​

On Windows, Docker Desktop, Minikube, kubectl, and Helm must all be installed before you launch the TUI installer. The installer does not — and cannot — install any of them for you.

Why the installer can't do this automatically

Docker Desktop is licensed, third-party software with its own end-user license agreement. Installing it — and Minikube, kubectl, and Helm, all distributed via the Windows Package Manager — requires the user to explicitly accept package and source agreements and, in most environments, administrator privileges. Silently installing third-party software on a user's machine on their behalf is not something the TUI installer does — you install these prerequisites yourself, once, with full visibility into what's being installed and what you're agreeing to. The installer's Dependency Check step (Step 3) only verifies each tool is present and tells you what to run if it's missing.

Hardware virtualization must be enabled in the BIOS/UEFI

Docker Desktop requires hardware virtualization (Intel VT-x or AMD-V/SVM) to be enabled in your system's BIOS/UEFI settings. On many consumer and gaming PCs this is disabled by default. If it's off, Docker Desktop will install without errors but will fail to start afterwards.

To check: open Task Manager → Performance tab → CPU, and look for "Virtualization." If it says "Disabled," reboot into your BIOS/UEFI setup (varies by manufacturer, commonly Del or F2 during boot) and enable the setting — look for "SVM Mode" (AMD) or "Intel VT-x" / "Virtualization Technology" (Intel), usually under a CPU or Advanced configuration menu.

Run the following in a PowerShell window with administrator rights:

winget install --id Docker.DockerDesktop --accept-package-agreements --accept-source-agreements
winget install --id Kubernetes.minikube --accept-package-agreements --accept-source-agreements
winget install -e --id Kubernetes.kubectl --accept-package-agreements --accept-source-agreements
winget install -e --id Helm.Helm --accept-package-agreements --accept-source-agreements
Why the --accept-*-agreements flags matter

Without these flags, winget prompts interactively for confirmation of the Microsoft Store source terms and the package's license agreement. In many terminal environments (including remote sessions) this confirmation prompt does not render properly and the install appears to hang with no visible way to respond. Passing --accept-package-agreements --accept-source-agreements accepts both agreements upfront and lets the install run non-interactively to completion.

Open a new PowerShell window after installing kubectl/Helm

winget updates the PATH environment variable, but your current PowerShell session doesn't pick up the change automatically — running kubectl or helm right after installing them fails with "command not recognized" even though the install succeeded. Either open a new PowerShell window, or reload PATH in the current one:

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

Verify with kubectl version --client and helm version --short before launching the TUI installer — the Dependency Check step re-runs on every Enter press, so a stale PATH in the installer's own process (inherited at launch) also means restarting the installer itself after a fresh install, not just opening a new terminal for manual commands.

After installation, Docker Desktop needs one manual first launch:

  1. Start Docker Desktop from the Start menu.
  2. Accept the Docker Subscription Service Agreement when prompted.
  3. If prompted to add your user to the docker-users group, confirm and sign out/in (or restart) to apply it.
  4. Wait for the Docker Desktop whale icon in the system tray to show "Docker Desktop is running."

Verify all four prerequisites are ready before launching the installer:

docker info --format "{{.ServerVersion}}"
minikube version --short
kubectl version --client
helm version --short

All four commands should return a version number with no errors. If docker info errors out, Docker Desktop is installed but not yet running — start it and wait for it to finish initializing.

The installer checks Docker Desktop's configured resource limits, not your total hardware

The System Requirements Check (Step 2 below) measures RAM and CPU as reported by Docker (docker info), not your machine's physical totals. This means the check reflects whatever limit is set in Docker Desktop → Settings → Resources → Advanced, which can be lower than what your hardware actually has — especially right after a fresh install.

Before launching the installer, open Docker Desktop's settings and make sure Memory is set to at least 16 GB (24 GB recommended) and CPUs to at least 8 (10 recommended), then apply and restart Docker Desktop. On a machine with less physical RAM/CPU than these minimums, lower Docker Desktop's allocation as needed, but expect the installer to warn or block accordingly.

Installation Flow​

The TUI walks you through seven screens in sequence. Each step is tracked and resumed automatically if you restart the installer.

Step 1 — Welcome​

The installer displays a welcome message and disclaimer. Press Enter or y to accept and continue, or n to quit.

Step 2 — System Requirements Check​

The installer verifies your system meets the minimum requirements:

  • Available RAM ≥ 16 GB (hard minimum) / ≥ 24 GB recommended
  • Available CPU cores ≥ 8 (hard minimum) / ≥ 10 recommended
  • Free disk space ≥ 50 GB

You can continue with a warning if requirements are not fully met, but performance may be degraded.

Step 3 — Dependency Check​

The installer checks four dependencies: Docker, Minikube, kubectl, and Helm. Each check is a presence check only — it confirms the tool is installed and, for kubectl/Helm, runnable (a version query), but does not verify cluster connectivity, permissions, or Docker Desktop's actual resource allocation (that's Step 2).

None of the four are installed automatically. If any is missing, the screen stays on this step and shows a concrete install command for your platform (for example winget install -e --id Helm.Helm on Windows, brew install helm on macOS). Install the missing tool(s) and press Enter to re-run the check — no restart needed.

DependencyBehavior if missing
DockerInstallation stops — Docker must be installed and running
MinikubeInstallation stops — Minikube must be installed
kubectlInstallation stops — kubectl must be installed
HelmInstallation stops — Helm must be installed

Step 4 — Registration​

The installer opens your browser to the Lakehousecat portal for registration. This step:

  1. Starts a local callback server (temporary, runs only during this step)
  2. Opens your browser to the Lakehousecat portal login page
  3. You sign in or create a free account at portal.lakehousecat.com
  4. The portal redirects back to the installer with your license credentials

The following information is received automatically and stored in ~/.lhc/state.json:

  • Handshake Key — used to authenticate the Kubernetes operator
  • Customer ID — your account identifier
  • Email — used as the admin account for the Lakehousecat instance

Registration times out after 5 minutes if the browser flow is not completed.

Step 5 — Setup & Deployment​

The installer runs seven sequential steps automatically:

StepAction
1. Create Minikube clusterStarts a Minikube cluster with the profile lakehousecat using the Docker driver. Resources are allocated automatically based on your system (up to 8 CPUs and 24 GB RAM).
2. Add Helm repositoryAdds https://charts.lakehousecat.com as the lakehousecat Helm repository.
3. Create namespacesCreates the lhc-operator namespace and the instance namespace lhc-instance. The instance namespace comes first because the operator only gets rights in the namespaces it is installed for and does not create them.
4. Create license service proxyDeploys a small in-cluster proxy that allows the operator to reach the Lakehousecat licensing service.
5. Create handshake secretCreates the lhc-handshake-secret Kubernetes secret in lhc-operator using your handshake key from registration.
6. Install Lakehousecat operatorInstalls the lakehousecat-operator Helm chart with targetNamespaces={lhc-instance} and waits up to 10 minutes for the operator to be ready.
7. Setup Lakehousecat instanceApplies the evaluation Lakehousecat Custom Resource in the lhc-instance namespace, pre-configured with your account details.

Step 6 — Deployment Progress​

The installer monitors the deployment until all services are running. Lakehousecat deploys a complete stack of interconnected services — this typically takes about 10 minutes. Most of that time is spent pulling container images, so the exact duration depends on your internet bandwidth (for example, Wi-Fi quality).

Step 7 — Access​

When deployment is complete, the installer displays your access credentials and automatically starts a port-forward to the ingress controller:

URL:      http://127.0.0.1:42027
Email:    <your-email>
Password: <generated-admin-password>

The port-forward runs in the background while the TUI is open. Open the displayed URL in your browser and log in with the credentials shown.

If the automatic port-forward fails, the installer shows the manual fallback command to run in a separate terminal:

kubectl port-forward -n ingress-nginx svc/ingress-nginx-controller 42027:80

Evaluation Instance Configuration​

The evaluation instance is pre-configured for local use:

  • Tier: FREE (1 user, 10 data sources)
  • Replicas: 1 per service (no high availability)
  • Storage: SeaweedFS in standalone mode (50 Gi)
  • Monitoring: Disabled
  • Architecture: Detected automatically (amd64 or arm64)
  • Sample data: Enabled by default — a retail-demo sample (Custom Model, datasources, and dashboards) is installed automatically once deployment completes, so you can explore Lakehousecat immediately without connecting your own data first.

Resource allocation per service is optimized for a single-machine evaluation environment. Autoscaling requires a STANDARD or higher subscription.

State and Resumability​

Installation state is persisted to ~/.lhc/state.json. If the installer exits unexpectedly, restarting it resumes from the last completed step — you do not need to restart from scratch.

Uninstall​

To remove the evaluation setup including the Minikube cluster:

lhc-installer --uninstall

On Windows, run lhc-installer.exe --uninstall instead.

This removes the lakehousecat Minikube profile and the Lakehousecat home directory (~/.lhc), including the saved installation state — so a later run of the installer starts from scratch. The command finishes with All Lakehousecat evaluation data has been removed.

On Windows, if the installer itself runs from inside ~/.lhc, it cannot delete its own executable while it is running. It removes everything else, then deletes the executable a moment after the process exits — no error is shown and no manual cleanup is needed.

Next Steps​

Once your instance is running: