Formance

🚀 Quick Start

Local Development

Running the stack locally

1. Run Formance Stack

   a. With the Tilt UI

   • Visit Tilt Dashboard's Table View
   • Toggle 'Show disabled resources'
   • Locate 'formance' Group and Enable all its resources.

   b. With tilt args

   💡 We recommend using the Tilt UI for enabling/disabling resources.

   tilt up formance

2. Formance Dashboard

   💡 Please wait for a few minutes for the initial Formance migrations script to finish before accessing the Dashboard.

   Visit the Formance Dashboard at: http://formance.k8s.orb.local

3. Dex for OIDC Authentication

   When accessing the Formance dashboard, you will be prompted to log in via the Dex login page. Please use the following credentials:

   • Email Address: admin@kapitol.io
   • Password: password

   Upon successful login, click on "GRANT ACCESS" to gain access to the dashboard.

Connecting to the Formance Stack via API

Connecting to the Formance Stack via API requires an API Token. Follow the instructions below to generate an API Token.

1. OAUTH Clients

   1. Visit the Formance Dashboard at:

      1. Staging
      2. Local

   2. Navigate to 'OAuth Clients' view and click on the '+ New OAuth Client' button.

   3. Fill in the following information:

      1. Name: Any name you want to give to the client
      2. Redirect URI: leave empty
      3. Redirect post logout URI: leave empty
      4. Description: Any description you want to give to the client
      5. Then click on 'SAVE'.

   4. Copy the generated UUIDs for Client ID and Client Secret.

   💡 Note: Save the Client Secret securely, as you will not be able to retrieve it again. However, you can also generate a new secret if needed.

2. API Token

   On your terminal, run the following command:

   make formance-auth

   The following command will do the following:

   1. Export the Formance URL on your machine via environment variables FLOCAL for local Formance and FSTAGING for staging Formance.

   2. Automatically fetch the 'TOKEN ENDPOINT' from the Formance Stack.

   3. Automatically request an API Token based on the CLIENT ID and CLIENT SECRET you provided.

   4. Lastly, it will automatically export the API TOKEN to your machine via the environment variable FAT.

   💡 Note: Copy and save the generated ACCESS_TOKEN somewhere safe in case the 'FAT' variable gets deleted.

3. API Token Validation

   On your terminal, run the following command:

   For local:

   curl -s $FLOCAL/api/ledger/_info -H "Authorization: Bearer $FAT" | jq -r '.'

   For staging:

   curl -s $FSTAGING/api/ledger/_info -H "Authorization: Bearer $FAT" | jq -r '.'

4. Formance API Reference

   For more information on the Formance API Reference, please refer to the official documentation.

⚙️ Formance Architecture

Local Development

Ingress controller

The Formance Operator requires an ingress controller to be present on the cluster. In our case, we use AWS ALB.

Certificates Management

The operator depends on Cert-Manager, which should be available on the cluster before installing the operator.

OIDC Provider

The Auth service of the Formance Platform requires an OIDC provider to be available on the cluster. In our case, we use Dex. For more information on the Formance authentication process, please refer to the Formance Authentication documentation.

Stateful Dependencies

For proper functionality, stacks deployed within our local Kubernetes cluster require the following stateful dependencies:

1. NATS with Jetstream enabled: Deployed using the official NATS Helm chart (./kubernetes/charts/formance/stateful).
2. OpenSearch: Deployed using the official OpenSearch Helm chart (./kubernetes/charts/formance/stateful).
3. PostgreSQL: Deployed via Helm chart (./kubernetes/charts/postgres).

Formance's main database is initialized with the SQL file ./kubernetes/charts/postgres/sql-scripts/08-formance.sql.

Operator

The operator is responsible for deploying a full or partial Formance OSS Stack, simplifying deployment and release management of different Formance ecosystem components.

The operator is deployed using the Helm chart located at ./kubernetes/charts/formance/regions, derived from the official Formance regions Helm chart.

To pull and sync the latest Formance regions Helm chart locally, use the following command:

make sync-charts module=formance

Stack

The operator utilizes custom resource definitions (CRDs) specific to the Formance application. These CRDs automate common tasks such as application updates, version management, configuration, and scaling.

We employ three types of CRDs:

1. Version (./kubernetes/charts/formance/stack/templates/versions.yaml): Defines the application version to deploy.
2. Configuration (./kubernetes/charts/formance/stack/templates/configuration.yaml): Specifies application configurations, including ports, environment variables, and secrets.
3. Stack (./kubernetes/charts/formance/stack/templates/stacks.yaml): Defines the resources constituting the application, such as deployments, services, volumes, and other required Kubernetes resources.

Customize the stack using the values.dev.yaml file in the stack directory, containing default values that can be overridden.

Staging

Formance Dashboard

Visit the Staging Formance Dashboard at: https://formance-staging-internal.kapitol.io

Dex for OIDC Authentication

When accessing the Formance dashboard, you will be prompted to log in via the Dex login page. Please log in using your Nextfinancial Account. Upon successful login, click on "GRANT ACCESS" to gain access to the dashboard.

Stateful Dependencies

For proper functionality, Formance stacks deployed within our Kubernetes cluster require the following stateful dependencies:

1. NATS with Jetstream enabled: Deployed on Qovery as a Helm Service under the Staging Environment.
2. OpenSearch: Deployed on Qovery as a Helm Service under the Staging Environment.
3. PostgreSQL: Deployed on Qovery as a Helm Service under the Staging Environment.

Operator

The operator is responsible for deploying a full or partial Formance OSS Stack, simplifying deployment and release management of different Formance ecosystem components. The Operator is deployed on Qovery as a Helm service within the Staging Environment.

Stack

The operator utilizes custom resource definitions (CRDs) specific to the Formance application. These CRDs automate common tasks such as application updates, version management, configuration, and scaling.

We employ three types of CRDs:

1. Version (./kubernetes/charts/formance/stack/templates/versions.yaml): Defines the application version to deploy.
2. Configuration (./kubernetes/charts/formance/stack/templates/configuration.yaml): Specifies application configurations, including ports, environment variables, and secrets.
3. Stack (./kubernetes/charts/formance/stack/templates/stacks.yaml): Defines the resources constituting the application, such as deployments, services, volumes, and other required Kubernetes resources.

We customize the stack configuration using the values.yaml file found in the same directory as the CRD templates.

Secrets

The secrets used in the deployments of the Formance stack, Dex, Stateful Dependencies, and the Operator are stored in Infisical under the Kapitol Project.

Production

Coming soon...

Learn More

For more information on the Formance stack, please refer to the official documentation.