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

> Migrate your Midaz Helm deployment from v3.x to v4.x — handle breaking changes, configuration mappings, and post-upgrade verification.

## 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 before upgrading.
  </Step>

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

## Breaking changes in v4.x

### RabbitMQ dependency change to Groundhog2k

The RabbitMQ chart dependency has been replaced from Bitnami to [Groundhog2k](https://Groundhog2k.github.io/helm-charts).

<Danger>
  This change may lead to **PersistentVolumeClaim (PVC) data loss** when upgrading existing installations because the underlying StatefulSet, volume mounts, and configuration differ from the previous dependency.
</Danger>

**Important notes:**

* The Groundhog2k chart **requires a valid Erlang cookie**. Set `rabbitmq.authentication.erlangCookie.value` to a 32+ character printable string with no spaces. If missing or empty, RabbitMQ will fail to start.
* If you need to preserve existing data, back up and plan a controlled migration of PVCs and definitions before upgrading.

**Required configuration:**

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

<Note>
  This breaking change only impacts deployments that use the chart's default RabbitMQ (`rabbitmq.enabled: true`). If you run an external or managed RabbitMQ, you are not affected.
</Note>

### App version bump

Midaz has been bumped to **v3.3.1**.

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

## New features in v4.x

### BitnamiSecure images for core data services

The default images for core data services now use the BitnamiSecure repositories with the `latest` tag:

| Service    | Image Source  | Tag    |
| :--------- | :------------ | :----- |
| PostgreSQL | BitnamiSecure | latest |
| MongoDB    | BitnamiSecure | latest |
| Valkey     | BitnamiSecure | latest |

If you require pinning to a specific version, override the tag in `values.yaml`:

<CodeGroup>
  ```yaml values.yaml theme={null}
  postgresql:
    image:
      tag: "16.2.0"

  mongodb:
    image:
      tag: "7.0.5"

  valkey:
    image:
      tag: "7.2.4"
  ```
</CodeGroup>

### Official NGINX image for microfrontends

The previous Bitnami NGINX dependency was replaced with an internal template based on the official `nginx` image.

<Note>
  If you previously customized the Bitnami-based NGINX configuration, review the new templates under `templates/console/` and adjust your values accordingly.
</Note>

## Why we changed Bitnami dependencies

We moved away from Bitnami dependencies due to policy changes impacting stability and operations. For more context, see:

* [bitnami/charts#36215](https://github.com/bitnami/charts/issues/36215)
* [bitnami/containers#86191](https://github.com/bitnami/containers/issues/86191)
* [bitnami/containers#83267](https://github.com/bitnami/containers/issues/83267)

## Upgrade command

<CodeGroup>
  ```bash Shell theme={null}
  helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 4.0.0 -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
  ```
</CodeGroup>

<Warning>
  Due to the RabbitMQ dependency change, rolling back may require manual intervention to restore PVCs and data. Ensure you have backups before upgrading.
</Warning>

## 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 dependency change. Export RabbitMQ definitions before upgrading and restore after.

**NGINX configuration issues**

* Review the new NGINX templates under `templates/console/` and update your overrides.