Skip to main content

​
Overview

Onyx can be deployed on any cloud provider that supports:
  • Docker Compose — any Linux VM with Docker installed (see Docker Compose)
  • Kubernetes — any managed Kubernetes service (see Kubernetes)
  • Terraform — AWS is fully supported via the modules in deployment/terraform/modules/aws/
The Terraform modules in the repository target AWS exclusively. For Azure and GCP, use the Helm chart on AKS or GKE and manage the underlying cloud resources (databases, object storage, caches) with your preferred tooling.

​
AWS

AWS is the most thoroughly supported cloud target. The repository ships Terraform modules that provision a production-ready stack end-to-end.

EKS (recommended)

Deploy Onyx on Amazon EKS using the Helm chart. The Terraform eks module provisions the cluster, node groups, EBS CSI driver, metrics server, and cluster autoscaler.

Terraform quickstart

Use the onyx Terraform module to provision a complete AWS stack (VPC, EKS, RDS, ElastiCache, S3, optional OpenSearch) with a single terraform apply.

​
AWS module summary

The deployment/terraform/modules/aws/ directory contains:
ModuleWhat it creates
onyxTop-level composition — wires all modules below together
vpcVPC with public/private subnets and S3 gateway endpoint
eksEKS cluster, managed node groups, addons, optional IRSA
postgresRDS for PostgreSQL; returns a connection URL
redisElastiCache for Redis with optional auth token
s3S3 bucket locked to the VPC endpoint
opensearchAmazon OpenSearch domain (opt-in)
wafAWS WAF with rate limiting and CloudWatch logging

​
ECS / Fargate

An ECS Fargate configuration exists in the repository. It targets teams that prefer a serverless container runtime over Kubernetes.
The ECS/Fargate configuration does not have a corresponding Terraform module in the current repository structure. Use it as a reference when defining your own ECS task definitions and services.

​
Managed services on AWS

When running on AWS, prefer managed services over the in-cluster alternatives bundled with the Helm chart:
Onyx componentRecommended AWS serviceNotes
PostgreSQL (relational_db)Amazon RDS for PostgreSQLDisable postgresql.enabled in Helm values; supply POSTGRES_HOST via configMap
Redis (cache)Amazon ElastiCache for RedisDisable redis.enabled; supply REDIS_HOST
File store (minio)Amazon S3Disable minio.enabled; configure IRSA or static credentials
OpenSearch (opensearch)Amazon OpenSearch ServiceDisable opensearch.enabled; supply OPENSEARCH_HOST

​
Azure

Onyx runs on Azure Kubernetes Service (AKS). There are no Azure-specific Terraform modules in the repository; provision your cluster and managed services with the Azure CLI, Bicep, or your own Terraform configuration, then install Onyx using the Helm chart.
Onyx componentRecommended Azure service
PostgreSQLAzure Database for PostgreSQL – Flexible Server
RedisAzure Cache for Redis
File storeAzure Blob Storage (configure an S3-compatible endpoint or use the postgres file store backend)
KubernetesAzure Kubernetes Service (AKS)

​
AKS deployment steps

1

Provision an AKS cluster

az aks create \
  --resource-group my-rg \
  --name onyx-aks \
  --node-count 3 \
  --node-vm-size Standard_D8s_v3 \
  --enable-addons monitoring \
  --generate-ssh-keys
2

Get credentials

az aks get-credentials --resource-group my-rg --name onyx-aks
3

Install Onyx via Helm

Follow the Kubernetes deployment guide. Disable the in-cluster databases and point Onyx at your Azure managed services via configMap in values.yaml:
configMap:
  POSTGRES_HOST: "my-server.postgres.database.azure.com"
  REDIS_HOST: "my-cache.redis.cache.windows.net"

postgresql:
  enabled: false

redis:
  enabled: false

minio:
  enabled: false

​
GCP

Onyx runs on Google Kubernetes Engine (GKE). There are no GCP-specific Terraform modules in the repository; use the Helm chart after provisioning your cluster and managed services.
Onyx componentRecommended GCP service
PostgreSQLCloud SQL for PostgreSQL
RedisMemorystore for Redis
File storeCloud Storage (via S3-compatible interoperability endpoint or postgres backend)
KubernetesGoogle Kubernetes Engine (GKE)

​
GKE deployment steps

1

Create a GKE cluster

gcloud container clusters create onyx-gke \
  --zone us-central1-a \
  --num-nodes 3 \
  --machine-type n2-standard-8
2

Get credentials

gcloud container clusters get-credentials onyx-gke --zone us-central1-a
3

Install Onyx via Helm

Follow the Kubernetes deployment guide. Disable the in-cluster databases and reference your Cloud SQL and Memorystore endpoints:
configMap:
  POSTGRES_HOST: "10.x.x.x"          # Cloud SQL private IP
  REDIS_HOST: "10.x.x.x"             # Memorystore IP

postgresql:
  enabled: false

redis:
  enabled: false

minio:
  enabled: false

​
General guidance for all cloud providers

​
Use managed databases

Running PostgreSQL and Redis as in-cluster containers (the default Helm chart behaviour) is convenient for getting started but not recommended for production. Managed services provide automated backups, high availability, and simplified operations.
In-cluster serviceManaged replacement
relational_db (postgres:15.2-alpine)RDS, Cloud SQL, Azure Database for PostgreSQL
cache (redis:7.4-alpine)ElastiCache, Memorystore, Azure Cache for Redis
minio (S3-compatible)S3, Cloud Storage, Azure Blob Storage
To switch Onyx to an external database, disable the subchart and set the host in configMap: 
postgresql:
  enabled: false

configMap:
  POSTGRES_HOST: "your-managed-db-host"
  POSTGRES_USER: "onyx"
  POSTGRES_PASSWORD: "..."       # or use auth.postgresql.existingSecret

​
Object storage for file store

Onyx supports two file store backends:
  • s3 (default) — S3-compatible storage. Works with AWS S3, GCS interoperability endpoint, Azure Blob via compatible gateway, or the in-cluster MinIO.
  • postgres — stores files in PostgreSQL. No extra service required; suitable for lite deployments or when object storage is unavailable.
configMap:
  FILE_STORE_BACKEND: "s3"
  S3_ENDPOINT_URL: "https://storage.googleapis.com"   # GCS example
  S3_FILE_STORE_BUCKET_NAME: "onyx-files"

​
Persistent storage (Kubernetes)

Ensure your cluster has a default StorageClass that provisions ReadWriteOnce volumes. On each cloud provider:
ProviderRecommended StorageClass
AWS EKSgp3 (provisioned by EBS CSI driver)
AKSmanaged-premium or managed-csi
GKEstandard-rwo (provisioned by GCE CSI driver)
Set storageClassName on the Vespa, OpenSearch, MinIO, and PostgreSQL sections of values.yaml. See Kubernetes for the full PVC reference.

​
Next steps

Docker Compose

Deploy on a single VM with Docker Compose — the fastest path to a running instance.

Kubernetes

Full Helm chart reference for Kubernetes deployments on any cluster.

Terraform (AWS)

Provision a complete AWS stack with the official Terraform modules.

Build docs developers (and LLMs) love

Get started for freeTalk to us