Installing and deploying

CRM and Fees guidance marked legacy on this page applies only to legacy releases that already exist. Midaz v4 deploys the unified Ledger and serves CRM and Fees on /v2.

In Midaz v4, the unified Ledger contains CRM and Fees as modules. Use their /v2 API through the Ledger. They are not separate services, ports, plugins, or Helm releases. Midaz plugins ship as independent Helm charts and follow the same deployment model as Midaz Core. Each plugin runs as a separate service alongside the platform, with its own configuration, dependencies, and lifecycle.

Before deploying any plugin, make sure you have a running Midaz Core instance. Plugins depend on Midaz Core APIs and cannot operate independently. See the Midaz Helm deployment guide if you haven’t set up Midaz yet.

Prerequisites

Before deploying plugins, make sure you have:

A running Kubernetes cluster with Midaz Core already deployed. Use a currently supported minor release in production.
Helm 3.8 or later, for OCI registry support.
kubectl configured with access to your cluster.
Cluster admin permissions or appropriate RBAC roles.
A valid Enterprise license key for the plugin you deploy.

Verify your tools are ready:

helm version

kubectl cluster-info

In Midaz v4, CRM ships from the same source-available Midaz repository as an embedded Ledger component. It is not a plugin with a separate license. Separately deployed plugins may require an Enterprise license. Contact a Lerian representative if you need one.

Available plugin charts

Each plugin ships as an OCI-compatible Helm chart.

Plugin	Chart name	Default namespace
Fees	`plugin-fees-helm`	`midaz-plugins`
Pix	`plugin-br-pix-direct-jd-helm`	`midaz-plugins`
Indirect Pix (BTG)	`plugin-br-pix-indirect-btg-helm`	`midaz-plugins`
Bank Transfer	`plugin-br-bank-transfer-helm`	`midaz-plugins`

Every chart is published at oci://registry-1.docker.io/lerianstudio/<chart-name>.

CRM is a module inside the midaz-helm chart. You enable it with the crm values block. No CRM chart exists.

Installing a plugin

The installation process is the same for all plugins. Replace the chart name, registry, and version for the plugin you want to deploy.

1. Check available versions

Read the current chart version from the registry:

helm show chart oci://registry-1.docker.io/lerianstudio/<chart-name>

Check plugin version compatibility to find a plugin version compatible with your Midaz Core version, and inspect that plugin’s chart metadata before deploying it.

2. Install the chart

Pix
Indirect Pix (BTG)

helm install plugin-br-pix-direct-jd \
  oci://registry-1.docker.io/lerianstudio/plugin-br-pix-direct-jd-helm \
  --version <version> \
  -n midaz-plugins \
  --create-namespace

helm install plugin-br-pix-indirect-btg \
  oci://registry-1.docker.io/lerianstudio/plugin-br-pix-indirect-btg-helm \
  --version <version> \
  -n midaz-plugins \
  --create-namespace

Replace <version> with the desired chart version. The --create-namespace flag creates the midaz-plugins namespace if it doesn’t already exist.

3. Verify the installation

After installing, confirm the release is deployed:

helm list -n midaz-plugins

Check the pod status:

kubectl get pods -n midaz-plugins

All pods should show Running status and READY state.

To install a plugin with custom configuration, create a values.yaml file and pass it with the -f flag:

helm install <release-name> <oci-chart> \
  --version <version> \
  -n midaz-plugins \
  --create-namespace \
  -f my-plugin-values.yaml

Configure the selected chart

Plugin charts do not share one license, secret, or persistence contract. Inspect the selected chart’s values.schema.json and chart-specific documentation before setting values. Do not reuse CRM or Fees examples: in Midaz v4 they are Ledger modules, not plugin charts. For example, Bank Transfer requires chart-specific encryption keys and uses bankTransfer.secrets.MONGO_URI when its bundled MongoDB is disabled. Its license integration is optional when LICENSE_SERVICE_ADDRESS and TENANT_IDS are unset. Other plugins have different requirements.

Keep sensitive values in Kubernetes Secrets. Do not assume a key accepted by one plugin is valid for another.

Configuring ingress

By default, plugin services use ClusterIP, so they are only accessible within the cluster. To expose a plugin externally, enable ingress in your values.yaml. The ingress configuration follows the same pattern as Midaz Core. Here’s an example using NGINX:

<plugin>:
  ingress:
    enabled: true
    className: "nginx"
    annotations: {}
    hosts:
      - host: plugin.example.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: plugin-tls
        hosts:
          - plugin.example.com

Replace <plugin> with the plugin’s service key.

For detailed ingress configuration examples with AWS ALB and Traefik, refer to the Midaz Helm deployment guide. The same patterns apply to plugin charts.

Verifying your deployment

After you install a plugin, verify that it runs correctly.

Check pod status

kubectl get pods -n midaz-plugins -o wide

All pods should be in Running state with all containers ready.

Check pod logs

kubectl logs -n midaz-plugins deployment/<plugin-deployment-name> --tail=50

Look for successful startup messages and verify there are no errors related to database connections, license validation, or missing configuration.

Test the health endpoint

Each plugin sets its own probe paths. Read them from the Deployment:

kubectl get deploy <plugin-deployment-name> -n midaz-plugins -o yaml

Read the service name and its port with kubectl get svc -n midaz-plugins. Then port-forward the Service and call the path you read:

kubectl port-forward -n midaz-plugins svc/<plugin-service-name> <local-port>:<service-port>
curl http://localhost:<local-port>/<probe-path>

Upgrading plugins

To upgrade a plugin to a new version, use helm upgrade with the target version:

helm upgrade <release-name> <oci-registry> \
  --version <new-version> \
  -n midaz-plugins \
  -f my-plugin-values.yaml

Always upgrade Midaz Core before upgrading plugins. Plugins depend on Midaz Core APIs, so upgrading in the wrong order may cause compatibility issues.

For detailed upgrade procedures, pre-upgrade checklists, and rollback instructions, see the Helm upgrade guide.

Uninstalling a plugin

To remove a plugin from your cluster:

helm uninstall <release-name> -n midaz-plugins

Uninstalling a plugin removes its Kubernetes resources (deployments, services, configmaps, secrets) but does not delete persistent data stored in databases. If you used the bundled MongoDB, the PersistentVolumeClaims may remain. Delete them manually if you want to fully clean up.

Deploy Midaz using Helm – Initial Midaz Core installation guide
Helm upgrade guide – Upgrade procedures and rollback instructions
Midaz chart version compatibility – Current Midaz chart and application metadata
Plugin version compatibility – Plugin compatibility with Midaz Core versions
Our plugins – Plugin catalog and how plugins work
Helm repository – Source code, charts, and release notes

Introduction

Midaz

Other products

Installing and deploying

Prerequisites

Available plugin charts

Installing a plugin

1. Check available versions

2. Install the chart

3. Verify the installation

Configure the selected chart

Configuring ingress

Verifying your deployment

Check pod status

Check pod logs

Test the health endpoint

Upgrading plugins

Uninstalling a plugin

​Prerequisites

​Available plugin charts

​Installing a plugin

​1. Check available versions

​2. Install the chart

​3. Verify the installation

​Configure the selected chart

​Configuring ingress

​Verifying your deployment

​Check pod status

​Check pod logs

​Test the health endpoint

​Upgrading plugins

​Uninstalling a plugin

​Related resources

Prerequisites

Available plugin charts

Installing a plugin

1. Check available versions

2. Install the chart

3. Verify the installation

Configure the selected chart

Configuring ingress

Verifying your deployment

Check pod status

Check pod logs

Test the health endpoint

Upgrading plugins

Uninstalling a plugin

Related resources