Helm Chart

BitVault ships a single Helm chart at deploy/helm/bitvault/ with three values overlays corresponding to the three dependency tiers. The chart is the authoritative Kubernetes packaging for both self-hosted and SaaS deployments.

Dependency Tiers

Tier Dependencies Typical Use Case
lite PostgreSQL + MinIO Self-hosted single-node, local Kubernetes (kind/k3d), CI smoke tests
standard lite + Redis + NATS JetStream Production minimum; unlocks caching, sessions, rate-limiting, transactional outbox, and the full event backbone
full standard + OpenSearch SaaS deployments; unlocks derived full-text search. PostgreSQL FTS remains as fallback if OpenSearch is unavailable.

The chart bundles sub-charts for each dependency as optional condition-gated dependencies. The values.lite.yaml, values.standard.yaml, and values.full.yaml overlays enable the appropriate sub-charts and configure sane defaults for each tier.

Values Structure

Key top-level values and their purpose:

Values Key Type Purpose
image.digest string Primary deployment handle. Set to sha256:<hash>. CI PRs bump this field.
image.repository string OCI registry and repository path
replicaCount integer Baseline replica count (HPA min); overridden per environment
resources.requests / resources.limits object CPU and memory bounds; required, no defaults to prevent unbounded containers
tier enum: lite\|standard\|full Activates the correct sub-chart conditions and feature flag defaults
featureFlags object Per-feature flag overrides (OpenSearch search, advanced sharing, etc.)
externalSecrets.enabled bool Enables ExternalSecret resources; requires external-secrets-operator
externalSecrets.secretStore string SecretStore name (Vault, AWS SSM, etc.)
ingress.host string Public hostname for Ingress/Gateway configuration
autoscaling.enabled bool Enables HPA; KEDA ScaledObjects are always created for workers
podDisruptionBudget.enabled bool Enables PDBs (always true in standard/full)

Installation

Lite Tier (Self-Hosted / Local Kubernetes)

helm install bitvault deploy/helm/bitvault/ \
  --namespace bitvault-prod \
  --create-namespace \
  --values deploy/helm/bitvault/values.lite.yaml \
  --set image.digest=sha256:<digest> \
  --set ingress.host=bitvault.example.com

Standard Tier (Production Minimum)

helm install bitvault deploy/helm/bitvault/ \
  --namespace bitvault-prod \
  --create-namespace \
  --values deploy/helm/bitvault/values.standard.yaml \
  --set image.digest=sha256:<digest> \
  --set ingress.host=bitvault.example.com \
  --set externalSecrets.enabled=true \
  --set externalSecrets.secretStore=vault-bitvault-prod

Full Tier (SaaS)

helm install bitvault deploy/helm/bitvault/ \
  --namespace bitvault-prod \
  --create-namespace \
  --values deploy/helm/bitvault/values.full.yaml \
  --set image.digest=sha256:<digest> \
  --set ingress.host=bitvault.io \
  --set externalSecrets.enabled=true \
  --set externalSecrets.secretStore=vault-bitvault-prod \
  --set autoscaling.enabled=true

Upgrading

helm upgrade bitvault deploy/helm/bitvault/ \
  --namespace bitvault-prod \
  --values deploy/helm/bitvault/values.full.yaml \
  --set image.digest=sha256:<new-digest> \
  --atomic \
  --timeout 10m

--atomic rolls back automatically if the upgrade does not reach Ready within the timeout. In GitOps mode, ArgoCD handles the upgrade lifecycle instead.

GitOps Usage

In GitOps-managed deployments, the Helm chart is not invoked directly by operators. Instead:

  1. The deploy/gitops/ repository (or deploy/ directory, depending on repo layout) contains an ArgoCD Application manifest per environment that references the chart and a per-environment values file.
  2. The per-environment values files (values.prod.yaml, values.staging.yaml, etc.) overlay the tier values and contain the image.digest field.
  3. CI opens a pull request against the GitOps repo bumping image.digest to the newly built, signed digest.
  4. ArgoCD detects the change and renders the chart via its Helm source, applying the diff to the cluster.

No helm upgrade commands run in CI. CI’s job ends when it pushes the image and opens the GitOps PR.

:::tip Self-Host Use the lite tier values with Docker Compose (deploy/compose/docker-compose.lite.yaml) for the simplest self-hosted deployment. No Kubernetes required. The Helm chart is for Kubernetes environments; both compose and helm reference the same OCI image by digest. :::