Skip to main content
Version: 0.0.42

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

helm install lhc-operator lakehousecat/lakehousecat-operator \
  --namespace lhc-operator \
  --create-namespace \
  --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:
    persistence:
      size: "10Gi"

  clickhouse:
    persistence:
      size: "20Gi"

  seaweedfs:
    persistence:
      size: "10Gi"

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 may take 30–60 minutes as container images are pulled and all services start and interconnect.

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​