Local Kubernetes (Kind + Helm)

Run LangWatch locally on Kind for development and testing

Run the full LangWatch stack locally on a Kind cluster. This is useful for testing the Helm chart, evaluating LangWatch in a Kubernetes environment, or developing against a production-like setup.

Looking for production deployment? If you want to deploy LangWatch to a real cluster with prebuilt images (no local build required), see Kubernetes (Helm) instead. This page covers the local Kind workflow which builds images from source.

Developing LangWatch itself? make quickstart in the repo root starts only the services you pick and is faster for day-to-day development. This Kind workflow is for testing the Helm chart packaging and Kubernetes-specific behavior.

Prerequisites

• Docker (running, with at least 16 GB RAM and 20 GB free disk allocated)
• Kind v0.20+
• kubectl
• Helm 3.12+
• make (included on macOS and most Linux distributions)

Note: The first image build (especially the app image) is memory-intensive and can take 15-30 minutes. Subsequent builds reuse Docker cache and are much faster.

Quick Start

git clone https://github.com/langwatch/langwatch.git
cd langwatch/charts/langwatch
make example-up

This runs four steps:

1. Create a Kind cluster named lw-local (if it doesn’t exist)
2. Build all Docker images locally (if not already built, first build takes 15-30 min)
3. Load images into the Kind cluster
4. Install the Helm chart with values-local.yaml into the lw-local namespace

Access LangWatch at http://localhost:30560.

Manual Setup

If you prefer to run each step manually:

1. Create a Kind Cluster

kind create cluster --name lw-local \
  --config charts/lib/kind-config.yaml \
  --wait 60s

The Kind config maps port 30560 on your host to a NodePort inside the cluster.

2. Build and Load Images

cd charts/langwatch

# Build all images
make images

# Load into Kind
make images-local

This builds four images:

• langwatch/langwatch:local, App
• langwatch/langwatch_nlp:local, NLP service
• langwatch/langevals:local, Evaluators
• langwatch/clickhouse-serverless:next, ClickHouse

3. Install the Helm Chart

# Update chart dependencies
make deps

# Install with local values
helm upgrade --install lw . \
  --namespace lw-local --create-namespace \
  -f examples/values-local.yaml \
  --wait --timeout 10m

4. Verify

# Check pod status
make example-status

# Or directly:
kubectl -n lw-local get pods

All pods should reach Running status within a few minutes.

Profiles

The Makefile supports multiple profiles via the PROFILE variable:

make example-up PROFILE=local           # Default: all-in-one local dev
make example-up PROFILE=hosted-dev      # Simulates cloud dev environment
make example-up PROFILE=hosted-prod     # Simulates production (requires external DBs)
make example-up PROFILE=scalable-prod   # Simulates HA production
make example-up PROFILE=test            # CI integration testing

Each profile uses the corresponding examples/values-{profile}.yaml file.

What’s Included

The values-local.yaml profile deploys:

Component	Replicas	Notes
LangWatch App	1	NodePort on 30560
LangWatch Workers	1	Separate pod
LangWatch NLP	1
LangEvals	1
PostgreSQL	1	Chart-managed
ClickHouse	1	Chart-managed, standalone
Redis	1	Chart-managed
AI Gateway	2 to 10	Autoscaled, image pulled from Docker Hub
Langy assistant	1	Image pulled from Docker Hub

• autogen.enabled: true, secrets are auto-generated
• pullPolicy: Never for the app, NLP, LangEvals and ClickHouse images, so they must be built and loaded first
• Prometheus and CronJobs are disabled to save resources

Teardown

# Remove the Helm release
make example-down

# Delete the Kind cluster entirely
make clean

Troubleshooting

Pods stuck in ImagePullBackOff: Images haven’t been loaded into Kind. Run make images-local.

Port 30560 not accessible: Ensure the Kind cluster was created with the port mapping config (charts/lib/kind-config.yaml). Recreate the cluster if needed: make clean && make example-up.

Pods stuck in Pending: Check if your Docker daemon has enough resources. Kind needs at least 4 CPU and 8 GB RAM allocated to Docker (16 GB if building images locally).

Slow startup: First-time image builds take several minutes. Subsequent make example-up runs reuse cached images and are much faster.

Next Steps

• Production Kubernetes deployment: Deploy to a real cluster
• Sizing & Scaling: Resource recommendations