Overview
Documentation
This documentation is written so that an AI agent can install SRE Orbit from it without a human: every value, every port and every prerequisite is written down. If you find a command that doesn't work as printed, or a value that isn't written down, that's a bug in this documentation, and you are not expected to fill the gap in.
Audience. Two readers, one document set: a platform engineer who already runs Kubernetes, and an autonomous coding agent with shell access and no prior context on this repository. Every command is copy-pasteable. Every placeholder says, in the same sentence, exactly how to obtain the real value.
Source of truth. This documentation describes the product as specified in
CONTRACT.md (including Addendum v0.2: mandatory
authentication, an isolated metrics port, and a single browser-facing component; and
Addendum v0.5: users, roles, the audit trail, dashboards and APM),
CLAIMS.md (every number), and DESIGN.md (the
frontend). Where this documentation and those files disagree, the root files win;
open an issue.
Read in this order
| # | Page | What it's for |
|---|---|---|
| 1 | architecture.md | The four components, what talks to what, the auth boundary, and what leaves your account (nothing). Read this first: every other page assumes it. |
| 2 | install/README.md | Which of the four install paths to use, and why. |
| 2a | install/local-k3d.md | The laptop loop: a throwaway Kubernetes cluster in one command. Start here if you're kicking the tyres. |
| 2b | install/docker-compose.md | Single host, no Kubernetes. The fastest path to a running stack. |
| 2c | install/helm.md | The production path, for any real cluster. |
| 2d | install/kubectl.md | Plain manifests, for teams that cannot or do not run Helm. |
| 3 | configuration.md | Every environment variable, its default, and what it means, in one table for all four components. |
| 4 | security.md | The threat model, what the auth middleware does, what NetworkPolicies do and don't enforce, and the questions a security reviewer will ask. |
| 4a | identity.md | Users, sessions and roles: the first admin, signing in from a browser and a shell, the closed permission list, and where the state lives. |
| 4b | audit.md | What the audit trail records, how to query and export it, its retention, and how the client address is decided. |
| 5 | api.md | Every route, every request and response shape, the closed error-code set, the SSE frame types, and every hard limit. |
| 5a | apm.md | Sending OpenTelemetry traces, the series the engine derives under Tempo's names, the APM pages, and the demo shop. |
| 5b | dashboards.md | Built-in and custom dashboards: the editor, variables, the JSON model, import from Grafana, permissions. |
| 5c | logs.md | Searching the logs the engine stores: how lines arrive, the query language, the histogram and facets, the live tail. |
| 5d | ingestion.md | Deciding what the engine stores of traces and logs: sampling rates, exclusion filters, the impact preview, and the checked, audited save. |
| 5e | sql.md | Read-only SQL over the estate, costs, the audit trail, logs, traces and metrics: the language, every table and column, the functions, the limits and the examples. |
| 5f | databases.md | Querying your own PostgreSQL and MySQL databases from the SQL editor, read-only in three layers: ORBIT_SEAL_KEY, the read-only user to create, RDS security groups and the chart's egress. |
| 5g | terminal.md | A shell in a pod from the Deck: turning it on, what is recorded and audited, its limits, and replaying a session. |
| 5h | features.md | Turning whole features off for one installation: the twelve switches, the vendor lock, the presets, what orbit-api refuses, and the audit. |
| 6 | operations.md | What to watch once it's running: saturation signals, log shape, probe semantics, backups of orbit-api's data, audit retention. |
| 6a | alerts.md | The six derived alert rules, one runbook section each, and acknowledging and silencing them. |
| 7 | troubleshooting.md | Symptom → cause → fix, including the failure modes we've already hit. |
| 8 | benchmark.md | The disk, ingest, RAM and query-latency comparison against Prometheus and VictoriaMetrics: the methods as they were run, the scripts that reproduce them, and the measured numbers with their losses. |
| 8a | orbit-stack.md | The telemetry engine: what it stores and how, compaction, every endpoint, the PromQL it answers, its configuration, and how to point an agent at it. |
| 9 | changelog.md | What changed, contract version by contract version. |
| 10 | status.md | An honest, as-of-now snapshot of what's implemented versus scaffolded. |
If you are an agent installing this unattended
- Read
architecture.mdonce, in full, before touching a terminal. - Pick one path from
install/based on what's already available in this environment (install/README.mdhas the decision table). Don't mix paths. - Follow that page's command sequence exactly, in order. Every command is independently copy-pasteable; none depend on shell state from outside the page.
- Use that page's own "verify" section to confirm health before declaring success.
A container that starts is not yet a container that is ready: the two
have different HTTP endpoints and this documentation never conflates them. Then sign
in: every Deck page and every
orbit-apiroute but a handful needs a user, andidentity.md→ "The first admin" says how the first one is created on your path. - If a command fails, go to
troubleshooting.mdbefore changing anything the page told you to run verbatim. Most first-run failures are one of the four entries at the top of that page. - Generate secrets yourself. Nothing in this repository ships a credential, and
every page that needs one (
ORBIT_AUTH_TOKEN,NOCTURNE_AUTH_TOKEN,NOCTURNE_API_KEY,ORBIT_STACK_AUTH_TOKEN,WEB_AUTH_VERIFIER, and the optionalORBIT_SESSION_SECRETandORBIT_ADMIN_PASSWORD_VERIFIER) says exactly which command produces it.
What this product is, in one paragraph
SRE Orbit is four containers you run in your own account: web (the marketing site
and the Orbit Deck console), orbit-api (the Deck's backend: clusters, workloads,
telemetry, FinOps, and the users, roles, dashboards and audit trail it keeps),
nocturne (the AI assistant, provider-abstract, streaming over SSE) and orbit-stack
(the telemetry engine: remote-write and OpenTelemetry traces in, PromQL and APM out).
We run no hosted backend, and nothing in the product needs one. architecture.md draws the whole picture, including the one architecture
decision every other page depends on: the browser talks to web, and only web.
Conventions used throughout
- Commands are shown exactly as typed, with
$implied and never printed literally. Copy the line starting after any comment. CHANGEMEmarkers do not appear here undefined. Every value a command needs is either given outright or generated by the command immediately before it.- Environment variable names match
CONTRACT.mdbyte-for-byte, including theORBIT_/NOCTURNE_/WEB_prefixes. A name without one of those prefixes is not a real variable this product reads, except the platform's own (PORT,NODE_ENV,HOSTNAME) and the downward-API names the demo shop reads (POD_NAME,POD_NAMESPACE,NODE_NAME);configuration.mdandorbit-stack.mdlist them all. - Numbers that describe product performance (disk, ingest, RAM, latency) come from
CLAIMS.md, which cites the benchmark run behind each one, or, onbenchmark.mdand where a page points to it, from the report underservices/rust/orbit-stack/bench/runs/that the sentence names, asCLAIMS.mditself allows. No other number is printed: not a Go benchmark, not a builder's own run. Every ratio carries the scopeCLAIMS.mdor its report gives it.