MeterBox on-prem & sovereign deployment guide

Owner: Eng. Review cadence: whenever a tier-level capability changes (scheduler, secrets backend, key-management story, compliance scope).

MeterBox ships in three operating models. Same Helm chart, same APIs, same data-plane image — only where it runs and who runs it differs.

Tier	Operator	Cluster	Best for
Cloud	MeterBox	Shared multi-tenant control plane + per-(org, env) data planes	SaaS teams that don't want to operate Kubernetes
Self-Managed	You	Your existing Kubernetes (EKS, GKE, AKS, k3s, OpenShift, on-prem)	Data residency, regulatory control, zero outbound deps
Managed (sovereign)	MeterBox SRE	Single-tenant cluster in your sovereign cloud / region	Defense, public sector, fintech, healthcare with FedRAMP / HIPAA / GDPR-grade requirements

The customer-facing summary lives at the Deployment section on the home page (data sourced from src/web/data/tiers.json). This document is the operator-facing runbook that backs those promises.

What each tier inherits

All three tiers ship the same surface:

The full /v1/* data-plane API (customers, plans, metering, entitlements, credits, coupons, webhooks, ledger).
The full /cp/* control plane (auth, MFA, SSO, audit, retention, env lifecycle, backup mirror).
The bundled in-cluster Postgres + Redis. Managed datastore services (RDS, Cloud SQL, Aurora, Elasticache, Memorystore) are explicitly not supported — see the customer-data-stays-in-cluster rule in README.md.
The same SPA dashboard, served from the control-plane pod.

Differences below are purely operational.

What you don't get (single-tenant by design)

Self-Managed and Managed run a dedicated control + data plane per tenant org. That's the value — and the constraint:

No cross-tenant analytics or benchmarks. MeterBox has no visibility into other tenants' usage, so there are no "how do you compare to other $segment customers" reports baked into the SPA. Build that from your own warehouse export.
No shared catalog. Plans, models, add-ons, and features are defined per tenant. There is no global price list, no central marketplace of plans, no shared promo codes.
No multi-tenant data plane. Self-Managed cannot be wired into a single multi-tenant deployment that serves several tenant orgs from one pod — the data plane is provisioned per-(org, env). Marketplace / white-label scenarios are on the P5 backlog (see the README roadmap).
No managed datastores. Postgres + Redis ship bundled in the Helm chart. RDS / Aurora / Elasticache / Cloud SQL are not supported substrates — this is the hard architectural rule that makes air-gapped deployment possible.

For the Self-Managed tier specifically, also note:

SCIM 2.0 + OIDC SSO + access-review CSV stay inside your cluster. Your IdP integration runs against /cp/scim/v2/* and /cp/sso/* on the Self-Managed control plane, and the quarterly access-review snapshot (GET /cp/access-review) is yours to download — no data leaves your cluster to produce it, which is what most enterprise security reviewers ask for first.

Self-Managed — installing the chart

# 1. Mirror the images into your registry (air-gapped clusters).
docker pull ghcr.io/<owner>/meterbox/control-plane:<tag>
docker pull ghcr.io/<owner>/meterbox/data-plane:<tag>
docker tag  ghcr.io/<owner>/meterbox/control-plane:<tag>  your-registry.example.com/meterbox/control-plane:<tag>
docker tag  ghcr.io/<owner>/meterbox/data-plane:<tag>     your-registry.example.com/meterbox/data-plane:<tag>
docker push your-registry.example.com/meterbox/control-plane:<tag>
docker push your-registry.example.com/meterbox/data-plane:<tag>

# 2. Configure values.
cp deploy/helm/meterbox/values.yaml my-values.yaml
# Edit: images.controlPlane / dataPlane, ingress.host, secrets.*, ...

# 3. Install.
helm install meterbox deploy/helm/meterbox -f my-values.yaml -n meterbox

Key Helm values to override

Value	Default	Notes
`images.controlPlane` / `dataPlane`	GHCR	Point at your registry mirror in air-gapped clusters
`images.pullSecretName`	unset	Required if the registry is private
`secrets.adminApiKey`	unset	Legacy admin-key gate; rotate yourself
`controlPlane.appBaseUrl`	empty	Where the SPA is served (used for reset links, SSO redirect)
`controlPlane.ingress.host`	`meterbox.local`	The ingress hostname for the cp / spa
`postgres.bundled`	`true`	Must stay `true` — in-cluster Postgres is the supported store
`redis.bundled`	`true`	Same rule
`warmPool.size` / `warmPool.regions`	3 / 3 regions	Pre-warmed slots per region (see warm-pool service)
`backupMirror.enabled`	`false`	Opt in to the encrypted off-cluster mirror
`backupMirror.key`	empty	32-byte AES-256-GCM key (64 hex chars) — cluster-wide default
`backupMirror.defaultTarget.kind`	`stub`	`stub` / `s3` / `gcs` / `azure`

Per-tenant overrides for the backup target are also available via PATCH /cp/organizations/me/backup-target — see backup-mirror.js.

Air-gap notes

No outbound network at runtime is required by the platform itself. The third-party integrations (Stripe, Resend, OIDC IdP, Pwned- Passwords API) are all env-gated — leaving the credentials unset disables that surface (returns a 501-shaped response or is hidden from the SPA).
TLS is operator-supplied. The chart's controlPlane.ingress.tls lets you point at an existing Secret; cert-manager / your own PKI plug in there.
Image scanning + admission (Kyverno, OPA Gatekeeper, Trivy) are entirely customer-controlled. The chart adds no admission webhooks.

Managed (sovereign) — what MeterBox SRE operates

The Managed tier is Self-Managed run by MeterBox SRE. The customer chooses the region (AWS GovCloud, GCP Assured, Azure Government, EU-only AWS, or on-prem) and the operating cluster is single-tenant — no other customer's data ever lands on it.

Customers in this tier:

Hold all keys. Backup-mirror data-encryption keys are envelope-encrypted per snapshot by the customer's KMS (AWS KMS / GCP KMS / Azure Key Vault) — MeterBox only sees the wrapped DEK and never the plaintext. JWT signing key + session cookie secret live in in-cluster secrets the customer rotates on its own schedule. See src/control-plane/services/backup-mirror.js for the envelope-encryption seam.
Get audit-log streaming to their SIEM via the cp NDJSON export (GET /cp/audit/export) plus an ongoing batched push handled by SRE.
Own the VPC peering (or air-gap, or VPN), with no MeterBox-owned ingress beyond the operator break-glass jumphost.
Receive a quarterly external pentest report plus a subprocessor list scoped to their region.

The operator-side procedures behind these promises — provisioning, on-call, upgrades, backup/restore drills, key rotation, SIEM cron-push samples for Splunk/Datadog/S3, and VPC-peering shapes (peered / Transit Gateway / air-gap) — live in docs/operator-runbook.md.

Compliance posture per tier

Tier	SOC 2	HIPAA	FedRAMP	ISO 27001	GDPR data residency
Cloud	Anchor cert (in progress — see `docs/compliance/`)	—	—	Roadmap	EU shared cluster planned
Self-Managed	Inherits customer's controls	HIPAA-ready (customer signs BAA with their cloud)	Customer-led, on customer infra	Roadmap	Inherent (your cluster, your region)
Managed (sovereign)	Anchor cert + customer's controls	Yes (with BAA)	Moderate — target	Yes (target)	Yes — region-pinned

Detailed control narratives live in docs/compliance/soc2-evidence-map.md and docs/compliance/audit-trail-architecture.md.

What we deliberately do NOT do, across all tiers

These are not gaps to close — they are explicit non-goals so the operating model stays clear:

No managed datastore providers. Postgres + Redis are always in-cluster workloads bundled by the chart.
No off-cluster backups by default. The encrypted mirror is opt-in per-org, encrypted with a key only the customer holds.
No silent telemetry to MeterBox from Self-Managed or Managed clusters. Outbound calls only happen for explicitly-configured integrations (Stripe webhooks, optional email transport, and — when the tenant opts into them — the Avalara/Anrok tax providers). Air-gapped installs use the fixed_rate tax provider, which runs fully in-cluster with zero egress.
No tier-gating of API surface. Cloud and Self-Managed expose the same /v1/* and /cp/* endpoints; the differences are operational, not product.
No multi-tenant data on Managed clusters. Single-tenant by definition.

Cross-references

README — Architecture
README — Local development on macOS
Helm chart values
docs/operator-runbook.md — Managed-tier SRE operating procedures
docs/compliance/soc2-evidence-map.md
docs/compliance/audit-trail-architecture.md
src/web/data/tiers.json — single source of truth for the customer-facing tier descriptions