Operations

Runbooks, health checks, and local verification.

This page mirrors the practical runbook for working on Lighthouse locally and validating the current feature set.

Core Commands

npm run docker:sample
npm run docker:sample:down
npm run verify
npm run e2e

Health Checks

curl http://localhost:3000/api/health
curl http://localhost:3000/api/dashboard-metrics
curl http://localhost:9090/-/ready
curl http://localhost:9308/metrics

Replay Verification

Use the live integration test with the sample stack already running.

$env:KAFKA_INTEGRATION="1"
$env:KAFKA_BROKERS="localhost:19092,localhost:19093,localhost:19094"
npm.cmd run test:kafka:integration

Replay Jobs

npm run replay:jobs -- list
npm run replay:jobs -- show --job-id sample-job

Replay API Smoke Test

curl -X POST http://localhost:3000/api/jobs \
  -H "content-type: application/json" \
  -d '{"source":"orders","destination":"orders-replay","partition":"0","start":"0","end":"5","job-id":"sample-job-api"}'
curl http://localhost:3000/api/jobs/sample-job-api/preview
curl -X POST http://localhost:3000/api/jobs/sample-job-api/start
curl http://localhost:3000/api/jobs/sample-job-api

Troubleshooting

Prometheus unavailable

Check that Prometheus is up and reachable from the app process.

docker ps
curl http://localhost:9090/-/ready

Dashboard metrics stay at zero

Confirm the demo producer and Kafka exporter are running.

docker compose -f docker-compose.yml -f docker-compose.local-kafka.yml ps
curl http://localhost:9308/metrics

Replay CLI range validation fails

This usually means the requested offsets are outside the retained source range, or the destination topic is missing the selected partition.

Replay job start fails

Check the job status, Kafka connectivity, and whether the local SQLite file path is writable.

CI

The main CI workflow currently runs:

production dependency audit
ESLint
Jest tests
Next.js production build
Playwright end-to-end checks
Docker config and image builds