> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 0179 — On-prem and air-gapped delivery

> Accepted · 2026-10-20

> [!NOTE]
>
> Amends [0076](/adr/0076-every-package-runs-saas-on-prem-and-air-gapped). 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](/adr/0076-every-package-runs-saas-on-prem-and-air-gapped). Sources: owner answers PK9–PK14 (`stackra-decisions-2026-10-19.md` L377, L467–469, 2026-10-20);
gap analysis D-14 and E-04.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.