Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.formance.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Step 1: Install CRDs

The Formance Operator relies on Custom Resource Definitions (CRDs) that must be installed separately before deploying the platform: 
helm upgrade --install operator-crds oci://ghcr.io/formancehq/helm/operator-crds \
  --version 3.8.1 \
  --namespace formance-system \
  --create-namespace
CRDs are managed as a separate Helm release following Helm best practices. This prevents accidental deletion of CRDs (and all associated resources) when uninstalling or upgrading the platform chart.

​
Step 2: Install the Platform

Once the CRDs are in place, install the Formance platform: 
helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.2.0 \
  --namespace formance-system
This installs the Formance Operator 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.2.0 \
  --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.2.0 \
  --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.2.0 \
  --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.2.0

​
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.2.0 \
  --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