Skip to main content
Use this page to run OpenLIT from a clone of the repository while you work on it. One script starts every service with hot reload for the UI. To run OpenLIT without changing it, use Docker Compose instead. scripts/dev-realtime.sh starts and supervises: Logs from every service share one terminal, prefixed with the service name. Ctrl+C stops everything, and if any service exits, the rest stop too.

​
Prerequisites

  • Node.js 20 or later
  • Go 1.25 or later
  • Docker with Docker Compose v2.24 or later, for ClickHouse and NATS
  • curl, openssl, and lsof (preinstalled on macOS and most Linux distributions; on Windows, use WSL)
  • Python 3, only to send sample spans

​
Start OpenLIT

1

Clone the repository and install the UI dependencies

2

Create src/client/.env

Set at least these values:
file:./data.db is relative to src/client/prisma, and .db files are ignored by git. The script reads the UI port from NEXTAUTH_URL.
3

Run the script from the repository root

The first time, add SEED=1 to create the default user, organisation, project, and database configuration:
After that, start it without SEED:
The script applies Prisma migrations, starts ClickHouse if needed, then starts NATS, the UI, the receiver, and the engine. It prints the address of each service when they are up.
4

Sign in

Open http://localhost:3000 and sign in with user@openlit.io and openlituser.

​
Send sample spans

Threshold alerts only see spans sent with an API key.
  1. In OpenLIT, open Settings → API Keys and create a key.
  2. Send spans to the local receiver:
    Useful flags include --service, --model, --latency-ms, --cost, and --http-status. Run the script with --help for the full list. If the dev script reported that port 4318 was busy and used 14318, pass --endpoint http://127.0.0.1:14318.
  3. Open Alerts, create an alert from the Error rate spike template, and send the spans again. The alert fires within a few seconds.
To point your own app at the local stack, use openlit.init(otlp_endpoint="http://127.0.0.1:4318", otlp_headers={"Authorization": "Bearer <your key>"}).

​
Options

Set any of these before the script, for example UI_PORT=3001 scripts/dev-realtime.sh. NATS uses assets/nats.conf, so local development has the same permissions as production. Its passwords, the engine secret, and the cron secret are random for each run. To skip Docker for NATS, install the server once:

​
Work on the UI only

If you are not working on alerts or the realtime pipeline, you can run the UI on its own against ClickHouse:
Threshold alerts stay idle without the receiver, engine, and NATS. The rest of the UI works as usual.

​
Run the checks

Before you open a pull request, run the checks for what you changed:
See CONTRIBUTING.md for the pull request process.

​
Troubleshooting

  • UI port 3000 is already in use: stop the other process or set UI_PORT, and update NEXTAUTH_URL to match.
  • prisma migrate deploy failed: the SQLite file was created by a different branch. Point SQLITE_DATABASE_URL at a new file, or rerun with SKIP_MIGRATE=1.
  • Alerts never fire: spans must be sent with an API key from the same project, and the alert must be in the environment you send to (default production).
  • Docker Compose ... is too old: src/dev-docker-compose.yml needs Compose v2.24 or later. Upgrade Docker, or run your own ClickHouse and set INIT_DB_HOST and INIT_DB_PORT.
  • timed out waiting for NATS JetStream: the script prints the NATS container logs above this message. Rerun it, or install nats-server locally (see Options) so NATS runs without Docker.