Reference
Configuration
Every environment variable this product reads, its default, and what it means. This
is the complete list: a name missing from it is not part of the contract, no matter
where you saw it. Source: CONTRACT.md and its addenda, and the
configuration packages of each service (internal/config), which refuse to start on a
value they cannot parse rather than fall back to a default.
Three scopes matter, and the tables below name one per row:
- build-time: baked into an image at
docker buildtime. Changing it on a running container does nothing; you must rebuild. - runtime: read from the process environment on startup (or, for a couple of backend-service values, cached with a bounded refresh). Changing it means restarting the container/pod, not rebuilding.
- runtime, server-only: runtime, and never sent to a browser. This scope only
exists on
web; the Addendum v0.2 proxy exists to keep it there.
web
| Var | Default | Scope | Meaning |
|---|---|---|---|
NEXT_PUBLIC_DEMO_MODE | true | build-time | Serve built-in demo data; the Orbit Deck needs no backend at all. next build inlines it into the browser bundle: set it with --build-arg, never at docker run/pod time. |
PORT | 3000 | runtime | Listen port for the Next.js standalone server. |
NODE_ENV | production | runtime | Standard Node.js mode flag; the shipped image always runs production. |
HOSTNAME | 0.0.0.0 | runtime | Bind address for the standalone server: 0.0.0.0, so it's reachable from outside its own container/pod network namespace. |
MALLOC_ARENA_MAX | 1 (set in the image) | runtime | glibc malloc arenas for the Next.js server. One per thread held tens of MiB after a burst of traffic, and a pod limited to one core has no contention to avoid. |
MALLOC_MMAP_THRESHOLD_ | 65536 (set in the image) | runtime | Allocations of at least this many bytes go straight to mmap, so freeing one returns it to the node. Setting it also stops glibc raising the threshold after the first large free. |
ORBIT_API_URL | http://orbit-api:8080 (compose) / templated to the in-cluster Service (Helm/kubectl) | runtime, server-only | Base URL the Next.js server uses to reach orbit-api. Never reaches the browser; see architecture.md. |
ORBIT_AUTH_TOKEN | empty | runtime, server-only | The bearer web's server attaches to every proxied /api/* call. Read from a Secret; must match orbit-api's own ORBIT_AUTH_TOKEN. |
WEB_AUTH_MODE | empty | runtime | basic turns on web's own HTTP Basic auth in front of every route; empty or disabled leaves it off; any other value fails closed. See security.md. |
WEB_AUTH_USER | empty | runtime, server-only | The single user name web's Basic auth accepts; no colon. Required when WEB_AUTH_MODE=basic. |
WEB_AUTH_VERIFIER | empty | runtime, server-only | A PBKDF2 verifier for the password (never the password itself), generated by node apps/web/scripts/hash-password.mjs. Required when WEB_AUTH_MODE=basic; see security.md. |
WEB_TRUST_PROXY | false; the plain manifests set true, and the chart derives it from ingress.enabled when empty | runtime | true says an edge proxy in front of web writes X-Forwarded-For, and only then does web pass that header to orbit-api, which records the client address from it in the audit trail and keys its per-client limits on it. true with nothing in front of web lets a browser choose the address it is recorded under. See audit.md → "How the client IP is determined". |
ORBIT_PUBLIC_URL | empty; the chart sets it on web only from publicUrl | runtime | The address people open the Deck at. When it is https://..., web takes the browser to be on https whatever X-Forwarded-Proto says: __Host- cookies with Secure, and https:// in the MCP snippet and the SSO redirect URIs, whose host still comes from the request. It is for an edge that rewrites that header, such as an ingress with no TLS behind a CDN. Empty, http://... or unreadable, the header decides. An install that was reading http signs everyone in once more when this goes on, and a browser that reaches the Deck over plain http anywhere but localhost cannot keep the cookie. It encrypts nothing: see audit.md → "Behind a cloud load balancer or a CDN". |
ORBIT_DECK_WRITE_TOKEN | empty | runtime, server-only, from Secret (key DECK_WRITE_TOKEN) | The operator token a person types in the Deck before a scale or resources write (Addendum v0.4), compared on web's hop and never forwarded. Empty refuses every workload write with 403 writes_disabled. |
ORBIT_DECK_OPERATOR | empty | runtime | A label, not a credential: the console name a workload write is logged under beside the signed-in user (console in the log line and the audit event). |
ORBIT_DECK_WRITES | empty | runtime | session: with no ORBIT_DECK_WRITE_TOKEN, a signed-in user's workloads.write (editor, admin) stands in for the operator token on the two workload writes; same-origin proof, the dry-run with its diff and the audit trail stay. orbit-api still needs ORBIT_WRITE_ENABLED and rbac.write.enabled. Empty keeps the token as the only way. |
ORBIT_CLUSTER_ID | empty | runtime, server-only | Live mode only: the cluster the Deck opens when the address names none. Empty picks the first cluster orbit-api lists. |
NEXT_PUBLIC_API_URL does not exist in this contract. It was removed in Addendum
v0.2: a build-time, browser-inlined API URL was both a misleading knob (one image per
API URL) and a documented route around the server-side proxy. If you see it in an
older fork or a stale deployment, that deployment predates the addendum.
orbit-api
| Var | Default | Scope | Meaning |
|---|---|---|---|
ORBIT_ADDR | :8080 | runtime | Listen address for the API. |
ORBIT_LOG_LEVEL | info | runtime | debug | info | warn | error. |
ORBIT_LOG_PROBES | false | runtime | Log /healthz, /readyz and /metrics requests at info; otherwise only at debug. |
ORBIT_CORS_ORIGINS | http://localhost:3000 | runtime | Comma-separated allowed origins. In the Helm chart, an empty value is derived from ingress.host + ingress.tls.enabled (https://sreorbit.example.com, never a scheme the ingress doesn't serve); set a literal only to add extra origins on top. |
ORBIT_DEMO_DATA | true | runtime | true = deterministic demo estate, no cluster access required, and on a first start with no user and no admin pair, the three demo accounts (identity.md). false = the live Kubernetes source, reading real clusters through ORBIT_KUBECONFIG or in-cluster credentials. ORBIT_AUTH_MODE=disabled is refused in this mode (below): an unauthenticated port onto a real cluster is not a local demo. |
ORBIT_NOCTURNE_URL | http://nocturne:8081 | runtime | Base URL for the internal reverse proxy to nocturne. |
ORBIT_NOCTURNE_TOKEN | falls back to NOCTURNE_AUTH_TOKEN | runtime, from Secret | The bearer the proxy attaches on its hop to nocturne. Either name works, so the two manifests cannot disagree. |
ORBIT_STREAM_TIMEOUT | 180s | runtime | How long a proxied nocturne stream may run. Keep it above NOCTURNE_TIMEOUT plus 30s. |
ORBIT_KUBECONFIG | empty | runtime | Path to a kubeconfig, read only when ORBIT_DEMO_DATA=false. Empty means in-cluster credentials, which needs the pod's ServiceAccount token projected and a role bound to it: components.orbit-api.rbac.enabled in the chart, deploy/kubectl/15-rbac-orbit-api.yaml in the plain manifests. When a path is given, every context in the file becomes one cluster and the {id} in /api/v1/clusters/{id} is that context name lowercased with every character outside [a-z0-9-] replaced by - (an EKS ARN becomes arn-aws-eks-us-east-1-...). Two contexts that sanitise to the same id is a startup failure. Mount the file as a volume; never paste one into an env var or a manifest. |
ORBIT_CLUSTER_ID | local | runtime | The {id} of the cluster orbit-api is running inside, used only when ORBIT_KUBECONFIG is empty, because an in-cluster pod has no context name to derive one from. Must match [a-z0-9-]{1,128}; anything else refuses to start. |
ORBIT_CLUSTER_NAME | ORBIT_CLUSTER_ID | runtime | Display name for that cluster. Cosmetic. |
ORBIT_STACK_URL | empty | runtime | Base URL of a Prometheus-compatible HTTP API (orbit-stack) backing GET /api/v1/query_range, the dashboards' label and series reads, and every APM route. Empty: query_range answers an empty series carrying the right unit, an ad-hoc PromQL expression (every dashboard panel is one) is refused with invalid_request, the APM and metadata routes answer 503 not_ready, and /readyz does not check it. Set: ad-hoc PromQL runs on the engine on demo data too, and /readyz also checks its /healthz, so orbit-api is NotReady until the engine answers. In the Helm chart an empty value is derived to http://<fullname>-orbit-stack.<namespace>.svc.cluster.local:8082, the same way ORBIT_NOCTURNE_URL is. |
ORBIT_STACK_TOKEN | empty | runtime, from Secret | Bearer attached to every ORBIT_STACK_URL call. Optional: the engine may need none. Setting it while ORBIT_STACK_URL is empty refuses to start, because nothing would carry it. Redacted in every log line. |
ORBIT_USAGE_SOURCE | auto | runtime | Where live CPU and memory usage comes from. auto: metrics.k8s.io while the cluster serves it, the engine when it does not. orbit-stack: the engine always, which needs ORBIT_STACK_URL. |
ORBIT_CACHE_MAX_AGE | 90s | runtime | How long the live source's informer cache may go without its watches making progress before /readyz names it stale in its cache rows. A cache that has filled keeps serving, and the pod stays ready, while it is stale; only a cache that has not filled yet, or an API server that does not answer, makes /readyz answer 503. Widen it for a slow or busy API server. |
ORBIT_WRITE_ENABLED | false | runtime | true lets the scale and resources routes change the cluster (Addendum v0.4), together with the write ClusterRole the chart renders only for components.orbit-api.rbac.write.enabled. Anything but true answers 403 writes_disabled. |
ORBIT_SECRETS_READ | false | runtime | true lets the configuration view read the Secrets a workload's template references, with the get on secrets (never list or watch) the chart grants only for components.orbit-api.rbac.secrets.enabled (Addendum v0.11). Off, a Secret reference reads not-read and its value cannot be revealed. The chart sets it from that same value, on the pod; components.orbit-api.env refuses it. |
ORBIT_KARPENTER_NAMESPACE | karpenter | runtime | Where Karpenter runs. FinOps prices each node from Karpenter's AWS estimates (on-demand and spot, by zone), read every 10 minutes from its pods' http-metrics port; the chart's NetworkPolicy opens that port alone, and only when the namespace exists. none reads nothing: the embedded list prices alone. |
ORBIT_NODE_HOURLY_USD | 0 | runtime | USD per hour for a node whose instance type is not in orbit-api's embedded on-demand price list (see architecture.md → live mode). Any non-EC2 node, k3s included, lands here. 0 counts such a node as free, which surfaces as an implausibly small bill rather than an invented one. Must be a non-negative number. |
ORBIT_RECOMMENDATIONS_REFRESH | 5m | runtime | How often the Deck's recommendations are recomputed in the background, per cluster; requests get the last result, so a recommendation is at most one interval old. A failed run is not served: the next request computes again. 0 computes on every request, as the Go original (tag go-oracle) did. Anything but 0 or a Go duration of 1s or more refuses to start. |
ORBIT_TRUSTED_PROXIES | empty | runtime | Comma-separated CIDRs (or single addresses) of proxies between web and orbit-api whose X-Forwarded-For is believed: a mesh sidecar, an internal gateway. Not web itself: a request carrying orbit-api's own bearer is web's, and its X-Forwarded-For is already believed (Addendum v0.5). The client address, for the audit trail and every per-client limit, is the nearest hop in that header not on this list. Empty is right for every shipped install path; a pod CIDR here would also skip the ingress's own address. An entry that is not an address refuses to start. |
ORBIT_SHUTDOWN_GRACE | 180s | runtime | Graceful-shutdown budget, matched to nocturne's so a proxied answer (up to 150s of streaming) is allowed to finish; any proxied stream still open 5s before the budget ends is closed with an event: done frame carrying finishReason: "shutdown". Must stay below the pod/container's own termination grace period (200s in every shipped manifest) or SIGKILL wins the race; see operations.md. (CONTRACT.md's base table says 15s; the addendum and the shipped defaults supersede it.) |
ORBIT_AUTH_MODE | static | runtime | static | oidc | disabled. See "Auth modes" below. |
ORBIT_AUTH_TOKEN | empty | runtime, from Secret | Required, ≥32 bytes, when mode is static. The service refuses to start otherwise. |
ORBIT_OIDC_ISSUER | empty | runtime | Required when mode is oidc. |
ORBIT_OIDC_AUDIENCE | empty | runtime | Required when mode is oidc. |
ORBIT_METRICS_ADDR | :9090 | runtime | Separate listener for /metrics (Addendum v0.2). Never the API listener; never routed by an ingress. |
ORBIT_CONTACT_WEBHOOK_URL | empty | runtime, from Secret | Optional. Every lead the site's contact form stores (under ORBIT_DATA_DIR/leads, listed at /deck/admin/leads) is also POSTed here as JSON, retried in the background three times; a failure is logged and loses nothing. A webhook URL usually carries its token: never logged, never in a committed file. With NetworkPolicy on, orbit-api also needs components.orbit-api.networkPolicy.allowInternetEgress. |
Identity (Addendum v0.5)
| Var | Default | Scope | Meaning |
|---|---|---|---|
ORBIT_DATA_DIR | /var/lib/sreorbit | runtime | Users, roles, sessions, dashboards, alert acknowledgements, leads and the audit trail, as files. Must be writable, or orbit-api refuses to start. One writer: run one replica. A PVC in the chart with components.orbit-api.persistence.enabled (keep mountPath equal to this), an emptyDir otherwise, the named volume orbit-api-data on compose. See identity.md → "Where the state lives". |
ORBIT_SESSION_SECRET | empty | runtime, from Secret | HMAC key that signs session tokens, 32 bytes or more (openssl rand -base64 48); shorter refuses to start. Empty: a 32-byte key is generated once into ORBIT_DATA_DIR/session.key. Changing it ends every session. Set it when backups of the data directory must not carry the signing key. |
ORBIT_ADMIN_USER | empty | runtime, from Secret | The first admin's username, created at startup only when no user exists; ignored afterwards. Lowercased, then [a-z0-9][a-z0-9._-]{0,31}. Set together with the next one or neither: one alone refuses to start. |
ORBIT_ADMIN_PASSWORD_VERIFIER | empty | runtime, from Secret | That admin's password as a PBKDF2 verifier (node apps/web/scripts/hash-password.mjs < admin-password), never the password. A malformed one refuses to start. |
ORBIT_AUDIT_RETENTION | 90d | runtime | How long the audit trail keeps a day: days (90d, 365d) or a Go duration of 24h or more. See audit.md. |
ORBIT_CHAT_RETENTION | 5d | runtime | How long a Nocturne conversation is kept after its last message: days (5d) or a Go duration from 1h to 90d. An hourly sweep deletes expired ones from disk, including those of users who never sign in again. |
Single sign-on seeds (Addenda v0.8 and v0.19)
Both providers are normally set up in the console, at Admin > Integrations. These variables
seed one only while the store holds no settings document for it; the first save in the
console wins from then on. Unset, the provider is off. See identity.md → "Single sign-on".
| Var | Default | Scope | Meaning |
|---|---|---|---|
ORBIT_SSO_GOOGLE_CLIENT_ID | empty | runtime | Google's Web application client ID, <digits>-<id>.apps.googleusercontent.com. Set with the next two, or none of the three: anything in between refuses to start. |
ORBIT_SSO_GOOGLE_CLIENT_SECRET | empty | runtime, from Secret | Its client secret. Never logged, never answered by a read. |
ORBIT_SSO_ALLOWED_DOMAINS | empty | runtime | The Workspace domains Google sign-in accepts, comma-separated; gmail.com is refused. |
ORBIT_SSO_DEFAULT_ROLE | viewer | runtime | The role of a first Google sign-in: viewer or editor. |
ORBIT_SSO_OIDC_ISSUER | empty | runtime | The OpenID Connect provider's issuer, https, exactly as its discovery document names it. Set with the next two, or none of the three: anything in between refuses to start, and so does any other ORBIT_SSO_OIDC_* without them. |
ORBIT_SSO_OIDC_CLIENT_ID | empty | runtime | The client ID at that provider. |
ORBIT_SSO_OIDC_CLIENT_SECRET | empty | runtime, from Secret | Its client secret (secrets.ssoOidcClientSecret in the chart). Never logged, never answered by a read. |
ORBIT_SSO_OIDC_DISPLAY_NAME | SSO | runtime | The name on the button, "Sign in with ...", and the provider's name in the audit trail. 40 characters at most. |
ORBIT_SSO_OIDC_SCOPES | openid email profile | runtime | Space-separated; must include openid. |
ORBIT_SSO_OIDC_ALLOWED_DOMAINS | empty | runtime | Email domains allowed in, comma-separated. Empty allows any address the provider vouches for. |
ORBIT_SSO_OIDC_EMAIL_CLAIM | email | runtime | The top-level ID-token claim holding the address. |
ORBIT_SSO_OIDC_GROUPS_CLAIM | groups | runtime | The top-level ID-token claim holding the groups. |
ORBIT_SSO_OIDC_GROUP_ROLES | empty | runtime | group=role pairs separated by ; or new lines, in order, the first match winning; each is split at its last =, so an LDAP DN works as a group. A role that does not exist refuses that person's sign-in (role_missing). |
ORBIT_SSO_OIDC_DEFAULT_ROLE | viewer | runtime | The role of anyone no group maps: viewer, editor or deny. deny needs at least one mapped group. |
SSL_CERT_FILE | unset | runtime | A PEM bundle orbit-api trusts instead of the image's roots, for a provider behind a private CA. Include the public roots in it when Google or a hosted provider must still verify. |
nocturne
| Var | Default | Scope | Meaning |
|---|---|---|---|
NOCTURNE_ADDR | :8081 | runtime | Listen address for the API. |
NOCTURNE_LOG_LEVEL | info | runtime | Log level. |
NOCTURNE_LOG_PROBES | false | runtime | Log probe and /metrics requests at info. |
NOCTURNE_PROVIDER | mock | runtime | mock | openai | openai-responses | anthropic. mock needs no credential and makes no outbound call, so the demo runs dry. openai-responses is OpenAI's Responses API: reasoning effort up to max, the model's reasoning carried across tool turns, store=false. anthropic is the Messages API (e.g. claude-sonnet-5-5): a set effort turns on adaptive thinking, thinking blocks go back with their signature across tool turns, tools and system prompt are cached across chats and the conversation tail across tool steps, and on the Claude API a refusal is retried on Anthropic's default fallback model (beta server-side-fallback-2026-07-01). A refusal ends the answer with finish refusal. |
NOCTURNE_BASE_URL | empty | runtime | OpenAI-compatible base URL, e.g. https://api.openai.com/v1. Required when provider is openai or openai-responses. |
NOCTURNE_API_KEY | empty | runtime, from Secret | Provider credential. Never logged. Empty is valid when provider is mock. |
NOCTURNE_REASONING_MODEL | empty | runtime | Model id for the reasoning tier (analysis, root cause, FinOps plans). |
NOCTURNE_FAST_MODEL | empty | runtime | Model id for the fast tier (product help, short answers). |
NOCTURNE_REASONING_EFFORT | empty | runtime | Reasoning effort of the reasoning tier: none | minimal | low | medium | high | xhigh | max. Empty sends none. Which values a model takes is the provider's answer (chat completions stops at xhigh). With anthropic, none and minimal send low. |
NOCTURNE_FAST_EFFORT | empty | runtime | The same for the fast tier. |
NOCTURNE_MAX_TOKENS | 2048 | runtime | Response ceiling, reasoning tokens included: raise it with a high effort. |
NOCTURNE_TIMEOUT | 120s | runtime | Upstream provider timeout. The stream's write deadline is this plus 30s, so raise ORBIT_STREAM_TIMEOUT above both. |
NOCTURNE_TRIAGE_URL | empty | runtime | System 1: a typed classifier (POST /v1/systemone, TypeSafe's Jev API) that routes the questions the keywords miss and ranks the health sweep an outage question opens with. Empty turns it off. |
NOCTURNE_TRIAGE_API_KEY | empty | runtime, from Secret | Its credential. Required with the URL. Never logged. |
NOCTURNE_TRIAGE_MODEL | empty | runtime | Its model id, e.g. a pinned version. Required with the URL. |
NOCTURNE_ORBIT_URL | empty | runtime | orbit-api's base URL, which the cluster tools read. Empty runs the assistant with no tools. |
NOCTURNE_ORBIT_TOKEN | falls back to ORBIT_AUTH_TOKEN | runtime, from Secret | The bearer the tools present to orbit-api, beside the asking user's session. Never logged. |
NOCTURNE_TOOL_TIMEOUT | 10s | runtime | One tool call, orbit-api included. Longer than NOCTURNE_TIMEOUT refuses to start. |
NOCTURNE_MAX_TOOL_STEPS | 6 | runtime | Model turns that may call tools in one answer, 1 to 20. |
NOCTURNE_TOOL_MAX_BYTES | 8000 | runtime | The most of one tool result the model reads, 1024 to 65536 bytes. |
NOCTURNE_TRUSTED_PROXIES | empty | runtime | Same semantics as ORBIT_TRUSTED_PROXIES. orbit-api is nocturne's only peer and forwards the chain it saw, so name the same CIDR here. |
NOCTURNE_AUTH_MODE | static | runtime | Same semantics as ORBIT_AUTH_MODE. nocturne is reachable only through orbit-api on the network, but "unreachable" is a network control, not an authentication one, and it's the component that carries model spend. |
NOCTURNE_AUTH_TOKEN | empty | runtime, from Secret | Required, ≥32 bytes, when mode is static. |
NOCTURNE_OIDC_ISSUER | empty | runtime | Required when mode is oidc. |
NOCTURNE_OIDC_AUDIENCE | empty | runtime | Required when mode is oidc. |
NOCTURNE_METRICS_ADDR | :9090 | runtime | Separate listener for /metrics (Addendum v0.2). |
NOCTURNE_SHUTDOWN_GRACE | 180s | runtime | Graceful-shutdown budget, the same as orbit-api's, so an in-flight SSE stream has time to drain. A drain overrun logs shutdown incomplete and exits 0; it is never reported as a startup failure. |
ORBIT_DEMO_DATA | true | runtime | Read by nocturne too, with the same meaning as on orbit-api: false refuses NOCTURNE_AUTH_MODE=disabled. |
orbit-stack
The Helm chart sets ORBIT_STACK_QUERY_RPM to 60000 and ORBIT_STACK_QUERY_BURST to 3000: every
Deck viewer reads through orbit-api, one client address, and a 30-day traces page is about a
hundred reads.
Every variable of the telemetry engine, with its default and meaning, is in
orbit-stack.md so the engine's page stays self-contained:
ORBIT_STACK_ADDR (:8082), ORBIT_STACK_METRICS_ADDR (:9090), ORBIT_STACK_LOG_LEVEL,
ORBIT_STACK_LOG_PROBES, ORBIT_STACK_DATA_DIR (/data, a volume), ORBIT_STACK_RETENTION
(15d), ORBIT_STACK_BLOCK_DURATION (2h), ORBIT_STACK_COMPRESSION (better),
ORBIT_STACK_BLOCK_CACHE_BYTES, ORBIT_STACK_HEAD_CHUNK_SAMPLES (120),
ORBIT_STACK_MAX_SERIES (0), ORBIT_STACK_MAX_LABELS_PER_SERIES (64),
ORBIT_STACK_MAX_LABEL_NAME_LEN (256), ORBIT_STACK_MAX_LABEL_VALUE_LEN (4096),
ORBIT_STACK_MAX_INDEX_BYTES, ORBIT_STACK_QUERY_TIMEOUT (30s),
ORBIT_STACK_QUERY_MAX_SAMPLES, ORBIT_STACK_QUERY_TURNS (0), ORBIT_STACK_QUERY_RPM (3000), ORBIT_STACK_QUERY_BURST
(300), ORBIT_STACK_MAX_BODY_BYTES, ORBIT_STACK_AUTH_MODE
(static), ORBIT_STACK_AUTH_TOKEN (from Secret, ≥ 32 bytes),
ORBIT_STACK_TRUSTED_PROXIES, ORBIT_STACK_SHUTDOWN_GRACE (30s), and for traces
ORBIT_STACK_TRACE_RETENTION (7d), ORBIT_STACK_TRACE_HEAD_BYTES (64MiB) and
ORBIT_STACK_TRACE_MAX_BYTES (5MiB, one trace; spans past it are refused) and
ORBIT_STACK_TRACE_GRAPH_PENDING (100000, service-graph spans waiting for their pair), which
apm.md explains. orbit-api reaches it with ORBIT_STACK_URL and
ORBIT_STACK_TOKEN (the same Secret key, ORBIT_STACK_AUTH_TOKEN, read under a second
name, like ORBIT_NOCTURNE_TOKEN).
orbit-shop, the demo shop
The synthetic services that give APM real traces (apm.md → "The demo
shop"), shipped in the orbit-stack image as /orbit-shop. Not part of a production
install.
| Var or flag | Default | Meaning |
|---|---|---|
ORBIT_SHOP_OTLP | empty, required | The engine's base URL, http://orbit-stack:8082; spans go to its /v1/traces. |
ORBIT_SHOP_OTLP_TOKEN | empty | The engine's bearer, ORBIT_STACK_AUTH_TOKEN, when its auth is static. |
ORBIT_SHOP_URL_<SERVICE> | empty | In --service mode, where each other service answers: ORBIT_SHOP_URL_API_GATEWAY, ORBIT_SHOP_URL_CATALOG, and so on, the name upper-cased with - as _. |
POD_NAME, POD_NAMESPACE, NODE_NAME | the service name, shop, unknown | The span resource, from the downward API. |
PORT | 8080 | The listen port in --service mode. |
--all / --service NAME | none | Every service in one process on 127.0.0.1 from --port-base (default 18110), or one service (loadgen for the load alone). Exactly one of the two. |
--rps | 5 | Requests a second the load generator sends, 0 to 1000. Compose reads it from ORBIT_SHOP_RPS, the chart from demo.shop.rps. |
Auth modes
Set with ORBIT_AUTH_MODE / NOCTURNE_AUTH_MODE, independently per service (in
practice, run both the same way):
| Mode | When to use it | What it needs |
|---|---|---|
static (default) | Single shared credential, the common case for a self-hosted install. | ORBIT_AUTH_TOKEN / NOCTURNE_AUTH_TOKEN, ≥32 bytes. |
oidc | You already run an identity provider and want per-caller identity instead of a shared secret. | <PREFIX>_OIDC_ISSUER and <PREFIX>_OIDC_AUDIENCE; the issuer's JWKS must be reachable from the pod. |
disabled | A laptop demo only. | Nothing, and it must stay that way. Refused outright when ORBIT_DEMO_DATA=false, so it cannot be left on against a real cluster by accident. |
Generating a static token
ORBIT_AUTH_TOKEN and NOCTURNE_AUTH_TOKEN are shared bearers you generate; nothing
in this repository ships one. The requirement is "≥32 bytes"; the command below
produces a 64-character hex string (32 bytes of real entropy, hex-encoded so it never
needs shell-quoting):
openssl rand -hex 32Run it three times: orbit-api, nocturne and orbit-stack each need their own
token, and web needs a copy of orbit-api's (it's the bearer web's server attaches when it proxies
/api/*). Where each one goes depends on the install path; see the "Secrets" section of
install/docker-compose.md,
install/helm.md, or install/kubectl.md.
Two optional secrets belong to identity, not to a service hop: ORBIT_SESSION_SECRET
(openssl rand -base64 48) and the first admin's verifier, which
identity.md → "The first admin" generates.
Never commit a generated token. Never put one in a values file, a ConfigMap, or a
ChartYAML default. CONTRACT.md: "Secrets are referenced, never embedded in a chart
default."
demo vs live: two different flags
NEXT_PUBLIC_DEMO_MODE (on web, build-time) and ORBIT_DEMO_DATA (on orbit-api,
runtime) look like the same switch and are not:
NEXT_PUBLIC_DEMO_MODE=truemeans the Orbit Deck UI reads its own synthetic data (apps/web/src/lib/demo-estate.ts) directly, without ever callingorbit-api.ORBIT_DEMO_DATA=truemeansorbit-apiitself serves a deterministic demo estate instead of querying a live cluster, independent of whether anything is calling it, and creates the three demo accounts on a first start with no user.falseselects the live source (services/rust/orbit-api/src/live.rs), which needs credentials for at least one cluster (seeORBIT_KUBECONFIG) and refuses to start without them.
Setting one without the other is a valid but confusing configuration (web never
calls orbit-api regardless of what orbit-api would have returned). Set them
together. See architecture.md → "The data path for a metric, ingest to pixel" for
exactly what each combination does.
Ports, all four components, one table
| Component | API port | Metrics port | Exposed by default ingress? |
|---|---|---|---|
web | 3000 | none (Next.js serves no /metrics) | Yes, the only one |
orbit-api | 8080 | 9090 | No (proxied through web) |
nocturne | 8081 | 9090 | No (proxied through orbit-api; no ingress rule exists for it at all) |
orbit-stack | 8082 | 9090 | No (queried by orbit-api; written to by in-cluster agents; no ingress rule) |
Where to go next
- What each auth mode's failure mode looks like in practice, and the threat model
behind these defaults:
security.md. - The exact command sequence that consumes these variables for your install path:
install/README.md.