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 assumes you have already completed the Enterprise Edition installation.
After installing Formance Enterprise Edition, you need to configure the control plane components: Dex (OIDC provider), Membership (management API), and Console (web interface).

​
Components Overview

ComponentDescriptionDefault URL
DexOIDC/OAuth2 provider for authenticationdex.<your-domain>
MembershipManagement API for organizations, users, and stacksmembership.<your-domain>
ConsoleWeb interface for managing your Formance stackconsole.<your-domain>

​
Dex Configuration

Dex is deployed as the default OIDC provider. You can configure it to:
  • Create local users for testing
  • Connect to external identity providers (SAML, LDAP, OAuth2)
  • Integrate with your existing SSO infrastructure

​
Default Configuration

The default Dex configuration creates a simple setup for testing with a static admin user. For production, configure your own identity provider.

​
Connecting to External Identity Providers

Dex configuration is set through cloudprem.membership.dex.configOverrides, which merges with the default Dex configuration generated by the Membership chart. 
# values.yaml
cloudprem:
  membership:
    dex:
      configOverrides:
        connectors:
          - type: saml
            id: saml
            name: SAML
            config:
              ssoURL: https://your-idp.example.com/sso
              ca: /path/to/ca.pem
              redirectURI: https://dex.your-domain.com/callback
              usernameAttr: name
              emailAttr: email

# values.yaml
cloudprem:
  membership:
    dex:
      configOverrides:
        connectors:
          - type: ldap
            id: ldap
            name: LDAP
            config:
              host: ldap.example.com:636
              insecureNoSSL: false
              bindDN: cn=admin,dc=example,dc=com
              bindPW: admin-password
              userSearch:
                baseDN: ou=users,dc=example,dc=com
                filter: "(objectClass=person)"
                username: uid
                idAttr: uid
                emailAttr: mail
                nameAttr: cn

# values.yaml
cloudprem:
  membership:
    dex:
      configOverrides:
        connectors:
          - type: oidc
            id: okta
            name: Okta
            config:
              issuer: https://your-org.okta.com
              clientID: your-client-id
              clientSecret: your-client-secret
              redirectURI: https://dex.your-domain.com/callback
              scopes:
                - openid
                - profile
                - email

​
Using Your Own OIDC Provider

If you already have an OIDC provider (e.g., Keycloak), you can bypass Dex entirely: 
# values.yaml
global:
  platform:
    membership:
      relyingParty:
        scheme: "https"
        host: "keycloak.example.com"
        path: "/realms/master"

cloudprem:
  membership:
    dex:
      enabled: false
    config:
      oidc:
        clientId: "membership"
        clientSecret: "your-client-secret"
        scopes:
          - openid
          - email
          - federated:id
The global.platform.membership.relyingParty defines the OIDC issuer URL. Use the path field when your provider uses a sub-path (e.g., Keycloak realms).

​
Membership Configuration

You can customize authentication behavior and stack defaults: 
cloudprem:
  membership:
    config:
      oidc:
        clientId: "membership"
        clientSecret: "changeMe"
        scopes:
          - openid
          - email
          - federated:id
      auth:
        loginWithSSO: false  # Enable email-based SSO selector
        tokenValidity:
          accessToken: "5m"
          refreshToken: "72h"
      stack:
        minimalStackModules:
          - Auth
          - Ledger
          - Gateway
        additionalModules:
          - Payments
          - Stargate
      fctl: true  # Enable fctl CLI support

​
Service Ports

ServicePortProtocol
Membership8080HTTP
Membership8082gRPC
Dex5556HTTP
Portal3000HTTP
Console V33000HTTP

​
Initial Setup with Membership CLI

The Membership CLI provides commands to configure your self-hosted deployment. You run these commands directly inside the Membership container.

​
Accessing the Membership CLI

Connect to the Membership container: 
kubectl exec -it -n formance-system deployment/membership -- sh
Use the configuration init command for an all-in-one setup: 
membership configuration init \
  --region-name "default" \
  --region-base-url "https://formance.your-domain.com" \
  --production \
  --org-name "My Company" \
  --admin-email "admin@your-company.com" \
  --stack-name "production"
This command creates:
  • A region for your deployment
  • An organization
  • An admin user
  • A stack ready to use

​
Check Database Connection

Before running any configuration, verify the database connection: 
membership configuration check
This displays the connection status and migration state.

​
Manual Setup

If you prefer to configure each component separately:

​
Create a Region

membership configuration region create \
  --name "default" \
  --base-url "https://formance.your-domain.com" \
  --production
List existing regions: 
membership configuration region list

​
Create an Organization

membership configuration org create \
  --name "My Company"
List organizations: 
membership configuration org list

​
Create a User

membership configuration user create \
  --email "admin@your-company.com" \
  --org "My Company" \
  --role ADMIN
Available roles:
  • ADMIN - Full access
  • GUEST - Read-only access
List users: 
membership configuration user list --org "My Company"

​
Create a Stack

membership configuration stack create \
  --name "production" \
  --org "My Company" \
  --region "default"
List stacks: 
membership configuration stack list

​
JSON Output

All commands support the --json flag for scripting: 
membership configuration region list --json
membership configuration org list --json
membership configuration stack list --json

​
Available Commands Reference

membership configuration
├── check              # Verify database connection and status
├── init               # All-in-one setup command
├── region
│   ├── create         # Create a new region
│   ├── list           # List all regions
│   └── delete         # Delete a region
├── org
│   ├── create         # Create an organization
│   └── list           # List organizations
├── stack
│   ├── create         # Create a stack
│   ├── list           # List stacks
│   └── delete         # Delete a stack
└── user
    ├── create         # Create a user
    └── list           # List users

​
Configure Organization with fctl

After the initial setup, you can use fctl for additional configuration.

​
Login to Your Cluster

fctl login --membership-uri https://membership.<your-domain>/api

​
Configure Auto-Login for Your Domain

fctl cloud organizations update <ORGANIZATION_ID> \
  --domain=your-company.com \
  --default-organization-role=GUEST \
  --default-stack-role=GUEST

​
Wizard Bootstrap (Alternative to CLI)

Instead of using the Membership CLI, you can auto-create users, organizations, regions, and stacks on first install using the wizard in your values file: 
cloudprem:
  membership:
    dex:
      configOverrides:
        staticPasswords:
          - email: "admin@example.com"
            hash: "$2a$10$..."  # bcrypt hash of password
            username: "admin"
            userID: "unique-uuid"
            role: ADMIN
    config:
      wizard:
        setup: |
          users:
            - id: "unique-uuid"
              email: "admin@example.com"
              role: "ADMIN"
          organizations:
            - id: "my-org"
              ownerId: "unique-uuid"
              name: "My Organization"
          regions:
            - id: "region-1"
              name: "production"
              organizationId: "my-org"
              baseUrl: "https://formance.example.com"
          stacks:
            - id: "main"
              name: "main"
              organizationId: "my-org"
              regionId: "region-1"
              version: "v3.1"
The wizard job runs once on first install and creates all the configured resources. This is the approach used by the ee-demo.yaml profile.

​
Accessing the Console

After setup, access the Console at: 
https://console.<your-domain>
Log in with your configured identity provider credentials.

​
Verifying the Setup

​
Check Component Health

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

# Check services
kubectl get svc -n formance-system

# Check ingresses
kubectl get ingress -n formance-system

​
Test Authentication

# Test Dex
curl -I https://dex.<your-domain>/.well-known/openid-configuration

# Test Membership API
curl -I https://membership.<your-domain>/api/_info

# Test Console
curl -I https://console.<your-domain>

​
Troubleshooting

  1. Verify ingress is configured:
kubectl get ingress -n formance-system
  1. Check TLS certificate:
kubectl describe certificate -n formance-system
  1. Check Console logs:
kubectl logs -n formance-system -l app=console
  1. Check Dex configuration:
kubectl get secret -n formance-system membership-dex-config -o jsonpath='{.data.config\.yaml}' | base64 -d
  1. Verify Dex is accessible:
curl https://dex.<your-domain>/.well-known/openid-configuration
  1. Check Dex logs:
kubectl logs -n formance-system -l app.kubernetes.io/name=dex
  1. Check database connection from inside the container:
kubectl exec -it -n formance-system deployment/membership -- membership configuration check
  1. Check Membership logs:
kubectl logs -n formance-system -l app=membership
  1. Verify PostgreSQL is running:
kubectl get pods -n formance-system -l app.kubernetes.io/name=postgresql

​
Next Steps

Infrastructure Services

Configure PostgreSQL and other services

Deploy a Stack

Create your first Formance Stack