Enterprise Deployment
This page is the deployment overview for self-hosted Enterprise builds. Several runbook-level sections (backup/restore, upgrade procedures, observability setup) are marked In progress and will be filled in as the operational story matures.
The Enterprise build is the same product as the managed SaaS, packaged for self-hosted deployment. It runs single-tenant against your own infrastructure and your own identity provider, with a signed license replacing the SaaS billing path.
Required components
A working deployment needs four things alongside the platform itself:
| Component | Notes |
|---|---|
| PostgreSQL 15 or newer | Application database. Stores definitions, instances, history, project membership, and so on |
| Temporal server | Durable workflow substrate the BPMN engine runs on |
| An OIDC identity provider | Any spec-compliant provider — Keycloak, Okta, Auth0, Azure AD, Zitadel, others |
| A signed license JWT | Issued by the platform vendor; presented at startup. See License management |
The platform itself ships as a backend service plus a web UI image.
Architecture
┌─────────────────────────────┐
│ Web UI image │
│ (served behind your proxy) │
└────────────────┬────────────┘
│ HTTPS
▼
┌─────────────────────────────────────────────────────────┐
│ QuantumBPM backend (Enterprise build) │
│ • OIDC token validation │
│ • Project RBAC from token claims │
│ • License validation at startup + daily │
└──────────┬────────────────┬─────────────────────────────┘
│ │
▼ ▼
┌────────────┐ ┌──────────────┐ ┌─────────────────┐
│ PostgreSQL │ │ Temporal │ │ OIDC provider │
│ │ │ │ ◄─── │ (your IdP) │
└────────────┘ └──────────────┘ └─────────────────┘
The backend is stateless — all durable state is in PostgreSQL and Temporal. Scale horizontally by running multiple backend replicas behind a load balancer.
OIDC integration
The Enterprise build doesn't run its own identity store. It validates inbound tokens against your IdP's discovery document and reads identity, organisation roles, and project memberships from the token claims you configure.
What the platform reads
| Claim | Default path | Purpose |
|---|---|---|
Subject (sub) | Standard OIDC | The user identifier |
| Roles | Configurable (default: roles) | Organisation-level roles (user, admin, system-admin). Drives platform-wide permissions |
| Projects | Configurable (default: projects) | Per-project memberships and roles. Shape: [{id, roles[]}] |
The roles and projects claim paths are configurable, so the platform integrates with providers whose claim shapes don't match the defaults out of the box. Examples that the configuration covers:
| Provider | Roles claim path |
|---|---|
| Keycloak | realm_access.roles (dotted nested path) |
| Azure AD | A custom extension claim |
| Auth0 | A namespaced custom claim |
| Zitadel | A flat top-level array |
Stringified-JSON claim values are also supported for providers that ship arrays as JSON-encoded strings.
Project membership shape
The projects claim carries one entry per project the caller has access to:
{
"projects": [
{ "id": "proj-finance", "roles": ["editor"] },
{ "id": "proj-ops", "roles": ["viewer"] }
]
}
A special wildcard — id: "*" with admin — grants cross-project admin (used backend-side for operator tooling). For end-user identities, list each project explicitly.
For the role hierarchy and what each role permits, see Authentication → The role model.
What you configure operator-side
At deployment time you point the platform at your IdP's issuer URL and set the claim paths the platform should read. Specific environment variable names and configuration file shapes are covered in In progress below — the conceptual contract is what's documented here.
License management
Enterprise deployments require a signed license JWT, presented to the platform at startup.
| When | What happens |
|---|---|
| Startup | The license signature is verified. An invalid or expired license prevents the backend from starting |
| Daily | The license is re-validated. An expired license at this check causes the backend to exit |
| Two months before expiry | Warning logs are emitted so you can renew without an outage |
Renewing means swapping in a new license JWT and restarting the backend. The license itself doesn't carry application data — it's purely a vendor-issued attestation of entitlement.
Contact your platform vendor for license issuance and renewal.
Provisioning users and projects
Enterprise builds can pre-provision users and projects from a YAML file read at startup. This is useful for:
- Bootstrapping a fresh deployment with the initial admin and a baseline project structure.
- Running deployments where project membership isn't carried in OIDC tokens (less common, but supported).
- Reproducing identical environments across staging / production.
The YAML format and exact configuration mechanism are covered in In progress below.
Deployment options
The platform images can run anywhere a container runtime can:
| Option | Notes |
|---|---|
| Docker Compose | The simplest fit for single-host deployments and evaluation. Compose files for the full stack (backend, web, Postgres, Temporal) ship in the deployment bundle |
| Kubernetes | Standard deployment for production environments. Works with any conformant cluster |
| Bare VMs / process supervision | The backend is a single binary; nothing prevents running it directly under systemd or similar |
Differences from SaaS
| Area | SaaS | Enterprise |
|---|---|---|
| Identity | Zitadel (managed) | Bring your own OIDC provider |
| Tenancy | Multi-tenant | Single-tenant |
| Billing | Paddle integration, plan limits, credit accounting | None — replaced by license |
| RBAC source | Zitadel + database | OIDC token claims |
| Bootstrapping | Auth Console UI | YAML provisioning at startup |
| User management | Platform Console + Auth Console | Your IdP |
| License gating | None | Required signed license |
For end users — anyone modeling, deploying, running instances, or building integrations — the contract is identical. Same UI, same APIs, same SDKs, same modeler.
In progress
The following sections are tracked but not yet written. Reach out to support if you need any of these for an active deployment:
- Configuration reference — concrete environment variables and configuration file shape for the OIDC issuer, claim paths, license path, database connection, Temporal client, and provisioning YAML location.
- Backup and restore — what to back up (PostgreSQL, license, configuration), how to restore.
- Upgrade procedures — version-to-version upgrade paths, schema migrations, rollback strategy.
- Observability — OpenTelemetry traces and metrics, healthchecks, log shape, dashboards.
- High availability and scaling — replica counts, load-balancing notes, Temporal sizing guidance.
- Hardening — recommended TLS, ingress, network-policy, and secret-management posture.
If you're standing up an Enterprise deployment today, the canonical operational source is the deployment bundle that ships with your license — the documentation here will catch up to it incrementally.