Single-host (Docker Compose)

Everything on one machine, one command — this is the recommended way to run Orbtrace on a single host, and the fastest way to evaluate it. docker compose up -d brings up the whole stack wired together: the Orbtrace app, Apache Doris (FE + BE), Postgres + pgvector, and Valkey — there are no external datastores to set up, unlike the Kubernetes path. It's a solid production deployment for small-to-mid volumes on one server; move to Deploying on Kubernetes only when you need to scale out across multiple machines.

First check the Installation preparation page for the hardware and kernel prerequisites (8 GB RAM floor, vm.max_map_count, ports).

There are no external datastores to provide — unlike the Kubernetes path, Doris/Postgres/Valkey all come up in the same command. The only piece you run separately is the Collector that sends data in (Integration patterns).

1. 1

   Install Docker

   Use the official Docker Engine installer. Verify with docker --version and docker compose version. Docker Compose v2 is required.

2. 2

   Get your access and the bundle

   Orbtrace is a private image. The deploy bundle (its compose/ directory has the Compose files, otelcol-config.yaml, .env.example) is a free public download; Nivorbit issues the per-customer pull token for the image. Download the bundle and unpack it (safe to paste as-is):

   tar xzf orbtrace-2.1.0.tar.gz && cd orbtrace-2.1.0

   Then log in to the registry — edit this line first, replacing <token> and <username> with your Nivorbit credentials:

   echo "<token>" | docker login ghcr.io -u <username> --password-stdin

   The image ghcr.io/nivorbit/images/orbtrace then pulls on docker compose up. Air-gapped? Nivorbit gives you an air-gapped bundle with the images baked in instead — load them with bash images/LOAD.sh before step 4, no login needed (see Air-gapped install).

3. 3

   Edit settings

   The deploy files are in the bundle's compose/ directory:

   cd compose
   cp .env.example .env
   $EDITOR .env

   At minimum set:

   • PGPASSWORD and DORIS_PASSWORD — change them from the defaults.
   • ORBTRACE_BOOTSTRAP_ADMIN_USERNAME — the email that becomes your admin (see Authentication).
   • ORBTRACE_BOOTSTRAP_ADMIN_PASSWORD — set this for an evaluation login. Without SSO configured there is no login form, so an eval box needs this: it gives you a username/password sign-in as that admin. (Production uses SSO instead.)
   • ORBTRACE_LICENSE_KEY — optional; leave blank to run the free COMMUNITY edition (see Licensing).

   See Configuration for every variable.

   There is no placeholder guard on Compose

   Unlike the Ansible path, docker compose up will boot with the example secrets unchanged (e.g. the change-me… Postgres password). Nothing stops you — so make sure you actually edited them before exposing the box.

4. 4

   Start

   From the compose/ directory:

   docker compose up -d

   First boot takes two to three minutes while Doris registers its storage nodes and Orbtrace creates the schema. Watch with docker compose ps; you're ready when orbtrace is healthy.

5. 5

   Open the UI

   Browse to http://localhost:8080 (or http://<server-ip>:8080). You should see the login page. Continue to First login.

   For HTTPS in production, front Orbtrace with a reverse proxy: enable the bundled Caddy with docker compose --profile edge up -d (publishes 80/443), or use your own Nginx/Traefik.

When Orbtrace is up, finish with the post-install checklist — secrets, a Collector to send data (Integration patterns), TLS, and backups.