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

> Migrate your Midaz Helm deployment from v4.x to v5.x: follow the pre-upgrade checklist, run migrations, and validate the new release.

<Warning>
  This v4.x → v5.x chart migration is historical. Preserve it for existing legacy releases. It is not Midaz v4 deployment guidance.
</Warning>

## Pre-upgrade checklist

***

<Steps>
  <Step>
    Backup existing Helm releases:

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

  <Step>
    **Decision required**: Choose your deployment strategy (Ledger service or legacy Onboarding/Transaction).
  </Step>

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

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

## Breaking changes in v5.x

***

### New Ledger service available

Starting from version 5.0, the **Ledger service** is available (`ledger.enabled: false` by default). When enabled, this service combines the functionality of both `onboarding` and `transaction` modules into a single deployment.

<Warning>
  The separate `onboarding` and `transaction` services will become legacy in a future release. The unified Ledger service will become mandatory. We recommend planning your migration to the Ledger service.
</Warning>

**Default values:**

| Setting             | v4.x (before) | v5.x (after)                                |
| :------------------ | :------------ | :------------------------------------------ |
| ledger.enabled      | not available | false                                       |
| onboarding.enabled  | true          | true (auto-disabled when ledger is enabled) |
| transaction.enabled | true          | true (auto-disabled when ledger is enabled) |

**Impact when enabling Ledger:**

* The chart removes the `midaz-onboarding` and `midaz-transaction` deployments.
* The chart creates a new `midaz-ledger` deployment.
* Ingresses will automatically redirect to the Ledger service (DNS compatibility maintained).
* Environment variables and secrets structure changes (module-specific prefixes).

### App version bump

Later v5.x patches raise the app version. Check the `Chart.yaml` of the exact chart version you target.

<Note>
  Check the [app changelog](https://github.com/LerianStudio/midaz/blob/main/CHANGELOG.md) for the complete list of changes.
</Note>

## Migration options

***

### Option 1: keep using Onboarding and Transaction (gradual migration)

Add the following to your values override to maintain the current behavior:

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

  onboarding:
    enabled: true

  transaction:
    enabled: true
  ```
</CodeGroup>

This allows you to upgrade the chart version without changing your infrastructure.

### Option 2: run all services simultaneously (testing/migration period)

Use the hidden `migration.allowAllServices` flag to run all three services during the migration:

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

  onboarding:
    enabled: true

  transaction:
    enabled: true

  migration:
    allowAllServices: true
  ```
</CodeGroup>

<Warning>
  Use this mode for testing and migration only. Do not use it in production long-term.
</Warning>

### Option 3: migrate to Ledger (recommended)

Accept the new architecture and migrate to the unified Ledger service:

<Steps>
  <Step>
    **Before upgrading**: Ensure your databases are ready (same databases, new environment variable names).
  </Step>

  <Step>
    **Update secrets**: Create new secrets with module-specific prefixes (see [Configuration reference](/en/platform/deploy/midaz/midaz-configuration-reference)).
  </Step>

  <Step>
    **Upgrade**: Run helm upgrade with the new chart version.
  </Step>

  <Step>
    **Verify**: Check that the Ledger service is healthy and the ingresses work.
  </Step>
</Steps>

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

  onboarding:
    enabled: false

  transaction:
    enabled: false
  ```
</CodeGroup>

## New features in v5.x

***

### Unified Ledger service

A new Ledger service that combines `onboarding` and `transaction` modules into a single deployment.

**Key characteristics:**

* Single HTTP endpoint (port 3000 by default)
* Separate database configurations for each module
* Shared Redis and RabbitMQ connections
* New Balance Sync Worker for background processing

**New environment variables:**

<CodeGroup>
  ```yaml values.yaml theme={null}
  # Balance Sync Worker
  BALANCE_SYNC_WORKER_ENABLED: "false"
  BALANCE_SYNC_MAX_WORKERS: "5"
  ```
</CodeGroup>

<Note>
  `BALANCE_SYNC_WORKER_ENABLED` and `BALANCE_SYNC_MAX_WORKERS` are still the current names. Do not remove them. Later chart versions **add** three more keys: `BALANCE_SYNC_BATCH_SIZE` (default `50`), `BALANCE_SYNC_FLUSH_TIMEOUT_MS` (default `500`), and `BALANCE_SYNC_POLL_INTERVAL_MS` (default `50`).
</Note>

### Ingress redirection to Ledger

When you enable Ledger, existing ingresses automatically redirect traffic to the Ledger service and maintain DNS compatibility.

| ledger.enabled | migration.allowAllServices | onboarding ingress target | transaction ingress target |
| :------------- | :------------------------- | :------------------------ | :------------------------- |
| false          | false (default)            | midaz-onboarding          | midaz-transaction          |
| true           | false (default)            | midaz-ledger              | midaz-ledger               |
| true           | true                       | midaz-onboarding          | midaz-transaction          |

### CRM service integration

The chart deploys CRM in the `midaz` namespace, not in `midaz-plugins`.

<Tip>
  For more details, refer to the [CRM Documentation](/en/products/midaz/crm/crm-overview).
</Tip>

**Migration from a standalone CRM release:**

<Steps>
  <Step>
    Deploy the new CRM in the midaz namespace:

    <CodeGroup>
      ```yaml values.yaml theme={null}
      crm:
        enabled: true
        configmap:
          MONGO_HOST: "midaz-mongodb"
          MONGO_NAME: "crm"
      ```
    </CodeGroup>
  </Step>

  <Step>
    Migrate your data from the old MongoDB to the new one (if using separate databases).
  </Step>

  <Step>
    Update your ingress/DNS to point to the new CRM service.
  </Step>

  <Step>
    Remove the old CRM release from `midaz-plugins`.
  </Step>
</Steps>

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

## Rollback procedure

***

<CodeGroup>
  ```bash Shell theme={null}
  # List release history
  helm history midaz -n midaz

  # Rollback to previous version
  helm rollback midaz <REVISION> -n midaz

  # Or explicitly disable ledger
  helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
    --set ledger.enabled=false \
    --set onboarding.enabled=true \
    --set transaction.enabled=true \
    -n midaz
  ```
</CodeGroup>

## Common issues

***

**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`