Install with Helm

With your datastores in place — Postgres/Valkey and Doris — install the stateless app with the OCI Helm chart.

1. 1

   Prerequisites

   A Kubernetes cluster and Helm 3.8+ (for OCI charts). Verify a default StorageClass with SSD-backed volumes exists — without one, the bundled Postgres/Valkey PVCs hang Pending forever:

   kubectl get storageclass    # one must be marked (default)

   Stand up Doris first. The chart never deploys Doris, and the Orbtrace pod stays un-Ready until it can reach one. Follow Setting up Doris before installing, and note its FQDN for doris.host.

2. 2

   Authenticate to the registry

   The chart and the image are private GHCR packages. Log in with the per-customer token Nivorbit gives you, then create an imagePullSecret the chart will use. <token> and <username> appear more than once below — replace every occurrence before running:

   echo "<token>" | helm registry login ghcr.io -u <username> --password-stdin
   kubectl create namespace orbtrace
   kubectl -n orbtrace create secret docker-registry ghcr \
     --docker-server=ghcr.io --docker-username=<username> --docker-password=<token>

   helm registry login authenticates the Helm CLI to pull the chart; the Secret + global.imagePullSecrets (next step) let the runtime pods pull the image. Air-gapped? Mirror the GHCR images and the OCI chart into your internal registry and point global.imageRegistry at it — see Air-gapped operation.

3. 3

   Get the chart and write your overrides

   Pull and unpack the chart so you have the sizing presets and the OpenShift overlay locally (helm show values only prints the default values.yaml — it can't hand you the values-small/medium/large.yaml or values-openshift.yaml files, which is why you unpack):

   helm pull oci://ghcr.io/nivorbit/charts/orbtrace --version 2.1.0 --untar

   You don't copy the whole values.yaml. When you install ./orbtrace, Helm already applies the chart's own values.yaml as the base — you just write a small my-values.yaml with the handful of keys you change, layered on top (step 4). Create it next to the unpacked orbtrace/ directory with at least:

   global:
     imagePullSecrets: [{ name: ghcr }] # the secret from step 2
   orbtrace:
     # JWT signing needs no value here — the app manages its RSA keys itself.
     ingress:
       hosts: [demo.orbtrace.com] # your external hostname(s); set orbtrace.ingress.tls for HTTPS
       # The app's OAuth2 URLs auto-derive from this host — no separate
       # frontendUrl/backendUrl needed on the ingress path.
       # On OPENSHIFT skip this block entirely: the overlay replaces the
       # Ingress with a Route — set openshift.route.host instead (a custom
       # host auto-derives the OAuth2 URLs too; see the OpenShift page).
     # Sign-in works out of the box: a break-glass local admin is provisioned
     # with a generated password (read it from the <release>-bootstrap-admin
     # Secret; a new password is required on first login). Wire SSO via
     # orbtrace.oidc.* for production. See "Signing in" below.
   # Doris — with the reference operator DorisCluster the defaults already
   # match, so most installs need NO doris.* keys here. Uncomment only what
   # differs on your side (see Setting up Doris):
   # doris:
   #   host: <your-doris-fe-host> # a VM / managed FE, or non-default operator names
   #   password: <doris-root-password> # only if your Doris has a root password — a fresh one has none
   #   # Single-BE Doris (evaluation)? Also uncomment BOTH lines below, or the
   #   # app aborts at boot ("replication num … available backend num is 1").
   #   # Never in production — see Replication factor on the Setting up Doris page.
   #   allowSingleReplica: true
   #   profile: { replicationNum: 1 }
   postgres:
     password: <postgres-password> # required — chart refuses to install if empty; bundled Postgres, or set postgres.* for an external one

   Other keys you may add: orbtrace.licenseKey (blank = free COMMUNITY — Licensing), orbtrace.oidc.* (your SSO providers), orbtrace.ai.* (AI provider for RCA/Replay), doris.profile.activeProfile (small / medium / large). Every available key and its default is in the unpacked orbtrace/values.yaml for reference — copy only the ones you override into my-values.yaml, so an upgrade never freezes you on an old default.

4. 4

   Install

   Run this in the directory where you unpacked the chart (step 3) — ./orbtrace and the -f paths are relative to it. You layer (in order) your sizing preset, then your overrides; later -f files win, so your my-values.yaml overrides the preset:

   # Sizing preset: values-small | values-medium | values-large
   helm install orbtrace ./orbtrace -n orbtrace \
     -f orbtrace/values-small.yaml \
     -f my-values.yaml

   On OpenShift this command is different (the values-openshift.yaml overlay is layered as the last -f) — use the one on the OpenShift page instead.

5. 5

   Wait for pods

   kubectl -n orbtrace get pods -w

   All pods should reach Running and pass readiness within ~3 minutes. The Orbtrace pod stays un-Ready until it can reach Doris (it applies the schema before binding) — so make sure your external Doris is up first. Confirm success in the app log:

   kubectl -n orbtrace logs -f deploy/orbtrace-app -c orbtrace
   # ready when you see: [doris-migration] complete

   A pod stuck un-Ready is almost always an unreachable Doris (or Postgres), or a replication factor your BE count can't meet (the app creates tables at doris.profile.replicationNum, default 2, which needs ≥2 live BE) — re-check the host/password and the replication factor against Setting up Doris.

6. 6

   Point DNS at the ingress

   Add a DNS record from your hostname to the Ingress (or LoadBalancer) address the chart surfaces. Continue to First login.

Next: Ports & exposure, then wire your telemetry in — a new OTel Collector, or dorisexporter on your existing pipeline (Integration patterns) — and the post-install checklist.