> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing and deploying

> Step-by-step guide for installing and deploying Midaz plugins on Kubernetes with Helm, covering prerequisites, values configuration, and post-install work.

<Warning>
  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`.
</Warning>

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.

<Note>
  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](/en/platform/deploy/midaz/midaz-installation) if you haven't set up Midaz yet.
</Note>

## Prerequisites

***

Before deploying plugins, make sure you have:

* A running [**Kubernetes**](https://kubernetes.io/releases/) cluster with Midaz Core already deployed. Use a currently supported minor release in production.
* [**Helm 3.8 or later**](https://helm.sh/docs/intro/install/), 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:

```bash theme={null}
helm version
```

```bash theme={null}
kubectl cluster-info
```

<Tip>
  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.
</Tip>

## 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>`.

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

## 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:

```bash theme={null}
helm show chart oci://registry-1.docker.io/lerianstudio/<chart-name>
```

Check [plugin version compatibility](/en/platform/deploy/midaz-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

<Tabs>
  <Tab title="Pix">
    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Indirect Pix (BTG)">
    ```bash theme={null}
    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
    ```
  </Tab>
</Tabs>

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:

```bash theme={null}
helm list -n midaz-plugins
```

Check the pod status:

```bash theme={null}
kubectl get pods -n midaz-plugins
```

All pods should show `Running` status and `READY` state.

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

  ```bash theme={null}
  helm install <release-name> <oci-chart> \
    --version <version> \
    -n midaz-plugins \
    --create-namespace \
    -f my-plugin-values.yaml
  ```
</Tip>

## 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.

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

## 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:

```yaml theme={null}
<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.

<Tip>
  For detailed ingress configuration examples with **AWS ALB** and **Traefik**, refer to the [Midaz Helm deployment guide](/en/platform/deploy/midaz/midaz-ingress). The same patterns apply to plugin charts.
</Tip>

## Verifying your deployment

***

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

### Check pod status

```bash theme={null}
kubectl get pods -n midaz-plugins -o wide
```

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

### Check pod logs

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
helm upgrade <release-name> <oci-registry> \
  --version <new-version> \
  -n midaz-plugins \
  -f my-plugin-values.yaml
```

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

For detailed upgrade procedures, pre-upgrade checklists, and rollback instructions, see the [Helm upgrade guide](/en/platform/deploy/midaz/midaz-upgrade-guide).

## Uninstalling a plugin

***

To remove a plugin from your cluster:

```bash theme={null}
helm uninstall <release-name> -n midaz-plugins
```

<Warning>
  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.
</Warning>

## Related resources

***

* [Deploy Midaz using Helm](/en/platform/deploy/midaz/midaz-installation) – Initial Midaz Core installation guide
* [Helm upgrade guide](/en/platform/deploy/midaz/midaz-upgrade-guide) – Upgrade procedures and rollback instructions
* [Midaz chart version compatibility](/en/platform/deploy/helm-version-compatibility) – Current Midaz chart and application metadata
* [Plugin version compatibility](/en/platform/deploy/midaz-version-compatibility) – Plugin compatibility with Midaz Core versions
* [Our plugins](/en/products/about-plugins) – Plugin catalog and how plugins work
* [Helm repository](https://github.com/LerianStudio/helm) – Source code, charts, and release notes