Start Berserk Locally

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 admin-ui. 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

curl -o docker-compose.yaml https://raw.githubusercontent.com/berserkdb/helm-charts/refs/heads/main/docker-compose.yaml
docker compose up -d

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, invites, and the operator-config view at /admin/config).

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"

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 Ingest Configuration for details.

Cleanup

To stop all services and remove all data:

docker compose down -v

Start Berserk Locally

On this page