> ## 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 v3.x to v5.x

> Upgrade your Midaz Helm deployment directly from v3.x to v5.x: address breaking changes from both major versions in a single migration.

<Warning>
  CRM and Fees guidance marked legacy on this page applies only to an existing legacy release. Midaz v4 deploys the unified Ledger and serves CRM and Fees on `/v2`.
</Warning>

<Note>
  This guide's v3.x and v5.x labels refer to **Helm chart releases**, not Midaz application versions. The historical chart v5 line introduced the Ledger workload as an option. Midaz application v4 now uses the unified Ledger.
</Note>

The Helm repository retains a `crm.enabled` workload and the `plugin-fees-helm` chart for older application releases. These are legacy compatibility surfaces, not the Midaz v4 deployment model.

If you're upgrading directly from v3.x to v5.x, you need to address breaking changes from both versions.

## Pre-upgrade checklist

***

<Steps>
  <Step>
    Backup existing Helm releases:

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

  <Step>
    **Critical**: Backup RabbitMQ data and definitions (v4.x breaking change).
  </Step>

  <Step>
    **Decision required for this historical chart migration**: Choose the Ledger workload or the legacy Onboarding/Transaction workloads.
  </Step>

  <Step>
    If migrating to Ledger service, prepare new secrets with module-specific prefixes.
  </Step>

  <Step>
    Schedule a maintenance window.
  </Step>
</Steps>

## Breaking changes to address

***

### From v4.x: RabbitMQ dependency change

<Danger>
  The RabbitMQ chart dependency changed from Bitnami to Groundhog2k. This may lead to **PVC data loss**. Back up RabbitMQ data before upgrading.
</Danger>

**Required configuration:**

<CodeGroup>
  ```yaml values.yaml theme={null}
  rabbitmq:
    authentication:
      erlangCookie:
        value: "<32+ printable characters without spaces>"
  ```
</CodeGroup>

### Helm chart v5.x: Ledger workload introduced

<Warning>
  This section describes the historical chart v5 transition, when the Ledger workload was optional. Midaz application v4 now requires the unified Ledger. Do not use the legacy option for a new v4 deployment.
</Warning>

**Choose one of these configurations:**

**Option A: Keep legacy services (gradual migration)**

<CodeGroup>
  ```yaml values.yaml theme={null}
  ledger:
    enabled: false

  onboarding:
    enabled: true

  transaction:
    enabled: true

  rabbitmq:
    authentication:
      erlangCookie:
        value: "<32+ printable characters>"
  ```
</CodeGroup>

**Option B: Migrate to Ledger (recommended)**

<CodeGroup>
  ```yaml values.yaml theme={null}
  ledger:
    enabled: true

  onboarding:
    enabled: false

  transaction:
    enabled: false

  rabbitmq:
    authentication:
      erlangCookie:
        value: "<32+ printable characters>"
  ```
</CodeGroup>

If using Option B, create new secrets with module-specific prefixes:

* `DB_ONBOARDING_PASSWORD`, `DB_TRANSACTION_PASSWORD`
* `MONGO_ONBOARDING_PASSWORD`, `MONGO_TRANSACTION_PASSWORD`

## Upgrade command

***

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

## What changes from v3.x

***

| Change               | Source Version | Impact                                          |
| :------------------- | :------------- | :---------------------------------------------- |
| RabbitMQ Groundhog2k | v4.x           | Requires Erlang cookie, possible PVC data loss  |
| BitnamiSecure images | v4.x           | PostgreSQL, MongoDB, Valkey use hardened images |
| Official NGINX       | v4.x           | Review custom NGINX configs                     |
| Ledger service       | v5.x           | New unified service (optional but recommended)  |
| CRM integration      | v5.x           | Moves from midaz-plugins to midaz namespace     |

## Common issues

***

**RabbitMQ fails to start**

* Make sure that you set the Erlang cookie correctly (32+ printable characters, no spaces).

**RabbitMQ PVC data loss**

* Expect this after the v4.x dependency change from Bitnami to Groundhog2k. Export RabbitMQ definitions before upgrading and restore after.

**Ledger service fails to start**

* Make sure that you configure all module-specific environment variables and secrets with the new prefixes (`DB_ONBOARDING_*`, `DB_TRANSACTION_*`, etc.).

**Ingress not routing to Ledger**

* Set `ledger.enabled: true`. Do not set `migration.allowAllServices` to `true`.

**Missing secrets after enabling Ledger**

* Create new secrets with module prefixes:
  * `DB_ONBOARDING_PASSWORD` instead of `DB_PASSWORD`
  * `DB_TRANSACTION_PASSWORD` instead of `DB_PASSWORD`
  * `MONGO_ONBOARDING_PASSWORD` instead of `MONGO_PASSWORD`
  * `MONGO_TRANSACTION_PASSWORD` instead of `MONGO_PASSWORD`

**Console and NGINX overrides no longer apply**

* Chart v7.0.0 removed the Console and NGINX components entirely. `templates/console/` no longer exists. Drop any `console.*` or NGINX overrides from your values file. They are inert, and the chart schema on newer versions rejects them.