Skip to content

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

#PageWhat it's for
1architecture.mdThe four components, what talks to what, the auth boundary, and what leaves your account (nothing). Read this first: every other page assumes it.
2install/README.mdWhich of the four install paths to use, and why.
2ainstall/local-k3d.mdThe laptop loop: a throwaway Kubernetes cluster in one command. Start here if you're kicking the tyres.
2binstall/docker-compose.mdSingle host, no Kubernetes. The fastest path to a running stack.
2cinstall/helm.mdThe production path, for any real cluster.
2dinstall/kubectl.mdPlain manifests, for teams that cannot or do not run Helm.
3configuration.mdEvery environment variable, its default, and what it means, in one table for all four components.
4security.mdThe threat model, what the auth middleware does, what NetworkPolicies do and don't enforce, and the questions a security reviewer will ask.
4aidentity.mdUsers, sessions and roles: the first admin, signing in from a browser and a shell, the closed permission list, and where the state lives.
4baudit.mdWhat the audit trail records, how to query and export it, its retention, and how the client address is decided.
5api.mdEvery route, every request and response shape, the closed error-code set, the SSE frame types, and every hard limit.
5aapm.mdSending OpenTelemetry traces, the series the engine derives under Tempo's names, the APM pages, and the demo shop.
5bdashboards.mdBuilt-in and custom dashboards: the editor, variables, the JSON model, import from Grafana, permissions.
5clogs.mdSearching the logs the engine stores: how lines arrive, the query language, the histogram and facets, the live tail.
5dingestion.mdDeciding what the engine stores of traces and logs: sampling rates, exclusion filters, the impact preview, and the checked, audited save.
5esql.mdRead-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.
5fdatabases.mdQuerying 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.
5gterminal.mdA shell in a pod from the Deck: turning it on, what is recorded and audited, its limits, and replaying a session.
5hfeatures.mdTurning whole features off for one installation: the twelve switches, the vendor lock, the presets, what orbit-api refuses, and the audit.
6operations.mdWhat to watch once it's running: saturation signals, log shape, probe semantics, backups of orbit-api's data, audit retention.
6aalerts.mdThe six derived alert rules, one runbook section each, and acknowledging and silencing them.
7troubleshooting.mdSymptom → cause → fix, including the failure modes we've already hit.
8benchmark.mdThe 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.
8aorbit-stack.mdThe telemetry engine: what it stores and how, compaction, every endpoint, the PromQL it answers, its configuration, and how to point an agent at it.
9changelog.mdWhat changed, contract version by contract version.
10status.mdAn honest, as-of-now snapshot of what's implemented versus scaffolded.

If you are an agent installing this unattended

  1. Read architecture.md once, in full, before touching a terminal.
  2. Pick one path from install/ based on what's already available in this environment (install/README.md has the decision table). Don't mix paths.
  3. Follow that page's command sequence exactly, in order. Every command is independently copy-pasteable; none depend on shell state from outside the page.
  4. 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-api route but a handful needs a user, and identity.md → "The first admin" says how the first one is created on your path.
  5. If a command fails, go to troubleshooting.md before 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.
  6. 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 optional ORBIT_SESSION_SECRET and ORBIT_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.
  • CHANGEME markers 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.md byte-for-byte, including the ORBIT_ / 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.md and orbit-stack.md list them all.
  • Numbers that describe product performance (disk, ingest, RAM, latency) come from CLAIMS.md, which cites the benchmark run behind each one, or, on benchmark.md and where a page points to it, from the report under services/rust/orbit-stack/bench/runs/ that the sentence names, as CLAIMS.md itself allows. No other number is printed: not a Go benchmark, not a builder's own run. Every ratio carries the scope CLAIMS.md or its report gives it.