Skip to content
AnvilBase

Kubernetes (Helm) — Experimental

⚠️ Experimental (Labs) — untested, not for production. This chart has only helm lint/helm template syntax validation in CI — it has never been deployed or tested on a real Kubernetes cluster, and Ingress/TLS and the Supavisor pooler are not fully templated. Use Docker Compose for production and scale it per Scaling. The chart is provided for experimentation and contribution.

A Helm chart ships in helm/anvilbase, mirroring the Compose services. It targets horizontal scale, rolling upgrades, and HA — but those paths are not yet tested.

Install

Terminal window
helm install anvilbase ./helm/anvilbase \
  --set secrets.create=true \
  --set secrets.postgresPassword=<password> \
  --set secrets.controlPlaneSecret=<secret> \
  -f custom-values.yaml

All options are in helm/anvilbase/values.yaml. Pin the version with anvilbaseVersion in your values rather than tracking a floating tag.

Secrets

Provide credentials either by letting the chart create a Secret (secrets.create=true + values) or by referencing an existing Secret you manage (e.g. via External Secrets Operator / Vault). Never commit secret values to your values file in version control. The set mirrors the environment variables:

  • postgresPassword, anvilbaseDbPassword
  • controlPlaneSecret, authSecret, secretKeyBase
  • minioRootPassword, valkeyPassword, minioKmsSecretKey

Postgres image

The chart’s postgres.image is AnvilBase’s own Postgres image (ghcr.io/paxtone-studio/anvilbase-postgres, FROM postgres:15-bookworm — no third-party Postgres base), defaulting to global.anvilbaseVersion.

If you are upgrading a deployment whose PersistentVolume was created by a pre-1.1 (supabase-based) release, run the one-time migration before it boots on this image — see Upgrades → Postgres image. New deployments need no action.

High availability

ComponentHA approach
Control planerun multiple replicas behind a Service — requires reachable Valkey for shared rate limiting (see Scaling)
Realtimemulti-node Phoenix cluster (BEAM distribution)
Postgresstreaming replication / Patroni for failover (operator-provided)
Valkeya clustered/replicated Valkey or managed equivalent
MinIOdistributed MinIO, or a managed S3-compatible store

When running >1 control-plane replica, set a Kubernetes readinessProbe against /health and consider ANVILBASE_RATE_LIMIT_REQUIRE_VALKEY=true so a replica that can’t reach Valkey refuses traffic instead of rate-limiting per-process.

Ingress & TLS

Front the deployment with your ingress controller (or Traefik) terminating TLS via cert-manager/Let’s Encrypt. Expose only the gateway; keep Postgres, Valkey, MinIO, realtime, and Deno on the cluster network. Apply NetworkPolicies to constrain east-west traffic and edge-function egress (Network Security).

Upgrades & rollback

Terminal window
helm repo update
helm diff upgrade anvilbase ./helm/anvilbase -f custom-values.yaml   # preview
helm upgrade anvilbase ./helm/anvilbase -f custom-values.yaml        # pre-upgrade hook backs up first


kubectl rollout status deployment/anvilbase-control-plane
kubectl get pods -l app.kubernetes.io/part-of=anvilbase


# rollback if needed (also triggers an AnvilBase-side rollback)
helm rollback anvilbase

The chart’s pre-upgrade hook snapshots before applying. See Upgrades for the full version-bump procedure and Disaster Recovery for failure scenarios.

Scaling

  • Control plane: scale replicas horizontally (Valkey required). Watch the Postgres connection ceiling — replicas × active_projects × pool_max < max_connections.
  • Realtime: scale for WebSocket fan-out; the BEAM handles huge connection counts per node.
  • Postgres: scale vertically and add read replicas; consider Supavisor pooling.

Details and the alerting keys to watch are in Scaling.

Health & monitoring

Wire probes and dashboards to /health and /health/services, and scrape logs (structured JSON). See Monitoring.

Next: Configuration.