Deployment Guide

Install Bud-Stack from the OCI Helm chart against managed (external) databases and object storage

This guide installs Bud-Stack from the published OCI Helm chart and points it at managed services you already operate (e.g. Azure Database for PostgreSQL, Cosmos DB for MongoDB, Azure Cache for Redis, Azure Blob via an S3-compatible gateway, an external Kafka and ClickHouse). It lists only the configuration that is mandatory for a new setup — defaults are fine for everything else.

If you want an all-in-one cluster with bundled Postgres/Mongo/Redis/MinIO, follow the Installation Guide instead.

Prerequisites

Requirement	Notes
Kubernetes 1.25+	With a default StorageClass for PVCs
kubectl, helm 3.8+	Helm must support OCI registries
Dapr 1.16+ installed cluster-wide	Service mesh used by every backend pod
Traefik ingress controller	Chart Ingresses are pinned to ingressClassName: traefik.
TLS strategy	ingress.https: disabled (plain HTTP), internal (Traefik/cert-manager in-cluster certs), or external (terminated upstream by a LB/WAF).
OIDC identity provider	Any OIDC-compliant IdP works (Keycloak, Auth0, Okta, Azure AD, Google, etc.). Authorization is owned by budapp’s Postgres-backed PDP — the IdP only needs to issue ID tokens. The sibling chart at infra/helm/keycloak/ is a convenient default if you don’t already run one.
Registry credentials	Robot account for registry.bud.studio (request from [e-mail])

Step 0 — Log in to the chart registry

helm registry login registry.bud.studio -u 'robot$yourname'
# password prompt

Quote the username so the shell does not expand the $.

Step 1 — Pull the default values

helm show values oci://registry.bud.studio/charts/bud --version 0.12.0 > values.yaml

Step 2 — Start your secrets file

Use the example.secrets.yaml shipped with the chart as the template. Every secret has its generation command in a comment above it.

helm pull oci://registry.bud.studio/charts/bud --version 0.12.0 --untar
cp bud/example.secrets.yaml secrets.yaml

Step 3 — Wire up external services

All managed services are configured under externalServices in values.yaml and the matching credential blocks live in secrets.yaml. Provision the resources below first, then fill in the values.

PostgreSQL

Create one database per backend service, each with its own user.

Configure in values.yaml	Configure in secrets.yaml
externalServices.postgresql.host	externalServices.postgresql.databases.<svc>.password
externalServices.postgresql.port	(one entry per service)
externalServices.postgresql.databases.<svc>.name
externalServices.postgresql.databases.<svc>.username

Required databases: budapp, budcluster, budmetrics, budmodel, budsim, budeval, buddoc, budprompt, budask, mcpgateway, budpipeline, budcodeinterpreter.

MongoDB (Novu)

Configure in values.yaml	Configure in secrets.yaml
externalServices.mongodb.endpoint	externalServices.mongodb.auth.password
externalServices.mongodb.databases.novu	novu.externalDatabase.password
novu.externalDatabase.host
novu.externalDatabase.database
novu.externalDatabase.username

Redis / Valkey

A single Redis instance, multiplexed by logical DB index.

Configure in values.yaml	Configure in secrets.yaml
externalServices.valkey.host	externalServices.valkey.password
externalServices.valkey.port
externalServices.valkey.databases.* (numeric index per consumer)
novu.externalRedis.host

The novu.externalRedis block references the same instance; only the host is restated — the password is shared from externalServices.valkey.password via the <release>-novu-externalredis Secret.

S3-compatible object storage

Works with Azure Blob via an S3 gateway, MinIO, SeaweedFS, or AWS S3. Create the buckets ahead of time.

Configure in values.yaml	Configure in secrets.yaml
externalServices.s3.endpoint	externalServices.s3.auth.accessKey
externalServices.s3.secure (true for HTTPS)	externalServices.s3.auth.secretKey
externalServices.s3.buckets.modelRegistry
externalServices.s3.buckets.modelInfo
externalServices.s3.buckets.novu
novu.externalS3.bucketName

ClickHouse

Configure in values.yaml	Configure in secrets.yaml
externalServices.clickhouse.host	externalServices.clickhouse.auth.password
externalServices.clickhouse.port
externalServices.clickhouse.databases.budmetrics (must stay metrics — hardcoded)
externalServices.clickhouse.databases.budeval
externalServices.clickhouse.databases.budgateway
	externalServices.clickhouse.auth.username

Kafka

Configure in values.yaml	Configure in secrets.yaml
externalServices.kafka.endpoint	externalServices.kafka.auth.password
externalServices.kafka.topics.pubsub
externalServices.kafka.topics.budgateway
	externalServices.kafka.auth.username

OIDC identity provider

Any OIDC-compliant IdP is supported — budapp validates ID tokens via OIDC discovery and stores all authorization state in its own Postgres PDP. If you don’t already operate one, the sibling chart at infra/helm/keycloak/ gives you a working Keycloak in one install.

You must pre-create the OAuth clients that the redirect-flow uses (budadmin-web, budcustomer-web, budplayground-web, plus the mcpgateway client) in your IdP and copy the client secrets into secrets.yaml (see Application secrets).

Configure in values.yaml	Configure in secrets.yaml
externalServices.keycloak.url (issuer base URL, no trailing slash)	externalServices.keycloak.clients.mcpgateway.secret
externalServices.keycloak.clients.mcpgateway.realm (or equivalent tenant identifier)
externalServices.keycloak.clients.mcpgateway.id

The externalServices.keycloak.* keys are named after the historical Keycloak default but accept any OIDC issuer URL — rename in your head as externalServices.oidc.*. The legacy keycloak.auth.adminUser / adminPassword fields are only consulted when you run the bundled Keycloak chart.

Step 4 — Application secrets & cluster config

These are not wired to external services but are required for a new install. All paths below live in secrets.yaml unless noted.

Registry pull credentials

registries:
  registry.bud.studio:
    username: robot$yourname
    password: <token>

Per-service secrets you must change

Path	Why
microservices.global.env.SUPER_USER_EMAIL	First admin login
microservices.global.env.SUPER_USER_PASSWORD	First admin login
microservices.budapp.env.AES_KEY_HEX	Encrypts stored credentials
microservices.global.env.PASSWORD_SALT	Password hashing salt
microservices.budapp.redirectFlow.sessionSecret	64-byte HMAC for the BFF session cookie
microservices.budapp.redirectFlow.defaultClientSecret	Must match the Keycloak client budadmin-web
microservices.budapp.redirectFlow.clientsByHost.*.clientSecret	One per frontend host (budadmin, budcustomer, budplayground) — all must exist as confidential clients in the realm
microservices.budnotify.env.STORE_ENCRYPTION_KEY, JWT_SECRET	Novu wrapper auth
microservices.mcpgateway.env.*	MCP gateway admin + JWT + auth-encryption secrets
microservices.rsaKeys.privateKey / publicKey / privateKeyPassword	Inter-service RSA pair (regen with openssl genrsa -aes256 -out private_key.pem 2048)
daprExtra.crypto.symmetricKey / asymmetricKey	Dapr crypto-component keys for cluster credential encryption
novu.store.encryption-key, novuExtra.password	Novu admin

Cluster-level config in values.yaml

Path	Purpose
global.ingress.hosts.root	Base public hostname (e.g. bud.yourdomain.com). All sub-hosts derive from this.
ingress.https	external (cert-manager / cloud LB), internal (in-cluster CA), or disabled
storage.budmodelRegistry.className	StorageClass for the model registry PVC (e.g. managed-csi on Azure)
storage.budmodelRegistry.size	Size the registry PVC for the models you plan to host

Step 5 — Install

helm install bud oci://registry.bud.studio/charts/bud \
  --version 0.12.0 \
  --namespace bud --create-namespace \
  -f values.yaml \
  -f secrets.yaml

Step 6 — Verify

kubectl -n bud get pods
kubectl -n bud get ingress

All pods should reach Running within ~5–10 minutes. Backend pods run a Dapr sidecar so expect 2/2 READY for most of them.

Common pitfalls

• budmetrics database name must be metrics;
• Redirect-flow clients must exist in the realm before the budapp pod boots, otherwise the login flow returns invalid_client.
• registries.registry.bud.studio credentials are required even for airgapped clusters that already mirrored the images — the chart still creates the imagePullSecret referenced by every Deployment.

Next steps

Helm Configuration Reference

Full list of values and overrides.

Architecture

How the services fit together.