Start Berserk Locally
Run the full Berserk stack on your machine using Docker Compose
For production use, we recommend deploying Berserk to Kubernetes with Helm. A Kubernetes deployment gives a better UI experience with richer context on logs, traces, and metrics — such as Kubernetes pod names, namespaces, and node information automatically attached to your telemetry.
This guide runs the full Berserk stack locally using Docker Compose — useful for trying out Berserk, local development, or quick demos.
In this case Berserk emits its own logs, traces and metrics into Berserk itself, so that will be the data you can explore.
Prerequisites
- Docker with Docker Compose v2.23.1+
Host DNS gotcha
The stack relies on Docker's embedded DNS (127.0.0.11) to resolve in-network
hostnames like meta, gateway, and query. If your host has a custom
resolver in /etc/resolv.conf that intercepts unqualified lookups (Netbird,
Tailscale's MagicDNS in some configurations, corporate VPN clients), the
query service can fail to reach meta with dns error: Temporary failure in name resolution. Disable the interceptor for the duration of the local run,
or override DNS on the compose services with dns: [127.0.0.11].
Berserk is pre-release (beta) software, provided AS IS with no warranty. By downloading and using it you agree to our Terms of Use.
Installation
Start the stack
Download the docker-compose.yaml
# `main` tracks the images listed inside the file. Pin to a release tag once
# one ships this compose.
curl -o docker-compose.yaml \
https://raw.githubusercontent.com/berserkdb/helm-charts/refs/heads/main/docker-compose.yaml
docker compose up -dPort 9500 already in use
Compose publishes the gateway on 127.0.0.1:9500 by default. Another
stack may already own that port. Remap with
HOST_GATEWAY_PORT=19500 docker compose up -d — adding a second
mapping in an override file still binds 9500.
This starts all Berserk services: PostgreSQL, MinIO (S3-compatible storage), meta, query, ingest, janitor, nursery, the web UI (data plane + admin plane), and the gateway — the auth edge that owns OIDC, sessions, and serves as the single public entry point.
Create the first admin
Gateway prints a one-time admin-setup URL to its container stderr on first boot. Grab it:
docker compose logs gateway | grep -A2 "Initial admin setup"You'll see something like:
Initial admin setup:
Open: http://localhost:9500/setup?token=…
This link expires in 1 hour and can be used once.Open the URL in a browser, fill in the form — email, given name, family name, password (12+ characters) — and submit. You'll be redirected to /login; sign in with the credentials you just set.
The setup token is a single-use admin credential. Anyone who can run docker compose logs gateway can read it until it's consumed.
Query the data via the UI
Once you're signed in, browse to http://localhost:9500 for the data-plane UI (query editor, dashboards, library) and http://localhost:9500/admin/ for the workspace admin (datasets, ingest tokens, members and invites, and the operator-config view at /admin/config). If you remapped the gateway with HOST_GATEWAY_PORT, use that host port instead.
The Berserk services emit their own telemetry into the default table, so you'll see data flowing immediately.
Query your data via the CLI
Install the Berserk CLI and authenticate against the gateway:
curl -fsSL https://go.bzrk.dev | bash
bzrk profile add local --endpoint http://localhost:9500
bzrk profile use local
bzrk login
bzrk search "default | take 10" --since "1h ago"The installer tracks latest stable and can lag this compose tag. Prefer a
CLI whose version equals the image: pins in docker-compose.yaml
(currently v1.1.2-rc.10). The first docker compose up pulls large
layers (query is ~800MB) and can sit silent for several minutes.
bzrk login prints a URL — follow the on-screen instructions to sign in. See Berserk CLI → Authenticating for the full reference.
Sending your own data
The local stack exposes OTLP endpoints for ingesting telemetry from your applications:
- gRPC:
localhost:14317 - HTTP:
localhost:14318
Configure your OpenTelemetry SDK or Collector to export to these endpoints. See Ingestion for details.
Cleanup
To stop all services and remove all data:
docker compose down -v