_Docs/
Get StartedModulesPlatformDeployCookbookChangelogReference
_Deploy
  • Deployment Overview
    • Overview
    • Requirements
    • Demo
      • All-in-one Demo Chart
    • Installation
      • Operator Setup
      • Control Plane SetupEE
    • Infrastructure Services
      • PostgreSQL
      • Message Broker
      • Temporal
    • Module Configuration
      • Stack Configuration
      • Gateway Module
      • Ledger Module
      • Payments Module
      • Auth ModuleEE
      • Orchestration ModuleEE
      • Reconciliation ModuleEE
      • Wallets ModuleEE
      • Webhooks ModuleEE
    • Configuration Reference
      • Operator settings reference
      • API Reference
    • Backups management
    • Troubleshooting
    • Configure OpenTelemetry
    • Traces
    • Metrics
    • Upgrade from the operator
    • Database update
  1. Deploy
  3. Self-Hosted
  5. Installation
  7. Operator Setup
Deploy

Operator Setup

This page requires self-hosted edition.
Deployment

This guide walks you through installing Formance on your Kubernetes cluster using the unified Formance Helm chart.

Enterprise Edition requires a valid license. Contact sales@formance.com to obtain one.

Prerequisites#

Before you begin, ensure you have:

  • Kubernetes 1.30+ cluster
  • Helm 3.x installed
  • kubectl configured to access your cluster
  • An Ingress Controller (nginx, traefik, etc.)
  • SSL certificates for your domain
  • Enterprise Edition license (Cluster ID and License Token)

For detailed requirements, see the Requirements page.

Quick Start#

Set Environment Variables#

Bash
export CLUSTER_ID=$(kubectl get ns kube-system -o jsonpath='\{.metadata.uid\}')
export LICENCE_TOKEN="your-licence-token"
export BASE_DOMAIN="formance.example.com"

Install#

Bash
helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.10.0 \
  --namespace formance-system \
  --create-namespace \
  --set tags.EntrepriseEdition=true \
  --set global.licence.clusterID=$CLUSTER_ID \
  --set global.licence.token=$LICENCE_TOKEN \
  --set global.serviceHost=$BASE_DOMAIN

Configure Service Hosts#

Enterprise Edition requires service hosts for the control plane components:

ComponentValue Key
Globalglobal.serviceHost
Membershipmembership.serviceHost
Dex (OIDC)dex.serviceHost
Portalportal.serviceHost
Console V3console.serviceHost

Using Minimal Profile#

For a minimal Enterprise installation:

Bash
helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.10.0 \
  --namespace formance-system \
  --create-namespace \
  --set tags.EntrepriseEdition=true \
  --set global.licence.clusterID=$CLUSTER_ID \
  --set global.licence.token=$LICENCE_TOKEN \
  -f https://raw.githubusercontent.com/formancehq/helm/main/charts/formance/profiles/ee-minimal.yaml

Custom Configuration#

Using a Values File#

For a production deployment with a custom domain and TLS:

Bash
export CLUSTER_ID=$(kubectl get ns kube-system -o jsonpath='\{.metadata.uid\}')
export LICENCE_TOKEN="your-licence-token"
export BASE_DOMAIN="formance.example.com"

helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.10.0 \
  --namespace formance-system \
  --create-namespace \
  --set tags.EntrepriseEdition=true \
  --set global.licence.clusterID=$CLUSTER_ID \
  --set global.licence.token=$LICENCE_TOKEN \
  --set global.serviceHost=$BASE_DOMAIN

View All Configuration Options#

Bash
helm show values oci://ghcr.io/formancehq/helm/formance --version 1.10.0

Verify Installation#

Check that all components are running:

Bash
kubectl get pods -n formance-system

You should see:

NAME                                    READY   STATUS    RESTARTS   AGE
formance-operator-xxxxx-xxxxx           1/1     Running   0          2m
membership-xxxxx-xxxxx                  1/1     Running   0          2m
console-v3-xxxxx-xxxxx                  1/1     Running   0          2m
membership-dex-xxxxx-xxxxx              1/1     Running   0          2m
postgresql-0                            1/1     Running   0          2m

License Validation#

The chart enforces license validation when tags.EntrepriseEdition is true:

  • Installation will fail if global.licence.clusterID is missing
  • Installation will fail if global.licence.token is missing

Get your Cluster ID with: kubectl get ns kube-system -o jsonpath='\{.metadata.uid\}'

Next Steps#

After installing the operator:

  1. Configure your Infrastructure Services (PostgreSQL, Message Broker)
  2. Deploy your first Stack
  3. Enable the modules you need
  1. Configure the Control Plane — Set up Dex, create organizations, and configure SSO
All-in-one Demo ChartControl Plane Setup
On This Page
  • Prerequisites
  • Quick Start
  • Set Environment Variables
  • Install
  • Configure Service Hosts
  • Using Minimal Profile
  • Custom Configuration
  • Using a Values File
  • View All Configuration Options
  • Verify Installation
  • License Validation
  • Next Steps