Skip to main content
Version: Next

Manual Setup

Use the TUI Installer instead

The TUI Installer handles all steps on this page automatically. Use the manual setup only if you need full control over the Kubernetes configuration or are integrating into an existing setup.

Deploy Lakehousecat locally on your Mac or Linux machine for single-user evaluation, development, and testing using Minikube.

Prerequisites​

System Requirements​

  • 8 CPU cores (minimum) / 10 cores (recommended) — below 8 cores, Kubernetes cannot schedule all services (~6.8 cores total CPU requests)
  • 16 GB RAM (minimum) / 24 GB RAM (recommended) — below 16 GB is not supported
  • 50 GB free disk space — SSD strongly recommended
  • macOS or Linux

Required Software​

  • Docker — Must be running before starting Minikube
  • Minikube — The only supported local Kubernetes option
  • kubectl — Kubernetes command-line tool
  • Helm — Version 3.8 or higher
  • Handshake Key — From portal.lakehousecat.com (free registration)

Step 1: Install Minikube​

macOS:

brew install minikube

Linux:

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

Verify installation:

minikube version

Step 2: Start Minikube Cluster​

Lakehousecat runs in a dedicated Minikube profile named lakehousecat. This keeps the deployment fully isolated from any other Minikube clusters you may have running.

minikube start \
  --profile=lakehousecat \
  --cpus=10 \
  --memory=32768 \
  --disk-size=50g \
  --driver=docker \
  --kubernetes-version=v1.29.0
tip

Recommended values for stable operation. Minimum supported: --cpus=8 --memory=16384. Below 8 CPUs, Kubernetes cannot schedule all service pods. Below 16 GB RAM, OOM kills are likely.

Verify the cluster is running:

minikube status --profile=lakehousecat
kubectl cluster-info
kubectl get nodes

Step 3: Enable Required Addons​

minikube addons enable storage-provisioner --profile=lakehousecat
minikube addons enable default-storageclass --profile=lakehousecat

Step 4: Install Helm​

macOS:

brew install helm

Linux: See helm.sh/docs/intro/install.

Step 5: Install Lakehousecat Operator​

helm repo add lakehousecat https://charts.lakehousecat.com
helm repo update

# Create the instance namespace first: the operator only gets rights in the
# namespaces listed in targetNamespaces and does not create them.
kubectl create namespace lhc-instance

helm install lhc-operator lakehousecat/lakehousecat-operator \
  --namespace lhc-operator \
  --create-namespace \
  --set "targetNamespaces={lhc-instance}" \
  --wait

Verify the operator is running:

kubectl get pods -n lhc-operator

Step 6: Create Handshake Secret​

Get your handshake key from portal.lakehousecat.com, then create the secret:

kubectl create secret generic lhc-handshake-secret \
  --from-literal=handshake-key=YOUR_HANDSHAKE_KEY_FROM_PORTAL \
  -n lhc-operator
Optional feature secrets

The handshake secret is the only one required for a basic evaluation. Optional features — pre-configured models, Mapbox maps, external S3 storage, SSO — read their credentials from additional pre-created secrets. See Required Secrets for the full list and helper scripts. Missing optional secrets do not block the deployment; the feature is simply skipped until you add the secret.

Step 7: Deploy Lakehousecat Instance​

Create a minimal configuration for local evaluation:

lhc-instance.yaml
apiVersion: lhc.lakehousecat.com/v1alpha2
kind: Lakehousecat
metadata:
  name: local-eval
spec:
  license:
    handshakeSecretName: "lhc-handshake-secret"

  customer:
    namespace: "lhc-instance"
    adminemail: "admin@example.com"

  version: "0.0.42"
  architecture: "amd64"                   # Use "arm64" for Apple Silicon

  analytics:
    replicaCount: 1
    resources:
      requests:
        cpu: "500m"
        memory: "2Gi"
      limits:
        cpu: "1"
        memory: "4Gi"

  lhc:
    replicaCount: 1
    resources:
      requests:
        cpu: "500m"
        memory: "1Gi"

  ui:
    replicaCount: 1
    resources:
      requests:
        cpu: "250m"
        memory: "512Mi"

  postgresql:
    persistenceSize: "10Gi"

  clickhouse:
    persistence:
      size: "20Gi"

  objectStorage:
    volume:
      persistence:
        size: "10Gi"
Storage class and size are a one-time choice

storageClass and volume sizes are set once, before this first apply — changing them later is a data migration, not an edit. See Storage Planning.

arm64 excludes one datasource type

architecture: "arm64" excludes IBM Db2 as a datasource type — IBM does not ship a Linux/ARM64 driver for it. Every other datasource type is unaffected. See IBM Db2 — Prerequisites for details.

Apply the configuration:

kubectl apply -f lhc-instance.yaml

Step 8: Monitor Deployment​

kubectl get lakehousecat -w
kubectl get pods -n lhc-instance -w
kubectl logs -f deployment/lhc-operator -n lhc-operator
Deployment Time

Initial deployment takes about 10 minutes as container images are pulled and all services start and interconnect. The exact duration depends mainly on your network bandwidth to the image registries.

Step 9: Retrieve Admin Credentials​

kubectl get secret lhc-admin-secret -n lhc-instance \
  -o jsonpath='{.data.LHC_ADMIN_EMAIL}' | base64 -d && echo

kubectl get secret lhc-admin-secret -n lhc-instance \
  -o jsonpath='{.data.LHC_ADMIN_PASSWORD}' | base64 -d && echo

Step 10: Access Lakehousecat​

Set up port-forwarding and keep the terminal open:

kubectl port-forward svc/lhc -n lhc-instance 42021:42021

Open http://localhost:42021 in your browser and log in with the credentials from the previous step.

Troubleshooting​

Pods Pending — Insufficient Resources​

kubectl describe nodes
kubectl describe pod -n lhc-instance <pod-name>

Increase Minikube resources and restart:

minikube stop
minikube start --cpus=10 --memory=32768 --disk-size=50g --driver=docker

Image Pull Errors (ImagePullBackOff)​

kubectl logs -f deployment/lhc-operator -n lhc-operator
kubectl get secret lhc-handshake-secret -n lhc-operator -o yaml

Ensure your handshake key is valid and the subscription is active.

Slow Performance​

  • Use SSD storage for the Minikube disk
  • Disable optional services (monitoring) in the CR

Stopping and Restarting​

# Stop the lakehousecat profile (preserves data)
minikube stop --profile=lakehousecat

# Start again
minikube start --profile=lakehousecat
kubectl get lakehousecat

To remove the instance completely:

kubectl delete lakehousecat local-eval
kubectl delete namespace lhc-instance
minikube delete --profile=lakehousecat

Next Steps​