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

# Configuring dependencies

> Configure Midaz Helm dependencies — Valkey, PostgreSQL, MongoDB, RabbitMQ — using bundled charts or external managed services for production.

The Midaz Helm Chart has the following dependencies for the project's default installation. All dependencies are enabled by default.

<Tip>
  **Production recommendation:** By default, the Midaz chart bundles all dependencies. For production deployments, disable bundled dependencies and connect to managed services (AWS RDS, Amazon MQ, etc.) for better reliability, automated backups, and scaling.
</Tip>

<Note>
  The examples below show configurations for both **Ledger** (recommended) and **Onboarding/Transaction** (legacy) services. Choose the configuration that matches your deployment.
</Note>

### Valkey

* **Version**: 2.4.7
* **Repository**: [Bitnami](https://charts.bitnami.com/bitnami)
* **Disable**: `valkey.enabled = false`

<Tip>
  **Production:** Use managed Redis/Valkey (ElastiCache, Memorystore) for high availability and automatic failover.
</Tip>

If you have an existing Valkey or Redis instance, you can disable this dependency and configure Midaz components to use your external instance.

<Tabs>
  <Tab title="Ledger (recommended)">
    ```yaml theme={null}
    ledger:
      configmap:
        REDIS_HOST: {your-host}:{your-host-port}
      secrets:
        REDIS_PASSWORD: {your-host-pass}
    ```
  </Tab>

  <Tab title="Onboarding/Transaction (legacy)">
    ```yaml theme={null}
    onboarding:
      configmap:
        REDIS_HOST: {your-host}:{your-host-port}
      secrets:
        REDIS_PASSWORD: {your-host-pass}

    transaction:
      configmap:
        REDIS_HOST: {your-host}:{your-host-port}
      secrets:
        REDIS_PASSWORD: {your-host-pass}
    ```
  </Tab>
</Tabs>

### PostgreSQL

* **Version**: 16.3.0
* **Repository**: [Bitnami](https://charts.bitnami.com/bitnami)
* **Disable**: `postgresql.enabled = false`

<Tip>
  **Production:** Use managed PostgreSQL (RDS, CloudSQL, Azure Database) with automated backups and point-in-time recovery.
</Tip>

If you have an existing PostgreSQL instance, you can disable this dependency and configure Midaz components to use your external PostgreSQL.

<Tabs>
  <Tab title="Ledger (recommended)">
    ```yaml expandable theme={null}
    ledger:
      configmap:
        # Onboarding module database
        DB_ONBOARDING_HOST: {your-host}
        DB_ONBOARDING_USER: {your-host-user}
        DB_ONBOARDING_PORT: {your-host-port}
        DB_ONBOARDING_REPLICA_HOST: {your-replication-host}
        DB_ONBOARDING_REPLICA_USER: {your-replication-host-user}
        DB_ONBOARDING_REPLICA_PORT: {your-replication-host-port}
        # Transaction module database
        DB_TRANSACTION_HOST: {your-host}
        DB_TRANSACTION_USER: {your-host-user}
        DB_TRANSACTION_PORT: {your-host-port}
        DB_TRANSACTION_REPLICA_HOST: {your-replication-host}
        DB_TRANSACTION_REPLICA_USER: {your-replication-host-user}
        DB_TRANSACTION_REPLICA_PORT: {your-replication-host-port}
      secrets:
        DB_ONBOARDING_PASSWORD: {your-host-pass}
        DB_ONBOARDING_REPLICA_PASSWORD: {your-replication-host-pass}
        DB_TRANSACTION_PASSWORD: {your-host-pass}
        DB_TRANSACTION_REPLICA_PASSWORD: {your-replication-host-pass}
    ```
  </Tab>

  <Tab title="Onboarding/Transaction (legacy)">
    ```yaml expandable theme={null}
    onboarding:
      configmap:
        DB_HOST: {your-host}
        DB_USER: {your-host-user}
        DB_PORT: {your-host-port}
        DB_REPLICA_HOST: {your-replication-host}
        DB_REPLICA_USER: {your-replication-host-user}
        DB_REPLICA_PORT: {your-replication-host-port}
      secrets:
        DB_PASSWORD: {your-host-pass}
        DB_REPLICA_PASSWORD: {your-replication-host-pass}

    transaction:
      configmap:
        DB_HOST: {your-host}
        DB_USER: {your-host-user}
        DB_PORT: {your-host-port}
        DB_REPLICA_HOST: {your-replication-host}
        DB_REPLICA_USER: {your-replication-host-user}
        DB_REPLICA_PORT: {your-replication-host-port}
      secrets:
        DB_PASSWORD: {your-host-pass}
        DB_REPLICA_PASSWORD: {your-replication-host-pass}
    ```
  </Tab>
</Tabs>

#### External PostgreSQL Bootstrap Job

When using an external PostgreSQL (`postgresql.enabled: false`), this chart provides a one-shot bootstrap Job that:

* Creates the `onboarding` and `transaction` databases if they do not exist.
* Creates the `midaz` role/user if it does not exist and sets its password.
* Grants database privileges and `public` schema permissions so `midaz` can create tables.
* Waits for connectivity with a 300s timeout.
* Is idempotent: if everything already exists, it prints and exits.

Configure in `values.yaml`:

```yaml expandable theme={null}
postgresql:
  enabled: false  # disable bundled PostgreSQL to use an external one

global:
  externalPostgresDefinitions:
    enabled: true
    connection:
      host: "your-postgres-host"
      port: "5432"
    postgresAdminLogin:
      # Option A: Use an existing Secret (recommended)
      # Required keys: DB_USER_ADMIN, DB_ADMIN_PASSWORD
      useExistingSecret:
        name: "my-postgres-admin-secret"
      # Option B: Inline credentials (not recommended in production)
      # username: "postgres"
      # password: "s3cret"
    midazCredentials:
      # Option A: Use an existing Secret (recommended)
      # Required key: DB_PASSWORD_MIDAZ
      useExistingSecret:
        name: "my-midaz-credentials-secret"
      # Option B: Inline password (not recommended in production)
      # password: "midaz-password"
```

<Note>
  All secrets must be in the same namespace as the release. The Job has a TTL of 300 seconds after completion.
</Note>

### MongoDB

* **Version**: 15.4.5
* **Repository**: [Bitnami](https://charts.bitnami.com/bitnami)
* **Disable**: `mongodb.enabled = false`

<Tip>
  **Production:** Use managed MongoDB (Atlas, DocumentDB) for automatic scaling, backups, and encryption at rest.
</Tip>

If you have an existing MongoDB instance, you can disable this dependency and configure Midaz components to use your external MongoDB.

<Tabs>
  <Tab title="Ledger (recommended)">
    ```yaml theme={null}
    ledger:
      configmap:
        # Onboarding module
        MONGO_ONBOARDING_HOST: {your-host}
        MONGO_ONBOARDING_NAME: {your-host-name}
        MONGO_ONBOARDING_USER: {your-host-user}
        MONGO_ONBOARDING_PORT: {your-host-port}
        # Transaction module
        MONGO_TRANSACTION_HOST: {your-host}
        MONGO_TRANSACTION_NAME: {your-host-name}
        MONGO_TRANSACTION_USER: {your-host-user}
        MONGO_TRANSACTION_PORT: {your-host-port}
      secrets:
        MONGO_ONBOARDING_PASSWORD: {your-host-pass}
        MONGO_TRANSACTION_PASSWORD: {your-host-pass}
    ```
  </Tab>

  <Tab title="Onboarding/Transaction (legacy)">
    ```yaml theme={null}
    onboarding:
      configmap:
        MONGO_HOST: {your-host}
        MONGO_NAME: {your-host-name}
        MONGO_USER: {your-host-user}
        MONGO_PORT: {your-host-port}
      secrets:
        MONGO_PASSWORD: {your-host-pass}

    transaction:
      configmap:
        MONGO_HOST: {your-host}
        MONGO_NAME: {your-host-name}
        MONGO_USER: {your-host-user}
        MONGO_PORT: {your-host-port}
      secrets:
        MONGO_PASSWORD: {your-host-pass}
    ```
  </Tab>
</Tabs>

### RabbitMQ

* **Version**: 16.0.0
* **Repository**: [Groundhog2k](https://Groundhog2k.github.io/helm-charts)
* **Disable**: `rabbitmq.enabled = false`

<Tip>
  **Production:** Use managed RabbitMQ (Amazon MQ, CloudAMQP) with HA configuration for message durability and automatic failover.
</Tip>

If you're using an external RabbitMQ instance, you **need to load** the required [load\_definitions.json](https://github.com/LerianStudio/helm/blob/main/charts/midaz/files/rabbitmq/load_definitions.json) file. Without these queues, exchanges, and bindings in place, **Midaz won't work as expected**.

You can load the definitions in one of two ways:

**Automatically**

Enable the bootstrap job in your `values.yaml` to automatically apply the RabbitMQ definitions to your external instance:

```yaml theme={null}
global:
  externalRabbitmqDefinitions:
    enabled: true
```

**Manually**

If you prefer to apply the definitions yourself, use RabbitMQ's HTTP API:

```bash theme={null}
curl -u {user}:{pass} -X POST -H "Content-Type: application/json" \
  -d @load_definitions.json http://{host}:{port}/api/definitions
```

The `load_definitions.json` file is located at: `charts/midaz/files/rabbitmq/load_definitions.json`.

#### External RabbitMQ Bootstrap Job

To streamline external RabbitMQ setup, this chart provides a one-shot Job that:

* Applies the standard definitions file via the HTTP API.
* Creates/updates the `transaction` and `consumer` users with custom passwords.
* Waits for AMQP connectivity with a 300s timeout.
* Is idempotent: if users already exist, it skips and exits.

Configure in `values.yaml`:

```yaml expandable theme={null}
rabbitmq:
  enabled: false  # disable bundled RabbitMQ to use an external one

global:
  externalRabbitmqDefinitions:
    enabled: true
    connection:
      protocol: "http"          # http or https
      host: "your-rabbitmq-host"
      port: "15672"             # HTTP management port
      portAmqp: "5672"          # AMQP port (for connectivity check)
    rabbitmqAdminLogin:
      # Option A: Use an existing Secret (recommended)
      # Required keys: RABBITMQ_ADMIN_USER, RABBITMQ_ADMIN_PASS
      useExistingSecret:
        name: "my-rabbitmq-admin-secret"
      # Option B: Inline credentials (not recommended in production)
      # username: "admin"
      # password: "s3cret"
    appCredentials:
      # Option A: Use an existing Secret (recommended)
      # Required keys: RABBITMQ_DEFAULT_PASS, RABBITMQ_CONSUMER_PASS
      useExistingSecret:
        name: "my-rabbitmq-app-credentials"
      # Option B: Inline passwords (not recommended in production)
      # transactionPassword: "transaction-pass"
      # consumerPassword: "consumer-pass"
```

<Note>
  All secrets must be in the same namespace as the release. The Job has a TTL of 300 seconds after completion. Users created: `midaz` (admin), `transaction`, `consumer`.
</Note>

#### RabbitMQ over TLS/SSL

If your RabbitMQ server requires TLS/SSL, update the client environment variables to use secure protocols:

<Tabs>
  <Tab title="Ledger (recommended)">
    ```yaml theme={null}
    ledger:
      configmap:
        RABBITMQ_URI: "amqps"      # was "amqp"
        RABBITMQ_PROTOCOL: "https" # was "http"
    ```
  </Tab>

  <Tab title="Onboarding/Transaction (legacy)">
    ```yaml theme={null}
    onboarding:
      configmap:
        RABBITMQ_URI: "amqps"      # was "amqp"
        RABBITMQ_PROTOCOL: "https" # was "http"

    transaction:
      configmap:
        RABBITMQ_URI: "amqps"      # was "amqp"
        RABBITMQ_PROTOCOL: "https" # was "http"
    ```
  </Tab>
</Tabs>

#### Use your own RabbitMQ

If you already have a RabbitMQ instance running, you can disable the built-in dependency and point Midaz components to your external setup.

<Tabs>
  <Tab title="Ledger (recommended)">
    ```yaml theme={null}
    ledger:
      configmap:
        RABBITMQ_HOST: {your-host}
        RABBITMQ_DEFAULT_USER: {your-host-user}
        RABBITMQ_PORT_HOST: {your-host-port}
        RABBITMQ_PORT_AMQP: {your-host-amqp-port}
      secrets:
        RABBITMQ_DEFAULT_PASS: {your-host-pass}
        RABBITMQ_CONSUMER_PASS: {your-rabbitmq-consumer-password}
    ```
  </Tab>

  <Tab title="Onboarding/Transaction (legacy)">
    ```yaml theme={null}
    onboarding:
      configmap:
        RABBITMQ_HOST: {your-host}
        RABBITMQ_DEFAULT_USER: {your-host-user}
        RABBITMQ_PORT_HOST: {your-host-port}
        RABBITMQ_PORT_AMQP: {your-host-amqp-port}
      secrets:
        RABBITMQ_DEFAULT_PASS: {your-host-pass}

    transaction:
      configmap:
        RABBITMQ_HOST: {your-host}
        RABBITMQ_DEFAULT_USER: {your-host-user}
        RABBITMQ_PORT_HOST: {your-host-port}
        RABBITMQ_PORT_AMQP: {your-host-amqp-port}
      secrets:
        RABBITMQ_DEFAULT_PASS: {your-host-pass}
    ```
  </Tab>
</Tabs>