Skip to main content
Enterprise Edition requires a valid license. Contact sales@formance.com to obtain one.
This guide walks you through installing Formance Enterprise Edition on your Kubernetes cluster.

​
Prerequisites

Before you begin, ensure you have:
  • Kubernetes 1.30+ cluster
  • Helm 3.x installed
  • kubectl configured to access your cluster
  • An Ingress Controller with TLS support
  • SSL certificates for your domain
  • Enterprise Edition license (Cluster ID and License Token)
For detailed requirements, see the Requirements page.

​
Installation

​
Set Environment Variables

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

​
Install with Helm

helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.0.1 \
  --namespace formance-system \
  --create-namespace \
  --set tags.EntrepriseEdition=true \
  --set global.licence.clusterID=$CLUSTER_ID \
  --set global.licence.token=$LICENCE_TOKEN
This installs the full Formance Platform including:
  • Data Plane — Operator, CRDs, and Versions (via the regions subchart)
  • Control Plane — Membership, Console, Portal, and Dex (via the cloudprem subchart)
  • Bundled PostgreSQL — shared by all components
All service hostnames are derived from global.serviceHost:
ServiceDefault Hostname
Membershipmembership.<serviceHost>
Dex (OIDC)dex.<serviceHost>
Portalportal.<serviceHost>
Console V3console.<serviceHost>

​
Using Minimal Profile

For a minimal Enterprise installation using the ee-minimal profile: 
helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.0.1 \
  --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

​
EE Demo Profile

To deploy a complete EE platform with a pre-configured demo stack, layer ee-demo.yaml on top of ee-minimal.yaml: 
helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.0.1 \
  --namespace formance-system \
  --create-namespace \
  --set tags.EntrepriseEdition=true \
  --set global.serviceHost=$BASE_DOMAIN \
  --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 \
  -f https://raw.githubusercontent.com/formancehq/helm/main/charts/formance/profiles/ee-demo.yaml
This adds a demo-demo stack with Auth, Gateway, Ledger, and Stargate modules, pre-configured demo users (support@formance.com / admin@formance.com, password: password), and a wizard that auto-creates the organization, region, and stack.
Profiles can be layered using multiple -f flags. Values from later files override earlier ones.

​
Full Configuration Example

For a production deployment with a custom domain and TLS: 
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.0.1 \
  --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

​
Using a Values File

For complex configurations, use a values file: 
# values.yaml
tags:
  EntrepriseEdition: true

global:
  serviceHost: "formance.example.com"
  licence:
    clusterID: "your-cluster-id"
    token: "your-licence-token"

  postgresql:
    host: "my-postgres.example.com"
    additionalArgs: "sslmode=require"
    auth:
      username: "formance"
      existingSecret: "postgres-credentials"

cloudprem:
  membership:
    ingress:
      enabled: true
      className: "nginx"  # or traefik, alb, etc.
      hosts:
        - host: "membership.formance.example.com"
          paths:
            - path: "/api"
              pathType: "Prefix"
      tls:
        - secretName: formance-tls
          hosts:
            - membership.formance.example.com
    dex:
      ingress:
        enabled: true
        hosts:
          - host: "dex.formance.example.com"
            paths:
              - path: "/"
                pathType: "Prefix"
        tls:
          - secretName: formance-tls
            hosts:
              - dex.formance.example.com
  portal:
    ingress:
      enabled: true
      hosts:
        - host: "portal.formance.example.com"
          paths:
            - path: "/"
              pathType: "Prefix"
      tls:
        - secretName: formance-tls
          hosts:
            - portal.formance.example.com
  console-v3:
    ingress:
      enabled: true
      hosts:
        - host: "console.formance.example.com"
          paths:
            - path: "/"
              pathType: "Prefix"
      tls:
        - secretName: formance-tls
          hosts:
            - console.formance.example.com

postgresql:
  enabled: false  # Use external PostgreSQL
Install with your values file: 
helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.0.1 \
  --namespace formance-system \
  --create-namespace \
  -f values.yaml

​
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
This is intentional to prevent accidental misconfiguration.
Get your Cluster ID with: kubectl get ns kube-system -o jsonpath='{.metadata.uid}'

​
Verify Installation

Check that all components are running: 
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

​
Migration from Previous Charts

If you previously used the cloudprem chart, follow these steps:

​
1. Backup Your Data

# Export current values
helm get values cloudprem -n formance-system > cloudprem-values.yaml

# Backup PostgreSQL data (recommended)
kubectl exec -n formance-system postgresql-0 -- pg_dumpall -U postgres > backup.sql

​
2. Map Configuration

The new chart nests cloudprem values under the cloudprem key. Common mappings:
Old (cloudprem)New (formance)
global.licence.tokenglobal.licence.token
global.licence.clusterIDglobal.licence.clusterID
global.serviceHostglobal.serviceHost
membership.*cloudprem.membership.*
console-v3.*cloudprem.console-v3.*
portal.*cloudprem.portal.*
dex.* (standalone)cloudprem.membership.dex.*

​
3. Uninstall Old Chart

helm uninstall cloudprem -n formance-system

​
4. Install New Chart

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

​
5. Verify Migration

# Check all pods are running
kubectl get pods -n formance-system

# Test Console access
curl -I https://console.your-domain.com

​
Next Steps

After installation:
  1. Configure the Control Plane — Set up Dex, create organizations, and configure SSO
  2. Configure Infrastructure Services
  3. Deploy your Stack

Control Plane Setup

Configure Dex, Membership, and Console

Create a Stack

Deploy your first Formance Stack