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

# Migrating from standalone CRM

> Complete guide for migrating from the standalone plugin-crm deployment to the CRM component integrated into Midaz.

Starting with **Midaz v3.5.0** and **Helm Chart v5.x**, CRM is no longer deployed as a standalone plugin. It is now integrated directly into the Midaz monorepo and Helm chart as an embedded component.

This guide explains how to migrate from the standalone `plugin-crm` deployment to the integrated CRM.

<Info>
  If you are starting a **new Midaz deployment** (v5.x+), you do not need this guide. Simply enable CRM in your Helm values as described in [Deploy Midaz using Helm](/en/platform/helm/midaz/midaz-installation). The integrated CRM is now the only supported deployment model.
</Info>

## What changed

***

The CRM plugin was originally maintained as a **separate codebase** with its own release cycle and deployed independently through a dedicated Helm chart (`plugin-crm`) in the `midaz-plugins` namespace.

Starting with **Midaz v3.5.0-beta.12** (December 2025), CRM was incorporated into the Midaz monorepo under `components/crm/`. Its deployment was then consolidated into the main Midaz Helm chart beginning in **v5.x**.

### Architecture comparison

| Aspect           | Standalone (v4.x and earlier)       | Integrated (v5.x+)                       |
| :--------------- | :---------------------------------- | :--------------------------------------- |
| **Source code**  | Separate repository                 | `components/crm/` in the Midaz monorepo  |
| **Helm chart**   | `plugin-crm` (dedicated chart)      | Part of the `midaz` chart                |
| **Namespace**    | `midaz-plugins`                     | `midaz`                                  |
| **Versioning**   | Independent release cycle           | Matches Midaz core version               |
| **MongoDB**      | Own connection configuration        | Shared MongoDB with other Midaz services |
| **Installation** | `helm install plugin-crm oci://...` | `crm.enabled: true` in Midaz values      |
| **Port**         | 4003                                | 4003 (unchanged)                         |

### API changes

The CRM API remains **fully backward-compatible**. All endpoints available in the standalone version continue to work the same way in the integrated deployment.

| Resource             | Endpoints                                              | Status                      |
| :------------------- | :----------------------------------------------------- | :-------------------------- |
| **Holders**          | POST, GET (list), GET (by ID), PATCH, DELETE           | Unchanged                   |
| **Aliases**          | POST, GET (list by holder), GET (by ID), PATCH, DELETE | Unchanged                   |
| **Aliases (global)** | GET `/v1/aliases` (list across all holders)            | Unchanged                   |
| **Related Parties**  | DELETE                                                 | Added in integrated version |

<Tip>
  The `GET /v1/aliases` endpoint allows you to list aliases across all holders with advanced filtering. Filters include `holder_id`, `account_id`, `ledger_id`, `document`, banking details, regulatory fields, and related party attributes.

  This endpoint complements the holder-scoped endpoints under `/v1/holders/{holder_id}/aliases`.
</Tip>

<Note>
  The endpoint `DELETE /v1/holders/{holder_id}/aliases/{alias_id}/related-parties/{related_party_id}` was introduced with the integrated CRM.

  If you previously needed to remove related parties individually, this operation is now supported directly. In earlier versions, this required updating the alias payload without the related party.
</Note>

### What stays the same

* **API contract**: All existing endpoints, request and response schemas, and behaviors remain unchanged.
* **Database**: MongoDB continues to be the storage backend.
* **Authentication**: Access Manager integration works the same way (`PLUGIN_AUTH_ENABLED`, `PLUGIN_AUTH_ADDRESS`).
* **Encryption keys**: `LCRYPTO_HASH_SECRET_KEY` and `LCRYPTO_ENCRYPT_SECRET_KEY` are still required.
* **Default port**: CRM continues to run on port 4003.

## Pre-migration checklist

***

Before starting the migration, confirm the following:

<Steps>
  <Step>
    **Identify your current standalone version**

    <CodeGroup>
      ```bash Shell theme={null}
      helm list -n midaz-plugins
      ```
    </CodeGroup>

    Record the `plugin-crm` chart version and app version.
  </Step>

  <Step>
    **Backup your current Helm values**

    <CodeGroup>
      ```bash Shell theme={null}
      helm get values plugin-crm -n midaz-plugins > plugin-crm-values-backup.yaml
      ```
    </CodeGroup>
  </Step>

  <Step>
    **Backup your MongoDB data**

    <CodeGroup>
      ```bash Shell theme={null}
      # Find the MongoDB pod in the midaz-plugins namespace
      kubectl get pods -n midaz-plugins -l app=mongodb

      # Export the CRM database
      kubectl exec -n midaz-plugins <mongodb-pod> -- \
        mongodump --db crm --archive=/tmp/crm-backup.archive

      # Copy the backup locally
      kubectl cp midaz-plugins/<mongodb-pod>:/tmp/crm-backup.archive ./crm-backup.archive
      ```
    </CodeGroup>
  </Step>

  <Step>
    **Verify your Midaz chart is v5.x or later**

    <CodeGroup>
      ```bash Shell theme={null}
      helm list -n midaz
      ```
    </CodeGroup>

    If you are running v4.x or earlier, upgrade Midaz first using the [Upgrading Helm](/en/platform/helm/midaz/midaz-upgrade-guide) guide.
  </Step>

  <Step>
    **Schedule a maintenance window**

    CRM will be temporarily unavailable during migration. Plan for a short downtime window.
  </Step>
</Steps>

## Migration steps

***

### Step 1 — Enable CRM in the Midaz chart

Add the CRM configuration to your Midaz Helm values:

<CodeGroup>
  ```yaml values.yaml theme={null}
  crm:
    enabled: true
    configmap:
      MONGO_HOST: "midaz-mongodb.midaz.svc.cluster.local."
      MONGO_NAME: "crm"
      MONGO_USER: "midaz"
      MONGO_PORT: "27017"
    secrets:
      MONGO_PASSWORD: "<your-mongodb-password>"
      LCRYPTO_HASH_SECRET_KEY: "<your-existing-hash-key>"
      LCRYPTO_ENCRYPT_SECRET_KEY: "<your-existing-encrypt-key>"
  ```
</CodeGroup>

<Warning>
  Use the **same encryption keys** (`LCRYPTO_HASH_SECRET_KEY` and `LCRYPTO_ENCRYPT_SECRET_KEY`) used in the standalone deployment. Different keys will make existing encrypted data unreadable.
</Warning>

If you use external secrets:

<CodeGroup>
  ```yaml values.yaml theme={null}
  crm:
    enabled: true
    useExistingSecret: true
    existingSecretName: "crm-secrets"
  ```
</CodeGroup>

### Step 2 — Migrate your MongoDB data

If your standalone CRM used its own MongoDB instance, restore the data into the Midaz-managed MongoDB.

<CodeGroup>
  ```bash Shell theme={null}
  # Copy the backup to the Midaz MongoDB pod
  kubectl cp ./crm-backup.archive midaz/<midaz-mongodb-pod>:/tmp/crm-backup.archive

  # Restore the CRM database
  kubectl exec -n midaz <midaz-mongodb-pod> -- \
    mongorestore --archive=/tmp/crm-backup.archive --db crm --drop
  ```
</CodeGroup>

<Tip>
  If the standalone and integrated CRM already use the **same MongoDB instance**, you can skip this step. Just confirm that `MONGO_HOST` and `MONGO_NAME` match.
</Tip>

### Step 3 — Deploy the integrated CRM

<CodeGroup>
  ```bash Shell theme={null}
  helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
    --version 5.x.x \
    -n midaz \
    -f your-values.yaml
  ```
</CodeGroup>

### Step 4 — Verify the integrated CRM is running

<CodeGroup>
  ```bash Shell theme={null}
  # Check the pod status
  kubectl get pods -n midaz -l app=crm

  # Check the logs
  kubectl logs -n midaz deployment/midaz-crm

  # Test the health endpoint (run port-forward in a separate terminal)
  kubectl port-forward -n midaz svc/midaz-crm 4003:4003 &
  curl http://localhost:4003/health
  ```
</CodeGroup>

### Step 5 — Validate your data

Run a quick validation to confirm that your data migrated correctly.

<CodeGroup>
  ```bash Shell theme={null}
  # List holders through the integrated CRM
  curl -H "X-Organization-Id: <your-org-id>" \
    http://localhost:4003/v1/holders

  # Verify a specific holder
  curl -H "X-Organization-Id: <your-org-id>" \
    http://localhost:4003/v1/holders/<known-holder-id>
  ```
</CodeGroup>

Compare the results with the standalone deployment.

### Step 6 — Update DNS and ingress

Update your DNS records or ingress rules to point to the CRM service in the `midaz` namespace.

<CodeGroup>
  ```yaml ingress-example.yaml theme={null}
  # The CRM service name changes from the standalone chart
  # Old: plugin-crm.midaz-plugins.svc.cluster.local
  # New: midaz-crm.midaz.svc.cluster.local
  ```
</CodeGroup>

### Step 7 — Remove the standalone CRM

After confirming that everything works as expected, remove the standalone deployment.

<CodeGroup>
  ```bash Shell theme={null}
  helm uninstall plugin-crm -n midaz-plugins
  ```
</CodeGroup>

<Danger>
  Only uninstall the standalone CRM **after validating the integrated deployment**. This operation removes the standalone deployment and its resources.
</Danger>

If the `midaz-plugins` namespace is no longer needed, you can optionally remove it.

<CodeGroup>
  ```bash Shell theme={null}
  kubectl delete namespace midaz-plugins
  ```
</CodeGroup>

## Access Manager permissions

***

Access Manager permissions remain unchanged after the migration.

The application name continues to be `plugin-crm`, and permissions apply to the `holders` and `aliases` resources.

| Permission                          | Description    | Resources        | Allowed Methods          |
| :---------------------------------- | :------------- | :--------------- | :----------------------- |
| `plugin-crm-editor-permission`      | Full access    | holders, aliases | post, get, patch, delete |
| `plugin-crm-contributor-permission` | Read and write | holders, aliases | post, get, patch         |
| `plugin-crm-viewer-permission`      | Read only      | holders, aliases | get                      |

No updates are required in your Access Manager configuration.

## Rollback procedure

***

If you need to revert to the standalone CRM:

<Steps>
  <Step>
    Disable CRM in the Midaz chart:

    <CodeGroup>
      ```yaml values.yaml theme={null}
      crm:
        enabled: false
      ```
    </CodeGroup>
  </Step>

  <Step>
    Re-deploy the Midaz chart:

    <CodeGroup>
      ```bash Shell theme={null}
      helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
        --version 5.x.x -n midaz -f your-values.yaml
      ```
    </CodeGroup>
  </Step>

  <Step>
    Re-install the standalone `plugin-crm`:

    <CodeGroup>
      ```bash Shell theme={null}
      helm install plugin-crm oci://registry-1.docker.io/lerianstudio/plugin-crm \
        --version <your-previous-version> \
        -n midaz-plugins \
        -f plugin-crm-values-backup.yaml
      ```
    </CodeGroup>
  </Step>

  <Step>
    Restore DNS or ingress to point back to the standalone service.
  </Step>
</Steps>

## Troubleshooting

***

**CRM pod fails to start with encryption errors**

* Confirm that `LCRYPTO_HASH_SECRET_KEY` and `LCRYPTO_ENCRYPT_SECRET_KEY` exactly match the values used in the standalone deployment.

**Data appears empty after migration**

* Verify that `MONGO_HOST` and `MONGO_NAME` point to the correct MongoDB instance and database.
* If you ran `mongorestore`, confirm the restore completed successfully.

**Access Manager rejects requests**

* The application name in Access Manager should still be `plugin-crm`. No change is required.

**Port conflict on 4003**

* Running both the standalone and integrated CRM simultaneously will create a conflict on port 4003.

If you need to run both during testing, temporarily change the port in the Midaz values:

<CodeGroup>
  ```yaml values.yaml theme={null}
  crm:
    configmap:
      SERVER_PORT: "4013"
  ```
</CodeGroup>

## Next steps

***

<CardGroup cols={2}>
  <Card title="CRM Overview" icon="circle-info" href="/en/midaz/crm/crm-overview">
    Learn about CRM features and design principles.
  </Card>

  <Card title="Using CRM" icon="rocket" href="/en/midaz/crm/using-crm">
    Start working with holders and alias accounts.
  </Card>

  <Card title="Upgrading Helm" icon="arrow-up" href="/en/platform/helm/midaz/midaz-upgrade-guide">
    Complete Helm upgrade guide covering all migration paths.
  </Card>

  <Card title="Deploy Midaz using Helm" icon="dharmachakra" href="/en/platform/helm/midaz/midaz-installation">
    Full deployment reference for Midaz v5.x.
  </Card>
</CardGroup>