Skip to content
Obzly

Docker Compose

Obzly runs as one app container next to its own Postgres and Valkey containers. This is the same shape the install script sets up; use Compose directly if you want to customize it or aren’t on a Debian/Ubuntu host.

You need Docker Engine 20.10+ and Docker Compose v2.0+, and a host with at least 2 CPU cores, 4 GB of RAM and 20 GB of disk; see System requirements.

Set up

Section titled “Set up”

Run everything from the repository root, not from inside deploy/docker/: the example builds the image from source, and its build context is the repository root where the Dockerfile lives.

Terminal window
git clone https://github.com/obzly/obzly.git
cd obzly
cp deploy/docker/docker-compose.yml.example docker-compose.yml
cp deploy/docker/.env.example .env

Edit .env and set a real POSTGRES_PASSWORD. One way to generate one:

Terminal window
openssl rand -hex 16

Everything else in .env is optional and documented in the file’s comments. Then start it:

Terminal window
docker compose up -d --build

Obzly comes up on http://localhost:4005. The ports it publishes:

Port Serves
4005 Web UI, REST API and OTLP/HTTP (/v1/logs, /v1/traces, /v1/metrics)
4317 OTLP/gRPC

Data lives under ./obzly-data (Parquet segments, plus the Postgres and Valkey data directories), relative to where you ran docker compose.

For the first sign-in (bootstrap token, admin password and MFA), see Quick install: Sign in. The container is named obzly, so the same docker logs obzly and docker exec -it obzly ./main ... commands apply.

Use the published image instead of building

Section titled “Use the published image instead of building”

To run a release instead of building from source, replace the build: block of the obzly service with:

image: ghcr.io/obzly/obzly:${OBZLY_IMAGE_TAG:-latest}

and set OBZLY_IMAGE_TAG in .env (for example v0.48.1). Images are published for linux/amd64 and linux/arm64.

Configure

Section titled “Configure”

Add any setting from the configuration reference to the obzly service’s environment:. Common ones:

  • ADMIN_EMAIL (set in .env): the bootstrap admin’s login instead of admin. Changing it later renames the existing account rather than creating a second one.
  • TRUSTED_PROXIES: the CIDR of your reverse proxy or load balancer, so logs, the audit log, rate limits and project IP allow-lists see real client IPs. Never use 0.0.0.0/0.
  • PUBLIC_URL: the address users reach Obzly at, so MCP clients get the right OAuth origin.

Email (SMTP) for alert notifications and invites, and the notification channels themselves, are set up in Obzly settings → Notifications & alerting, not in the environment. See Alerts & notifications.

Upgrade

Section titled “Upgrade”

When building from source:

Terminal window
git pull
docker compose up -d --build

With the published image:

Terminal window
docker compose pull && docker compose up -d

Only the obzly container is replaced; Postgres and Valkey data are untouched. Migrations run automatically on startup. Check Upgrade for versions that need action.

Next steps

Section titled “Next steps”