Orbtrace
ENTR
Talk to sales
Self-host

Quickstart

From "nothing installed" to "I see my first trace on the screen" — copy-paste, in order, on any machine with Docker. Honest about every step, including standing up a Collector.

The fastest path from nothing installed to your first trace on screen — about ten minutes on a laptop or a single VPS with Docker.

What you'll have at the end

A working Orbtrace running on your laptop or a VPS, with you logged in, a small OpenTelemetry Collector feeding it a stream of test traces, and you looking at your first trace waterfall.

This takes about ten minutes, not five — because Orbtrace is honest about one thing many tutorials skip: Orbtrace does not ingest telemetry itself. It ships the product (server + UI + storage); you run a standard OpenTelemetry Collector next to it that forwards data into Orbtrace's database. The quickstart sets up both. (Why this split? See Integration patterns.)

Before you start

You need:

  • A machine with at least 8 GB of free RAM. The default stack runs Apache Doris with three storage nodes, which is memory-hungry; 4 GB is only enough for a stripped-down single-node variant (see the callout in Installation). 16 GB is comfortable.
  • Docker Engine 24+ and Docker Compose v2. Check with docker --version and docker compose version.
  • Port 8080 free on that machine (Orbtrace's UI), plus 4317 and 4318 free (the Collector's OTLP ports).
  • Ten minutes of attention.

All three ports are defaults, not requirements. If 8080 is already in use on your machine, you'll change it in the settings file in step 2; the Collector ports move with the -p flags in step 5.

You do not need:

  • A cloud account or a domain name (we'll use localhost).
  • An LLM API key (RCA and the AI features are off until you configure a provider — the quickstart doesn't need them).
  • A license. Orbtrace runs in the free COMMUNITY edition out of the box (3 services / 3-day retention) — plenty for a quickstart. See Licensing for the paid editions.

The steps

  1. 1

    Get your access and the deploy bundle

    You need two things:

    • The deploy bundle — holds the docker-compose.yml, the Collector config, and an example settings file. It's free and needs no login: the button below downloads the latest version directly, and the download page offers the same file with its checksum.
    • A pull token from Nivorbit — the Orbtrace image itself is private. No token yet? Email sales@nivorbit.com.

    Download the bundle and unpack it:

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

    Log in to the registry. Edit this line before you run it — swap <token> and <username> for the credentials Nivorbit sent you:

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

    That's all the access you need — the image pulls automatically in step 3.

    Air-gapped, no registry access at all?

    Nivorbit hands you a bundle with the images baked in. Load them with bash images/LOAD.sh and skip the login. See Air-gapped install.

    The short way from here

    Don't want to do steps 2 and 3 by hand? You're already in the right directory — run:

    ./install.sh --port 8080

    8080 is where the UI will live — pick another port if it's taken. The script creates the settings file with generated secrets, prints an admin login, starts the stack, and — on a desktop machine — opens the UI in your browser once it's ready. Then jump to step 4 and sign in. Prefer to see each move? Keep going with step 2.

  2. 2

    Create your settings file

    Go into the bundle's compose/ directory, copy the example settings file, and give it a fresh Postgres password (the one value that must never stay at its placeholder — JWT signing keys are app-managed, nothing to set):

    cd compose
cp .env.example .env
sed -i.bak "s|^PGPASSWORD=.*|PGPASSWORD=$(openssl rand -base64 24 | tr -d '/+=')|" .env && rm .env.bak

    Open .env in any editor:

    nano .env    # or: vim .env / code .env

    and set a local admin login — the email is what you'll type on the login screen:

    ORBTRACE_BOOTSTRAP_ADMIN_USERNAME=you@example.com
ORBTRACE_BOOTSTRAP_ADMIN_PASSWORD=pick-a-strong-password

    Is port 8080 already in use on your machine? This is the file to fix that, too: set ORBTRACE_HTTP_PORT to a free port — the UI's public URLs follow it automatically. Using the installer instead? Pass the port on the command line: ./install.sh --port 9090.

    Fine for a quickstart — change before production

    The username/password form you just enabled exists so you can evaluate without setting up SSO. Before anyone else can reach this deployment:

    • Move sign-in to SSO (Google / Microsoft / GitHub / any OIDC) and leave ORBTRACE_BOOTSTRAP_ADMIN_PASSWORD blank — see Authentication.
    • Change PGPASSWORD and DORIS_PASSWORD from their defaults.

    Every setting in this file is explained in Configuration.

  3. 3

    Start Orbtrace

    From the compose/ directory (where you just created .env):

    docker compose up -d

    This pulls and starts the product and its storage (note: no Collector yet — that's step 5):

    On screen
    • orbtraceThe Spring Boot backend and the web UI.
    • doris-fe + doris-be ×3Apache Doris — the database that stores your logs, traces, and metrics.
    • postgresStores Orbtrace's own settings: users, SLOs, alert rules, dashboards.
    • valkeyA Redis-compatible cache for sessions and short-term state.

    First boot takes two to three minutes while Doris registers its storage nodes and Orbtrace creates the database schema. The command returns immediately; watch progress with:

    docker compose ps

    You're ready when orbtrace shows healthy — it deliberately holds that status back until the schema is fully in place, so healthy means queryable.

  4. 4

    Log in

    Open http://localhost:8080 in your browser. If Orbtrace runs on another machine, use its IP instead of localhost; if you picked another port in step 2, use it instead of 8080.

    You'll see the login screen. Your login depends on how you did step 2:

    How you did step 2Sign in with
    Ran ./install.shThe email and password it printed under "Local admin login"
    Edited .env yourselfThe ORBTRACE_BOOTSTRAP_ADMIN_USERNAME and ORBTRACE_BOOTSTRAP_ADMIN_PASSWORD you set
    Set neitheradmin@orbtrace.local and the password Orbtrace generated at first boot

    For that last row, the generated password is written to the server log exactly once — read it with:

    docker compose logs orbtrace | grep -A 3 "BREAK-GLASS"

    and you'll be asked to pick a new password as you sign in.

    You're in. The Overview screen is empty because nothing is sending telemetry yet — the next two steps fix that. For the fresh-install checklist, see First login.

  5. 5

    Stand up a Collector

    Orbtrace stores and shows telemetry; receiving it is the OpenTelemetry Collector's job. Start one — the stock upstream image plus the config file from the bundle:

    docker run -d --name orbtrace-otelcol \
  --network orbtrace-net \
  -p 4317:4317 -p 4318:4318 \
  -v "$PWD/otelcol-config.yaml:/etc/otelcol-contrib/config.yaml" \
  --tmpfs /var/lib/otelcol/queue:rw,mode=1777 \
  otel/opentelemetry-collector-contrib:latest

    What each flag does:

    • --network orbtrace-net — joins Orbtrace's network so the Collector can write into the database.
    • -p 4317:4317 -p 4318:4318 — publishes the two OTLP ports your apps will send telemetry to. Change the left-hand side of each pair if these are taken on your machine.
    • --tmpfs …/queue — a small in-memory scratch area for the send queue; the image runs as a non-root user and this is the simplest writable spot.

    If you changed DORIS_PASSWORD

    The reference config writes to Doris as root with no password (the default). If you set a DORIS_PASSWORD in your .env, pass it to the Collector too: add -e DORIS_PASSWORD=your-password to the command above.

    Check it came up clean:

    docker logs orbtrace-otelcol | tail

    No dial tcp … connection refused to doris-fe:8030 means it's talking to the database.

  6. 6

    Send a stream of test traces

    You don't have an instrumented app yet, so use OpenTelemetry's own load generator, telemetrygen, to fire some traces at the Collector:

    docker run --rm --network orbtrace-net \
  ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:latest \
  traces \
  --otlp-endpoint orbtrace-otelcol:4317 --otlp-insecure \
  --service quickstart-demo --traces 200 --rate 20

    This sends 200 traces from a fake service called quickstart-demo at 20 per second. It finishes in about ten seconds.

  7. 7

    Click your first trace

    Open http://localhost:8080/telemetry/traces — adjust localhost and 8080 as in step 4.

    The rows that appear are the 200 test requests from step 6. Click one: the panel on the right draws it as a waterfall — each bar is one step of the request, longer bars took longer. Hover a bar for its details.

    That's it — data in, data on screen. You have a working observability platform on your own hardware. The UI tour shows the rest.

What now?

You have the whole loop working, just with fake data. Three good next moves:

  • Send real telemetry. Follow Instrument your apps and point each app's OTEL_EXPORTER_OTLP_ENDPOINT at the Collector you just started.
  • Learn the screens. The screen guides walk the UI panel by panel.
  • Prepare for production. Read Configuration, set up real Authentication, and pick an AI provider for RCA and Replay. The quickstart defaults are tuned for local play, not real traffic.

If something didn't work

A container shows exited or unhealthy. Read its logs, then check Troubleshooting:

docker compose logs <name>

The login page won't load. Wait another minute — Doris is still registering its storage nodes, and Orbtrace won't serve until that's done.

The UI is up but shows no traces. Confirm step 6 finished without errors and that the Collector is running — it must share the orbtrace-net network with Orbtrace:

docker ps | grep otelcol

network orbtrace-net not found when starting the Collector. The network is created with the stack, so start the stack first, then retry:

docker compose up -d

How to stop it

docker stop orbtrace-otelcol && docker rm orbtrace-otelcol   # the Collector
docker compose down            # stop Orbtrace, keep data
docker compose down -v         # stop Orbtrace and delete all data
PreviousConceptsNextInstallation preparation