Skip to main content

Deployment

Orkestra ships as a Go binary plus a React SPA. Three deployment shapes are documented in this section, in increasing order of operational complexity:

ShapeWhen to useGuide
Single VM, Docker ComposeSolo operator, small team, internal tooling, evaluationSingle VM
VM + Caddy reverse-proxySame as above but with TLS, automatic Let's Encrypt, and the per-audience host split (ADR-0003) wired correctlyReverse-proxy with Caddy
KubernetesMulti-replica, autoscaling, integration with existing K8s toolingKubernetes overview

Orkestra does not ship a Helm chart today — see the Kubernetes overview for the YAML you'd write and the roadmap.

Compose-file inventory​

Regardless of shape, you'll be reading one or more of these compose files. They live in docker/:

FilePurpose
docker-compose.infra.ymlAlways-on infra: MongoDB, Redis, RustFS
docker-compose.dev.ymlSource-build + AIR hot reload — local development
docker-compose.staging.ymlStaging-like behavior + AIR hot reload — long-lived dev VMs
docker-compose.prod.ymlOptimized production stack — pulls a pre-built image from GHCR (ghcr.io/orkestra-cc/orkestra/backend:latest or :<sha>)
docker-compose.observability.ymlOptional: self-hosted Tempo + Prometheus + Loki + Grafana

What lives in .env vs /admin/modules​

Process-scoped infrastructure (Mongo URI, Redis URL, JWT keys, cookies, encryption keys) lives in docker/.env, read by the backend at boot.

Module configuration (OAuth credentials, SMTP, per-module enable flags — plus whatever config keys a fork's addons declare, e.g. payment or API-provider keys) lives in MongoDB (module_configs collection) and is edited at /admin/modules. Secrets are AES-256-GCM-encrypted at rest.

A module's ConfigSchema().EnvVar is consulted only on first-boot seeding — env-var changes after that boot have no effect. The single source of truth is the admin UI. See docker/CLAUDE.md "What belongs in .env / compose vs /admin/modules" for the full bucket split.