Skip to main content
This guide walks you through installing Formance Community Edition on your Kubernetes cluster using the unified Formance Helm chart.

​
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.)
For detailed requirements, see the Requirements page.

​
Quick Start

Install Formance with a single command: 
helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.0.1 \
  --namespace formance-system \
  --create-namespace
This installs the Formance Operator, CRDs, and a bundled PostgreSQL instance in the formance-system namespace. Community Edition is enabled by default (tags.CommunityEdition: true).

​
Using Minimal Profile

For a minimal installation with reduced resource requirements: 
helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.0.1 \
  --namespace formance-system \
  --create-namespace \
  -f https://raw.githubusercontent.com/formancehq/helm/main/charts/formance/profiles/ce-minimal.yaml

​
Demo Mode

To quickly test Formance with a bundled PostgreSQL and a pre-configured stack, layer the CE demo profile on top of the minimal profile: 
helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.0.1 \
  --namespace formance-system \
  --create-namespace \
  -f https://raw.githubusercontent.com/formancehq/helm/main/charts/formance/profiles/ce-minimal.yaml \
  -f https://raw.githubusercontent.com/formancehq/helm/main/charts/formance/profiles/ce-demo.yaml
This deploys a demo-demo stack with Gateway and Ledger modules, plus a bundled PostgreSQL. The demo profile configures regions.stacks and regions.settings automatically. See the Demo Deployment guide for more details.
Profiles can be layered using multiple -f flags. Values from later files override earlier ones.
Demo mode is intended for testing only. The bundled PostgreSQL has no persistent storage. Do not use in production.

​
Custom Configuration

​
Using a Values File

Create a custom values.yaml to configure the platform. Here’s an example with an external PostgreSQL and custom stack settings: 
# values.yaml
postgresql:
  enabled: false  # Disable bundled PostgreSQL

global:
  postgresql:
    host: "my-postgres.example.com"
    additionalArgs: "sslmode=require"
    auth:
      username: "formance"
      password: "your-secure-password"
      database: "formance"

regions:
  operator:
    enabled: true
  versions:
    create: true
  settings:
    postgres-uri:
      key: "postgres.*.uri"
      value: "postgresql://formance:your-secure-password@my-postgres.example.com:5432?disableSSLMode=true"
Install with your custom values: 
helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.0.1 \
  --namespace formance-system \
  --create-namespace \
  -f values.yaml

​
View All Configuration Options

To see all available configuration options: 
helm show values oci://ghcr.io/formancehq/helm/formance --version 1.0.1

​
Verify Installation

Check that the operator is running: 
kubectl get pods -n formance-system
You should see the operator pod in Running state: 
NAME                                  READY   STATUS    RESTARTS   AGE
formance-operator-xxxxx-xxxxx         1/1     Running   0          1m

​
Migration from Previous Charts

If you previously used the regions and operator-crds charts separately, follow these steps to migrate to the unified chart:

​
1. Backup Your Configuration

# Export current values
helm get values regions -n formance-system > regions-values.yaml
helm get values operator-crds -n formance-system > crds-values.yaml

​
2. Verify CRDs Have Keep Policy

Ensure your CRDs have the helm.sh/resource-policy: keep annotation:
kubectl get crds authclients.formance.com -o json | jq .metadata.annotations
You should see:
{
  "helm.sh/resource-policy": "keep"
}

​
3. Uninstall Old Charts

# CRDs will be preserved due to keep policy
helm uninstall regions -n formance-system
helm uninstall operator-crds -n formance-system

​
4. Install Unified Chart

helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.0.1 \
  --namespace formance-system
Your existing stacks and resources will continue to work with the new operator.

​
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 (Ledger, Payments, etc.)

PostgreSQL Setup

Configure PostgreSQL for your stack

Create a Stack

Deploy your first Formance Stack