Orbtrace
ENTR
Talk to sales
Self-host

Installation preparation

What to decide and prepare before installing Orbtrace — the three deployment paths, hardware and kernel prerequisites, the real port list, and the post-install checklist.

Pick the deployment path that matches your environment. Each one ends with the same outcome: Orbtrace running on your hardware, reachable on port 8080, ready for the First login.

One thing to know before you start

Orbtrace ships the product — server, UI, and storage. It does not ingest telemetry itself and does not bundle an OpenTelemetry Collector. After install you stand up a Collector (a single docker run, or a block in your existing pipeline) that forwards data into Orbtrace's database. See Integration patterns. These pages get Orbtrace running; the Collector is the step right after.

Decide which path you want

Not sure how big to build it?

Before you pick a path, run the Capacity planning — enter your daily volume, retention, and service count and it returns the Helm sizing, the Doris FE/BE counts, the vCPU / memory / disk to provision, and a ready-to-paste my-values.yaml overlay. It's grounded in Apache Doris's published deployment guidance.

All paths end with the same running Orbtrace. They differ in where it runs and how far it scales:

PathBest forWhat it runsScales to
Docker ComposeThe recommended default — single-host production, and the fastest way to evaluateEverything on one machine, one command — app + Doris + Postgres + Valkey, wired togetherOne host
Kubernetes (Helm)Teams already on Kubernetes that need HA and large volumesThe stateless app in-cluster; you provide Doris (and, recommended, Postgres)Many nodes
Bare metal (Ansible)A single Linux host you want set up and managed for youThe Compose stack, installed and run as a systemd serviceOne host
Cloud (EKS / AKS / GKE)A managed Kubernetes cluster on AWS, Azure, or GCPThe Helm path, with the provider's managed Postgres and storageMany nodes

Is Docker Compose only for testing? No. It brings up the whole stack — including Doris — with one command, which makes it both the quickest way to try Orbtrace and a perfectly good single-host production deployment for small-to-mid volumes. Reach for Helm only when you need to scale horizontally across a Kubernetes cluster; reach for Ansible when you want that same single-host stack installed and managed for you.

Prerequisites — applies to all paths

  • Linux (Ubuntu 22.04+ / Debian 12+ / RHEL or Rocky 9+ tested). macOS works for Docker Compose only, for development.

  • CPU: 4 cores minimum, 8 recommended.

  • RAM: 8 GB minimum for the default stack, 16 GB comfortable. 32 GB+ per Doris node for serious workloads.

    About the '4 GB tiny VPS' claim

    The default stack runs Apache Doris with three storage nodes, which alone wants several GB. 4 GB is not enough for it. A 4 GB box needs a reduced single-Doris-node footprint, which the shipped Compose file does not provide out of the box — treat 8 GB as the real floor unless you've deliberately trimmed Doris.

  • Disk: SSD strongly recommended for the Doris data directory. Budget about 30 GB per million spans per day before compression (~3–5 GB after).

  • Kernel (Doris needs this): vm.max_map_count ≥ 2000000 and swap disabled. The Compose stack sets these for you via a privileged init container; the Ansible playbook sets them on the host. On Kubernetes it is a node setting — see Setting up Doris.

  • Ports:

    On screen
    • 8080Orbtrace backend + UI. Published by default. This is the address you and your team open.
    • 4317 / 4318OTLP gRPC / HTTP — opened by your Collector, not by Orbtrace. Your apps send here. (Covered in Integration patterns.)
    • 8030 / 9030Doris FE — Stream Load (HTTP) and MySQL wire. Bound to loopback only; never expose on a LAN.
    • internalPostgreSQL (settings) and Valkey (cache) are not published at all — reachable only inside the stack's network.
    • 80 / 443Only if you put a reverse proxy in front for HTTPS — the optional Caddy edge profile, your own Nginx, or the Helm Ingress. Not opened by default.

For volume-based sizing (Doris FE/BE counts, CPU/memory/disk), see Capacity planning.

Choose your path

Post-install checklist

After any path, do these before you let anyone else in:

  1. Confirm PGPASSWORD isn't the placeholder (Compose won't stop you booting with it). DORIS_PASSWORD deliberately stays empty — the bundled Doris root account is passwordless, so don't "fix" it.
  2. Set up authentication — wire at least one SSO provider; see Authentication.
  3. Apply your license if you have one — Admin → License, or ORBTRACE_LICENSE_KEY. Without it you're on the free COMMUNITY edition (3 services / 3-day retention). See Licensing.
  4. Stand up a Collector and prove data flows — Integration patterns, then point a real service at it via Instrument your apps.
  5. Terminate TLS — Caddy edge profile, your own reverse proxy, or the Helm Ingress tls.
  6. Pick an AI provider if you want RCA / Replay — Admin → AI (see Admin screens).
  7. Set up backups — on Kubernetes, enable the chart's backup.* CronJobs (Postgres pg_dump + Doris snapshot). On Compose/Ansible, schedule a pg_dump of Postgres and a Doris BACKUP SNAPSHOT.

If any step trips, jump to Troubleshooting.

PreviousQuickstartNextCapacity planning