Docs/Deployment

Deployment Guide

VegaDūta is self-hosted. Every release publishes signed multi-arch images and OCI Helm charts to GHCR; you deploy them with Docker Compose (Lite or Full tier) or Helm on Kubernetes. This repository has no hosted-deploy pipeline: nothing here deploys for you. Every rule below exists because breaking it has caused an outage somewhere.

Non-negotiable rules — read before you touch anything

Do not power-cycle a stack people depend on to "fix" a hang. A hard host reset is a power-yank of the tenant database, and it destroys the evidence. Collect logs, container states and memory first. docker compose down -v (or scripts/vegaduta down --volumes) deletes data.
Pin versions. Set VEGADUTA_VERSION (Compose) or the chart version (Helm) to a released version; latest follows the newest release and a re-run can change what you run.
Verify what you pulled. Images are signed with cosign (keyless) and carry SPDX SBOM and SLSA provenance attestations; see CI/CD Pipelines for the verify commands.
Core deploys first. Core owns the Flyway migrations. Order is: dependencies → core → verify healthy → then the frontends that call it.
No localhost in a browser-facing URL on a server. A PUBLIC_* value that points at localhost sends other users' browsers to their own machines and breaks sign-in. scripts/vegaduta doctor checks this. Source builds (--build) of web must be rebuilt after a domain change so their fallback URLs change too.
APP_ENCRYPTION_KEY must be identical everywhere core boots. A different key makes every stored credential permanently undecryptable. Back up deploy/compose/.env together with the data.

The deployment options

Lite — Docker Compose supported

5 containers (postgres, valkey, keycloak in dev mode, core, web); the rag profile adds the sidecar. About 6 GB of Docker memory. scripts/vegaduta up --lite (or make up-lite). Config: deploy/compose/lite.yml.

Full — Docker Compose supported

Adds web-admin, PgBouncer, SeaweedFS (S3), a Keycloak database, the sidecar and opt-in profiles (events, temporal, jobs, observability, tracing, voice, rl, code-intel, builder, sandbox). scripts/vegaduta up --full [--profile …] (or make up). Config: deploy/compose/docker-compose.yml + deploy/compose/.env. Compose stack →

Kubernetes (Helm) preview

Umbrella chart vegaduta from oci://ghcr.io/cd-lc/charts; each component is also its own chart. The charts lint, render and validate in CI, but per deploy/helm/README.md they have not yet been run end to end against published images. Dependencies are bundled or your own (PostgreSQL, Valkey/Redis, S3, an OIDC issuer).

Local dev dev

Direct processes (mvn spring-boot:run, npm run dev, uvicorn) against the compose infra subset. Local development →

The deploy model, in five steps (Compose)

#	Step	Command shape	Verify
1	Generate secrets and start the stack	`scripts/vegaduta up --full` (adds `--domain <your-domain>` on a server)	every service reports healthy
2	Check the environment	`scripts/vegaduta doctor`, `scripts/vegaduta status`	no localhost in public URLs; ports and disk fine
3	Upgrade to a release	`scripts/vegaduta upgrade --version X.Y.Z` (backs up `.env`, pulls, recreates, waits for health)	services healthy; Flyway migrations applied at core start
4	Health-sweep the public endpoints	`curl` `api/actuator/health`, `app`, `admin`, `auth/.well-known`	all 200
5	Keep the previous version and a backup until verified	rollback = re-run with the previous `VEGADUTA_VERSION` (migrations are forward-only; restore the database backup if a migration must be undone)	previous version and backup recorded before you started

On Kubernetes the equivalent is helm upgrade with a pinned chart version. Rollback detail: Rollback & Recovery.

"I want to…" — decision table

I want to…	Go to
Install or upgrade	`deploy/README.md`, `deploy/helm/README.md`, `docs/installation.md`
Roll a deploy back	Rollback & Recovery
Understand what runs where	Service Topology, Ports & Service Matrix
Know what CI and releases do	CI/CD Pipelines
Operate the Compose stack	Compose stack
Run the platform on my machine	Local Development Setup
Add/change a public hostname or TLS	Compose stack §Domain overlay (Helm: your Ingress values)
Fix Keycloak — realm, clients, SMTP, social login	Keycloak Provisioning
Migrate a database schema	Rollback & Recovery (Flyway is forward-only; versions share one namespace across controlplane and tenant dirs)
Rotate a secret	Secrets & Key Management

"Released" is not "running"

Nothing deploys automatically. Never assume the code you are reading is the code that is running: check the running image version (scripts/vegaduta status, docker compose ps, or kubectl get pods -o wide) against the release tag.