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

Midaz plugins are distributed 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.

This guide walks you through installing, configuring, and verifying plugin deployments on Kubernetes.

<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/helm/midaz/midaz-installation) if you haven't set up Midaz yet.
</Note>

## Prerequisites

***

Before deploying plugins, ensure you have:

* [**Kubernetes (v1.30+)**](https://kubernetes.io/releases/download/) – A running cluster with Midaz Core already deployed.
* [**Helm 3+**](https://helm.sh/docs/intro/install/) – Installed and available.
* **kubectl** configured with access to your cluster.
* **Cluster admin** permissions or appropriate RBAC roles.
* A valid **Enterprise license key** (required for all plugins except CRM).

Verify your tools are ready:

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

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

<Tip>
  CRM is **source available** and does not require a license key. It is now an embedded component of Midaz. All other plugins require a valid Enterprise license. Contact a Lerian representative if you need one.
</Tip>

## Available plugin charts

***

Each plugin is published as an OCI-compatible Helm chart. The table below lists all available plugins and their chart references.

| Plugin                 | Chart name                   | OCI registry                                                           | Default namespace |
| :--------------------- | :--------------------------- | :--------------------------------------------------------------------- | :---------------- |
| **CRM**                | `plugin-crm`                 | `oci://registry-1.docker.io/lerianstudio/plugin-crm`                   | `midaz-plugins`   |
| **Fees Engine**        | `plugin-fees`                | `oci://registry-1.docker.io/lerianstudio/plugin-fees-helm`             | `midaz-plugins`   |
| **Pix Direct (JD)**    | `plugin-br-pix-direct-jd`    | `oci://registry-1.docker.io/lerianstudio/plugin-br-pix-direct-jd`      | `midaz-plugins`   |
| **Pix Indirect (BTG)** | `plugin-br-pix-indirect-btg` | `oci://registry-1.docker.io/lerianstudio/plugin-br-pix-indirect-btg`   | `midaz-plugins`   |
| **Bank Transfer**      | `plugin-br-bank-transfer`    | `oci://registry-1.docker.io/lerianstudio/plugin-br-bank-transfer-helm` | `midaz-plugins`   |

<Note>
  Starting from Midaz v5.x, **CRM** is now available as an integrated component within the main Midaz Helm chart. If you are running v5.x, you can enable CRM directly in your Midaz values instead of deploying it separately. See the [Midaz Helm guide](/en/platform/helm/midaz/midaz-installation) for details. Also note that the **Pix plugins** are still under active development.
</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

You can find available chart versions by checking the [Helm repository tags](https://github.com/LerianStudio/helm/tags) on GitHub. Filter by the plugin prefix (e.g., `plugin-crm-v`, `plugin-fees-v`).

You can also check the [version compatibility table](/en/platform/helm/helm-version-compatibility) to find the right chart version for your Midaz Core version.

### 2. Install the chart

<Tabs>
  <Tab title="CRM">
    ```bash theme={null}
    helm install plugin-crm oci://registry-1.docker.io/lerianstudio/plugin-crm \
      --version <version> \
      -n midaz-plugins \
      --create-namespace
    ```
  </Tab>

  <Tab title="Fees Engine">
    ```bash theme={null}
    helm install plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees-helm \
      --version <version> \
      -n midaz-plugins \
      --create-namespace
    ```
  </Tab>

  <Tab title="Pix Direct (JD)">
    ```bash theme={null}
    helm install plugin-br-pix-direct-jd oci://registry-1.docker.io/lerianstudio/plugin-br-pix-direct-jd \
      --version <version> \
      -n midaz-plugins \
      --create-namespace
    ```
  </Tab>

  <Tab title="Pix Indirect (BTG)">
    ```bash theme={null}
    helm install plugin-br-pix-indirect-btg oci://registry-1.docker.io/lerianstudio/plugin-br-pix-indirect-btg \
      --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 that all pods are running:

```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 plugin-crm oci://registry-1.docker.io/lerianstudio/plugin-crm \
    --version <version> \
    -n midaz-plugins \
    --create-namespace \
    -f my-plugin-crm-values.yaml
  ```
</Tip>

## Configuring license keys

***

All plugins except CRM require a valid Enterprise license key. You configure it through the Helm chart's `secrets` section in your `values.yaml`:

```yaml theme={null}
<plugin>:
  secrets:
    LICENSE_KEY: "<your-license-key>"
    ORGANIZATION_IDS: "<your-organization-ids>"
```

Replace `<plugin>` with the plugin's service key (e.g., `crm`, `fees`).

<Warning>
  Deploying a licensed plugin without a valid key will result in the service starting but rejecting API requests. Make sure your license key and organization IDs are configured before going to production.
</Warning>

## Configuring dependencies

***

Plugins bundle their own database dependencies by default. This means you can deploy a plugin and have a working setup without any extra database configuration. However, for production environments, you'll likely want to use your own managed databases.

### MongoDB

The **CRM**, **Fees Engine**, and **Pix** plugins use MongoDB for data storage. Each plugin chart includes a bundled [Bitnami MongoDB](https://charts.bitnami.com/bitnami) dependency (v16.4.0) that is enabled by default.

To use an **external MongoDB** instance, disable the bundled dependency and point the plugin to your instance:

```yaml theme={null}
mongodb:
  enabled: false

<plugin>:
  configmap:
    MONGO_HOST: <your-host>
    MONGO_NAME: <your-database-name>
    MONGO_USER: <your-user>
    MONGO_PORT: "<your-port>"
  secrets:
    MONGO_PASSWORD: <your-password>
```

Replace `<plugin>` with the plugin's service key (e.g., `crm`, `fees`).

## Using existing Kubernetes Secrets

***

For production environments, you can manage secrets outside of Helm by referencing an existing Kubernetes Secret. This avoids storing sensitive values directly in your `values.yaml`.

<Steps>
  <Step title="Create the secret">
    Create a Kubernetes Secret with the required keys for your plugin. For example, for CRM:

    ```bash theme={null}
    kubectl create secret generic plugin-crm-secrets \
      --from-literal=LCRYPTO_HASH_SECRET_KEY='<your-hash-key>' \
      --from-literal=LCRYPTO_ENCRYPT_SECRET_KEY='<your-encrypt-key>' \
      --from-literal=MONGO_PASSWORD='<your-mongo-password>' \
      --from-literal=LICENSE_KEY='<your-license-key>' \
      --from-literal=ORGANIZATION_IDS='<your-org-ids>' \
      -n midaz-plugins
    ```
  </Step>

  <Step title="Reference it in your values">
    Configure the plugin to use the existing secret:

    ```yaml theme={null}
    crm:
      useExistingSecret: true
      existingSecretName: "plugin-crm-secrets"
    ```
  </Step>
</Steps>

This pattern works for all plugins. Each plugin accepts `useExistingSecret` and `existingSecretName` parameters.

## Configuring ingress

***

Plugin services are deployed as `ClusterIP` by default, meaning 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/helm/midaz/midaz-ingress). The same patterns apply to plugin charts.
</Tip>

## Verifying your deployment

***

After installing a plugin, verify that everything is running 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

All plugins expose a `/health` endpoint. You can verify it via port-forwarding:

```bash theme={null}
kubectl port-forward -n midaz-plugins svc/<plugin-service-name> <local-port>:<service-port>
```

Then check the health endpoint:

```bash theme={null}
curl http://localhost:<local-port>/health
```

| Plugin             | Service name                 | Default port |
| :----------------- | :--------------------------- | :----------- |
| CRM                | `plugin-crm`                 | 4003         |
| Fees Engine        | `plugin-fees`                | 4002         |
| Pix Indirect (BTG) | `plugin-br-pix-indirect-btg` | 8080         |

## 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/helm/midaz/midaz-upgrade-guide).

## Uninstalling a plugin

***

To remove a plugin from your cluster:

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

For example:

```bash theme={null}
helm uninstall plugin-crm -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/helm/midaz/midaz-installation) – Initial Midaz Core installation guide
* [Helm upgrade guide](/en/platform/helm/midaz/midaz-upgrade-guide) – Upgrade procedures and rollback instructions
* [Version compatibility](/en/platform/helm/helm-version-compatibility) – Helm chart and application version mapping
* [Plugin version compatibility](/en/midaz/plugins/midaz-version-compatibility) – Plugin compatibility with Midaz Core versions
* [What are plugins?](/en/midaz/plugins/what-are-plugins) – Overview of the plugin architecture
* [Helm repository](https://github.com/LerianStudio/helm) – Source code, charts, and release notes