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

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**: Choose your deployment strategy - Ledger service or legacy Onboarding/Transaction (v5.x breaking change).
  </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>

### From v5.x: new Ledger service

<Warning>
  The unified Ledger service is available and will become mandatory in a future release. Plan your migration strategy.
</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**

* Ensure the Erlang cookie is set correctly (32+ printable characters, no spaces).

**RabbitMQ PVC data loss**

* This is expected due to the v4.x dependency change from Bitnami to Groundhog2k. Export RabbitMQ definitions before upgrading and restore after.

**Ledger service fails to start**

* Verify that all module-specific environment variables and secrets are configured with the new prefixes (`DB_ONBOARDING_*`, `DB_TRANSACTION_*`, etc.).

**Ingress not routing to Ledger**

* Ensure `ledger.enabled: true` and `migration.allowAllServices` is not set 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`

**NGINX configuration issues**

* The v4.x upgrade replaced Bitnami NGINX with official NGINX templates. Review the new templates under `templates/console/` and update your overrides.