Docs · Hangar
Hangar
Home base for building, releasing, and watching every service you run.
Documentation
The table of contents for the whole Hangar platform — Hangar itself, Airframe
(the service catalog), Glidepath (CI/CD), Tower (the Backstage UI), Apron
(the cluster template), and Autopilot (AI agent workloads, bounded and audited). Available two ways: browsable here across each repo’s own
docs/, and through Tower’s TechDocs tab once a component’s catalog-info.yaml
is registered in the catalog (Airframe and Glidepath are wired as of 2026-09-21;
Tower now has a catalog-info.yaml and mkdocs.yml; Backstage itself and Apron are not yet — see Open items).
Convention going forward: every new illustrated doc/artifact this project produces gets a line added to the relevant section below, at the time it’s created — not batched up later.
Start here
| Doc | Read this when… |
|---|---|
| Business rules | You want every rule Hangar applies, across every component, in one place: who may do what, what gates a release, what the clusters refuse, how strongly each rule holds, and which rules are not enforced yet. |
| service-catalog-design.md | You want the full design history and open decisions behind Airframe — the running log, not the as-built summary. |
| gitops-strategy.md | You want the repo topology, ArgoCD instance split, and the lower/upper env security boundary. |
| cluster-provisioning.md | You’re standing up a new cluster. |
| prod-infisical-migration-plan.md | You’re moving the prod cluster onto the new airframe pin and retiring the Infisical operator (plan, not yet executed). |
| local-clusters.md | You’re running clusters locally and want the operational notes. |
| rebuild-lab.md | You’re rebuilding the lab clusters with Apron. |
| backstage-design.md | You want Tower’s own design rationale — self-service flows, the terasky ingestor, catalog structure. |
SLOs
Added 2026-10-01. How an SLO is declared, measured, shown in Tower, and announced, with four diagrams, also in the diagram gallery.
| Doc | Read this when… |
|---|---|
| slo/README.md | You want to declare an SLO, understand its three notification signals (budget exhausted, burning fast, no data), or work out why one did or didn’t fire. |
Portability: any forge, any registry
Added 2026-10-15. A proposal, nothing built: running Hangar on GitLab and Bitbucket as well as GitHub, and on any OCI registry as well as GHCR. Six diagrams, also in the diagram gallery.
| Doc | Read this when… |
|---|---|
| portability/README.md | You want to know where GitHub and GHCR are load-bearing today, the two Hangar contracts that replace them, the credential differences per forge, the migration of the live GitHub fleet, the 24-week roadmap and the seven decisions it needs. The illustrated version is in the Library. |
Architecture reviews
Added 2026-09-27. Point-in-time reviews of the whole platform, each a standalone illustrated page under reviews/.
| Doc | Read this when… |
|---|---|
| Architecture review, 2026-09-27 | You want a staff architect’s verdict on Hangar as the company platform: conditional approval, ten findings with evidence, what to add, change and remove, and the five gates for production. The full review is a standalone page on the website. |
Autopilot — AI agent workloads
Added 2026-09-26. Design, plan and diagrams live in this repo under autopilot/.
| Doc | Read this when… |
|---|---|
| autopilot/README.md | You want the one-page overview and where everything is. |
| autopilot/roadmap.md | You want the unified plan: Airframe A+, Autopilot and Skyport AI in six milestones, with decisions and unverified items. |
| autopilot/airframe-ai-friendly.md | You want to know how AI-operable Airframe is (measured, baseline 27/100) and the ten workstreams to get to A+. |
| autopilot/design.md | You want the Autopilot design: two planes, the workload model, tiers, policy, backends, failure modes. |
| autopilot/skyport-ai-workloads.md | You want the six Skyport agents, one per workload shape, and how each is tested. |
| autopilot/glossary.md | A term is unfamiliar. |
| Diagram gallery | You want pictures: 37 one-page diagrams in three sets, on the website. |
Airframe — the service catalog
Developer- and admin-facing docs live in the airframe repo itself.
| Doc | Read this when… |
|---|---|
| airframe/docs/user/README.md | You’re creating a service, adding ground/flight environments, or attaching a component. |
| airframe/docs/user/quickstart.md | You want the full worked example — boarding-api (NodeJS): pull in the code, both env tiers, a Redis cache, a canary. |
| airframe/docs/user/quickstart-flight-api.md | You want a service that owns a database — flight-api (Spring Boot + PostgreSQL): the database as a component, credentials read from its Secret with valueFrom, a call from boarding-api, and the same service on the prod cluster. Read part 1 first. |
| airframe/docs/user/skyport-demo.md | You want the plan for the five-service Skyport demo system that exercises every stack and component, and where its code lives. |
| airframe/docs/user/decommission-app.md | You need to delete/decommission an app: what gets destroyed (both GitHub repos), the git-driven order of operations, and the ArgoCD ordering bug. Proven once on boarding-api. |
| airframe/docs/admin/architecture.md | You want the as-built reference — every XRD’s inputs/outputs, the composition graph, the plumbing. |
(Local checkout note: since this repo and airframe are cloned as siblings on
this machine, ../../airframe/docs/... also resolves locally — the links above
use full GitHub URLs instead because this page is also built by TechDocs, which
renders each repo’s docs in isolation and can’t follow a relative link across a
repo boundary.)
Illustrated / interactive:
| Doc | Status | Read this when… |
|---|---|---|
| Airframe Service Catalog | current | You want the architecture reference with real diagrams — same content as admin/architecture.md. |
| Airframe Quickstart | current, 2026-09-24 | Illustrated walkthrough of quickstart.md (part 1): NodeJS boarding-api, code pull-in, ground and flight, a Redis cache read with valueFrom, and a canary. Redis is verified live; the canary is not. |
| Airframe Database Quickstart | current, 2026-09-24 | Illustrated walkthrough of quickstart-flight-api.md (part 2): flight-api (Spring Boot + PostgreSQL) on both clusters, credentials via valueFrom, the NetworkPolicy proof, and a call from the gate board. Not yet walked through Tower and the pipeline. |
| Hangar Service Catalog | vision, 2026-09-17 | You want the original ELI10 pitch and roadmap for components not yet built (Postgres, RabbitMQ, MongoDB, OAuth, nginx). Its “dedicated vs. shared” diagram describes a mode: create|attach field that was never built for Redis — see admin/architecture.md for what actually shipped. |
Glidepath — CI/CD
Full user and admin documentation already lives in the glidepath repo; this is
the on-ramp, not a duplicate.
| Doc | Read this when… |
|---|---|
| glidepath/docs/user/README.md | You’re onboarding an app or maintaining its cicd.yaml. |
| glidepath/docs/admin/README.md | You’re running the platform — architecture, security model, ADRs, operations. |
Illustrated / interactive:
| Doc | Read this when… |
|---|---|
| Glidepath | You want the illustrated platform overview. |
| Pipeline Atlas · platform-cicd catalog | You want the pre-rename catalog reference (platform-cicd → Glidepath). |
| Sigstore Ecosystem | You want the keyless-signing (Fulcio/Rekor/cosign) reference behind admin/image-signing.md. |
| RHDH Plugin Manifest | You’re evaluating a Backstage/RHDH plugin for Tower. |
| Upstream Candidates | You want the roadmap of upstream tools being evaluated. |
Tower — the Backstage UI
Tower’s own documentation lives in the tower repo’s docs/
(also published through TechDocs). Start with these:
| Doc | Read this when… |
|---|---|
| Deployments | You want to know what the Deployments tab tells you: the plain-language troubleshooting banner and its rules, the six-step delivery path, and every control explained (Argo CD sync, force sync and terminate, the Rollout actions, Roll back). |
| Security model | You want to know who may do what from Tower, and the guardrails behind each action: owners and admins, no standing Kubernetes write permissions, the Argo CD account’s scope, audit, what Tower never does. |
| Break-glass debugging | You need to look inside a running pod: a recorded, time-boxed debug shell without exec. Walkthroughs for Ground and Flight (two-person approval), breaking the glass and reviews, recordings, the guardrails layer by layer, troubleshooting. |
| Break-glass admin guide | You run break-glass: architecture, setting it up on a cluster, configuration, the admission policies (Ground and Flight), the operations runbook, internals, design decisions, testing. |
| Environments | You’re adding, configuring or removing an environment, or editing its values. |
| Release records | You want the Releases tab’s records: the next release’s draft, release modes and sign-off, sealing, outcomes and the bake window, release names, GitHub Releases. |
| Supply chain | You want to know what the supply-chain chips mean, why a step is green, amber, red or grey, and what to do about each result. |
The illustrated design set below records how the tabs came to be:
| Doc | Read this when… |
|---|---|
| Tower Field Report | You want the current-state evaluation: what’s live, what’s thin. |
| Tower Dashboard Mockups | You want the Fleet Grid / Ops Wall dashboard concepts. |
| Tower Recent Activity | You want the activity-feed design. |
| Tower Release Matrix | You want the release-matrix design (Releases tab + Overview pill). |
| Tower Releases Revamp | You want the Releases tab redesign. |
| Tower Deployments Tab Concepts | You want the Deployments tab concepts. |
| Tower Rollout Mockups | You want the rollout-visualization concepts. |
| Tower CI/CD Mockups | You want the CI/CD tab (“Ground Control”) concepts. |
| Release Gates Mockup | You want the release-gates UI concept. |
| Release Flow Concepts | You want release-flow visualization concepts. |
| Release Thread Patterns | You want the release-thread (activity-log) pattern language. |
| Active Delivery Redesign | You want the write-action/RBAC UI redesign. |
Brand & design system
| Doc | Read this when… |
|---|---|
| Hangar Brand System | You’re designing anything Hangar-branded — palette, type, the amber/sky accent rule. |
| Hangar Logo Concepts | You want the logo design history — Concept A is final. |
Kubernetes fundamentals (general reference, not Hangar-specific)
Not part of the Hangar product — background reading that happens to live in the same artifact list. Not linked from Tower.
- Kubernetes Cluster Architecture
- Pod Instantiation: From kubectl apply to Running
- Worker Node Internals: From kubelet to Kernel
- Pod Termination & the SIGTERM Race
- Request Path: Client to Pod
- CPU Requests vs Limits
- Crossing Cluster Boundaries
Open items
- This index was curated by title and publish date, not by re-reading every
linked artifact. The Airframe and Glidepath sections above are verified
against real source (
xrds/,compositions/, the actualdocs/trees); the Tower and brand sections are placed by title alone — flag anything miscategorized or stale. - Backstage itself and Apron have no
catalog-info.yaml/mkdocs.ymlyet — their docs don’t appear in TechDocs until that’s added. Airframe, Glidepath (2026-09-21) and Tower do. - Tower has no
docs/user//docs/admin/split — its as-built docs (Deployments, Security model, Environments, …) are one flat set; worth splitting the same way Airframe and Glidepath do once it grows. - Live-status and incident write-ups for the dev cluster are one-off artifacts, not curated docs — deliberately left out of this index.