Getting Started

Pick a Kafka run mode and get to a working replay quickly.

Lighthouse supports three practical run modes: the local sample cluster, an existing Kafka-compatible endpoint, and Confluent Cloud.

Prerequisites

Node.js 24 and npm for local development
Docker Desktop or Docker Engine for the sample stack
Prometheus access through the included sample stack or your own deployment

Option 1: Local Sample Stack

This is the default path for demos and development. It starts the app, Prometheus, a three-broker Kafka cluster, a Kafka metrics exporter, a topic initializer, and a demo producer.

npm run docker:sample

Local endpoints:

Lighthouse UI: http://localhost:3000
Prometheus: http://localhost:9090
Kafka metrics exporter: http://localhost:9308/metrics
Kafka brokers: localhost:19092,localhost:19093,localhost:19094

Replay against the sample cluster:

npm run replay:cli -- --source orders --destination orders-replay --partition 0 --start 10 --end 25 --brokers localhost:19092,localhost:19093,localhost:19094

Option 2: Existing Kafka Endpoint

Use this when you already have a reachable Kafka-compatible cluster and do not need the sample brokers.

KAFKA_BROKERS=broker1:9092,broker2:9092
KAFKA_SSL=false
KAFKA_SASL_USERNAME=
KAFKA_SASL_PASSWORD=

npm run docker:external

If Kafka is running directly on your host and the exporter is inside Docker, use host.docker.internal instead of localhost.

Option 3: Confluent Cloud

Lighthouse uses the same connection model for Confluent Cloud. Set the brokers plus SASL credentials and keep TLS enabled.

KAFKA_BROKERS=pkc-example.us-east-1.aws.confluent.cloud:9092
KAFKA_SSL=true
KAFKA_SASL_MECHANISM=plain
KAFKA_SASL_USERNAME=<api-key>
KAFKA_SASL_PASSWORD=<api-secret>

npm run docker:external

Local App Development

For frontend and API work, keep the sample stack running and use the Next.js dev server.

npm ci
npm run docker:sample:detached
$env:PROMETHEUS_API="http://localhost:9090"
$env:PROMETHEUS_ALLOWED_HOSTS="localhost:9090"
npm.cmd run dev