How do I run RevenueDot with high availability?

Run two or more replicas of the same RevenueDot image behind a load balancer, on one managed Postgres with a standby (Amazon RDS Multi-AZ, Cloud SQL with high availability, or Aurora). Every replica serves the SDK API, the REST API, store notifications and the dashboard, and they share all state through Postgres, so any replica can answer any request. Losing a replica, a node or a whole availability zone does not stop purchases, and upgrades replace one replica at a time.

The server repository has three reference setups, all checked in CI and none applied for you:

There is no published image yet. Build it from the repository's Dockerfile and push it to your registry (docker build -t <registry>/revenuedot:<tag> .), then point the chart's image.repository or Terraform's image at it.

What keeps replicas from stepping on each other#

Webhooks are delivered at least once, as with RevenueCat: a replica killed after your endpoint answered but before the result was saved sends that delivery again 2 minutes later. Deduplicate on event.id (Webhooks).

Settings for several replicas#

Everything else is the same as a single server (Self-hosting).

Health checks and shutdown#

• GET /healthz is liveness: 200 while the process runs. It never asks the database, so a database failover does not restart every replica.
• GET /readyz is readiness: 200 when the database answers within 2 seconds and the replica is not shutting down, 503 otherwise. Point Kubernetes' readiness probe here. On ECS, where a failed load balancer check also replaces the task, the AWS setup checks /healthz instead, so a slow database does not restart every task; ECS takes a task out of the load balancer before it sends SIGTERM.
• On SIGTERM (Kubernetes, ECS, docker stop), a replica turns /readyz to 503, stops its background job, waits REVENUEDOT_SHUTDOWN_DELAY_MS, closes its port, finishes requests in flight and any running background job, then exits 0. A background job that is running stops after the webhooks in flight; the rest waits for the next run on another replica. Keep the delay plus the timeout under your platform's grace period (30 seconds on Kubernetes and in the AWS setup; Cloud Run allows 10, so the Google Cloud setup uses 0 and 8).

Kubernetes with Helm#

Create a Secret with the database URL and one with the server's secrets, then install the chart from a checkout of the server repository:

kubectl create namespace revenuedot
kubectl -n revenuedot create secret generic revenuedot-db \
  --from-literal=DATABASE_URL='postgres://revenuedot:<password>@<host>:5432/revenuedot?sslmode=require'
kubectl -n revenuedot create secret generic revenuedot-secrets \
  --from-literal=REVENUEDOT_ENCRYPTION_KEY="$(openssl rand -base64 32)" \
  --from-literal=REVENUEDOT_SMTP_URL='smtps://<user>:<password>@smtp.example.com:465'
helm install revenuedot deploy/helm/revenuedot -n revenuedot \
  --set image.repository=<registry>/revenuedot --set image.tag=<tag> \
  --set publicUrl=https://revenuedot.example.com \
  --set database.existingSecret=revenuedot-db --set secrets.existingSecret=revenuedot-secrets \
  --set ingress.enabled=true --set ingress.className=nginx \
  --set ingress.hosts[0].host=revenuedot.example.com \
  --set ingress.hosts[0].paths[0].path=/ --set ingress.hosts[0].paths[0].pathType=Prefix
kubectl -n revenuedot rollout status deploy/revenuedot && helm test revenuedot -n revenuedot

What the chart does by default:

• Two to ten replicas, scaled on CPU, spread over zones and nodes, with a PodDisruptionBudget that keeps one up during node drains and maxUnavailable: 0 on rollouts.
• Migrations in a pre-install,pre-upgrade hook Job when database.existingSecret is set (replicas then start with REVENUEDOT_MIGRATE=skip); otherwise each replica migrates on start under the lock. Set migrations.mode to job or startup to choose. Helm waits 5 minutes for the Job by default; pass --timeout 15m when a migration may take longer.
• Probes: startup and liveness on /healthz, readiness on /readyz.
• Security: uid 1000, no privilege escalation, every capability dropped, read-only root filesystem with a small /tmp, no service account token. networkPolicy.enabled=true admits traffic only on the HTTP port.
• Archives in Postgres unless you set archives.s3.bucket (with an access key in your Secret; role credentials such as IRSA are not read yet).

For ingress-nginx, add nginx.ingress.kubernetes.io/proxy-buffering: "off" so RevenueDot AI answers stream. For a quick evaluation without a database, --set postgresql.enabled=true adds one Postgres pod with a volume: no failover and no backups, so never for real purchases. All values are documented in the chart's values.yaml.

AWS with Terraform (ECS on Fargate)#

cd deploy/terraform/aws
cp terraform.tfvars.example terraform.tfvars   # domain_name, route53_zone_id, image, alarm_email
terraform init && terraform plan && terraform apply

It creates a VPC across 3 zones (public, private and database subnets, one NAT gateway per zone), RDS PostgreSQL 16 Multi-AZ (KMS-encrypted, TLS required, 14 days of point-in-time recovery, Performance Insights, deletion protection), the ECS service (2 to 10 tasks at 1 vCPU and 2 GiB, CPU target tracking, a deployment circuit breaker that rolls back), an Application Load Balancer with HTTPS only (TLS 1.2 and 1.3, HTTP redirected) and its ACM certificate validated in Route 53, Secrets Manager entries for the database URL and the encryption key, VPC flow logs, and CloudWatch alarms for 5xx answers, p95 latency, healthy targets, running tasks, database CPU, storage, memory and connections, and failed background job runs, all sent to one SNS topic.

Each task migrates on start by default. To migrate as a separate step, set migrate_on_start = false: tasks then refuse to start on a database missing a migration, so apply a new image in two steps: terraform apply -target=aws_ecs_task_definition.migrate, run the migrate_command output (it waits and fails if the migration failed), then terraform apply. Extra settings go in environment; extra secrets (SMTP URL, signing key, licence key, AI keys) go in secret_arns as Secrets Manager ARNs. Keep the Terraform state in an encrypted backend: it holds the database password and the encryption key.

Google Cloud with Terraform (Cloud Run)#

cd deploy/terraform/gcp
cp terraform.tfvars.example terraform.tfvars   # project_id, region, image, alert_email
terraform init && terraform plan && terraform apply

It creates a VPC and private services access, Cloud SQL for PostgreSQL 16 with regional availability (a standby in a second zone, automatic failover), private IP only, TLS required, backups with point-in-time recovery, Secret Manager entries, the Cloud Run service (2 to 10 instances, CPU always allocated so the background job runs between requests, direct VPC egress), a Cloud Run job for migrations, an uptime check of /readyz from several regions and alert policies for failed checks, 5xx answers, latency, database CPU and disk, and failed background job runs. Set public_url when you map a custom domain; without it the service's run.app address is used.

Postgres#

• Version 16 or later, with a standby in another zone. Every write is in Postgres, so it is the part to make highly available; the replicas are stateless.
• Connections: replicas times DATABASE_POOL_MAX, plus a few for migrations. Ten replicas at 10 is 100.
• Poolers: connect directly, through RDS Proxy, or through PgBouncer in session mode. PgBouncer in transaction mode breaks the advisory locks.
• Failover: RDS and Cloud SQL keep the same address. During the minute or so of a failover, requests that need the database fail with 5xx and /readyz turns 503; the SDKs retry receipts that got a 5xx, and replicas reconnect by themselves.

Upgrades without downtime#

Migrations run before the new version takes traffic, while the old version still serves requests. Releases keep each migration compatible with the version before it (add a column, ship, then remove the old one in a later release); the release notes say when an upgrade needs more. Then the platform replaces replicas one at a time, and each old replica drains before it exits. See Upgrades for backups and rolling back.

How it is tested#

• Unit tests run two background job runs at once and check that each webhook, expiration and alert email happens once.
• A run on a real Postgres starts three replicas at once on an empty database, sends 300 Test Store purchases through a load balancer that health-checks /readyz, stops one replica with SIGTERM in the middle (it exits in about 1.5 seconds) and starts it again, forces 40 expirations and points a second webhook at a failing endpoint. It checks each migration ran once, all 300 purchases succeeded, every one of the 340 events reached the working webhook exactly once, the failing webhook's alert email went out once, and no two background job runs overlapped (scripts/e2e/cluster/run.ts).
• CI lints and renders the chart, validates it against Kubernetes 1.29 to 1.33, validates and lints both Terraform setups, and runs the image the way the chart does: a migration job first, then two non-root replicas on a read-only filesystem, one stopped with SIGTERM.

Related#

• Self-hosting
• Upgrades
• Backups
• Enterprise