Skip to main content
Amends 0076. Desktop and PWA delivery is in ADRs 0249 to 0256 (wave 2, desktop and PWA group).

​
Context

On-prem and air-gapped installs run the same product in a customer’s environment. The owner’s answers PK9 to PK14 (mem L467–469, L377, 2026-10-20) set the packaging, the air-gap mechanism and the upgrade rule. The owner also set SaaS first: on-prem stays green in CI but is not sold until it is solid (gap analysis, owner 2026-10-20 night).

​
Decision

  1. Packaging (PK9). Helm charts and Docker Compose files are generated by gen from app-manifest.json, and CI tests them on every release.
  2. Registry (PK11). The importer pushes images to the customer’s registry, or loads them with docker load.
  3. Air-gap (PK10 and PK12). Air-gapped installs use a signed offline bundle built by stackra bundle. Day one includes both:
    • Zarf packages for the Kubernetes deployments, and
    • a signed Docker Compose bundle, with offline SDK tarballs. The importer verifies the Keygen licence (ADR 0178). A customer-run Verdaccio is optional.
  4. Upgrades (PK14). Upgrades go one minor version at a time, N to N+1. Each has a preflight, a mandatory backup, migrations as a job, and rollback by restore. The last two minors are supported.
  5. SaaS first. On-prem and air-gapped builds stay green in CI, but they are not sold until solid.

​
Consequences

  • A customer upgrade is always one step, which keeps the migration matrix small.
  • The bundle is the unit of air-gap delivery, so it is tested the same way as the SaaS image.

​
Enforcement

planned — the release job generates and tests the Helm and Compose artefacts, and the air-gap job runs with no network (ADR 0182).

​
Open questions

  1. D-14: the minimum on-prem footprint. Which of ZITADEL, Valkey, MinIO, ClamAV, Gotenberg, ffmpeg, Tesseract, vLLM, Chatwoot, Centrifugo, Convoy, Temporal and ClickHouse are required, and which are optional, with sizing.

​
Alternatives

  • Zarf as the only packaging: not chosen as the only route; the Compose bundle is the base.

​
Supersedes and sources

Supersedes: none. Amends: 0076. Sources: owner answers PK9–PK14 (stackra-decisions-2026-10-19.md L377, L467–469, 2026-10-20); gap analysis D-14 and E-04.