Local development

Running the code natively gives faster rebuilds and a debugger. The datastores still run in Docker from the Compose file.

Start the datastores

cd obleth-gateway/deploy/docker
cp .env.example .env
docker compose up -d postgres redis clickhouse

With the example .env they listen on 127.0.0.1: Postgres and ClickHouse as obleth / obleth, Redis with the password dev-redis-password.

Run the benchmark backend

A simulated OpenAI-compatible model server that streams tokens with a configurable delay, no GPU needed:

cd obleth-gateway/benchmark-backend
cargo run --release          # listens on 0.0.0.0:8081

Run the gateway

The obleth/ workspace builds two binaries, the gateway (obleth) and the Slurm provisioner (obleth-provisioner), so name the one to run:

cd obleth-gateway/obleth
export OBLETH_DATABASE_URL=postgres://obleth:obleth@localhost:5432/obleth
export OBLETH_REDIS_URL=redis://:dev-redis-password@localhost:6379
export OBLETH_CLICKHOUSE_URL=http://localhost:8123
export OBLETH_CLICKHOUSE_USER=obleth
export OBLETH_CLICKHOUSE_PASSWORD=obleth
export OBLETH_UPSTREAM_BASE_URL=http://localhost:8081
export OBLETH_ADMIN_TOKEN=dev-admin-token
export RUST_LOG=info,obleth=debug
cargo run --release --bin obleth

The gateway applies its Postgres migrations and ClickHouse schema at start; there is no separate migration step. OBLETH_CLICKHOUSE_USER defaults to default, which the ClickHouse image limits to connections from inside its container, so set it to obleth. If ClickHouse is unreachable the gateway still starts and writes usage to its spill file (OBLETH_WAL_PATH, default ./obleth-telemetry.wal) until it returns.

For a release binary, cargo build --release --bin obleth puts it at target/release/obleth.

Run the dashboard

cd obleth-gateway/control-plane
cp .env.example .env.local
npm install
npm run dev                  # http://localhost:3000

The dashboard reads .env.local, not deploy/docker/.env. The example points it at a gateway on localhost:9180 and the same Postgres, and sets the sign-in values it refuses to start without: sign in as admin@example.com / obleth-admin. Set OBLETH_PROXY_BASE_URL (default http://localhost:8080) if your gateway's data plane listens elsewhere; the Playground uses it.

Try it

Follow First tenant and key against http://localhost:9180, register a model with "api_base": "http://localhost:8081", and send requests to http://localhost:8080.

Run the tests

cd obleth-gateway/obleth
cargo clippy --workspace --all-targets
cargo test --workspace

cd ../control-plane
npm test
npm run build

Unit tests need no services. Integration tests run only when their URLs are set, and are skipped otherwise:

export OBLETH_TEST_DATABASE_URL=postgres://obleth:obleth@localhost:5432/obleth_test
export OBLETH_TEST_REDIS_URL=redis://:dev-redis-password@localhost:6379

The test database name must contain test; the tests refuse to run against any other. Point them at data you can lose. CI also runs bash scripts/check-versions.sh and a release build of benchmark-backend/; see CONTRIBUTING.md in the repo.

Settings worth changing while developing

Every setting is in Environment variables.