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

# Configurando dependências

> Configure as dependências Helm do Midaz — Valkey, PostgreSQL, MongoDB, RabbitMQ — usando charts inclusos ou serviços gerenciados externos em produção.

O Helm Chart do Midaz possui as seguintes dependências para a instalação padrão do projeto. Todas as dependências são habilitadas por padrão.

<Tip>
  **Recomendação para produção:** Por padrão, o chart do Midaz inclui todas as dependências. Para deploys em produção, desabilite as dependências inclusas e conecte-se a serviços gerenciados (AWS RDS, Amazon MQ, etc.) para melhor confiabilidade, backups automatizados e escalabilidade.
</Tip>

<Note>
  Os exemplos abaixo mostram configurações tanto para o **Ledger** (recomendado) quanto para os serviços **Onboarding/Transaction** (legado). Escolha a configuração que corresponde ao seu deployment.
</Note>

### Valkey

* **Versão**: 2.4.7
* **Repositório**: [Bitnami](https://charts.bitnami.com/bitnami)
* **Desabilitar**: `valkey.enabled = false`

<Tip>
  **Produção:** Use Redis/Valkey gerenciado (ElastiCache, Memorystore) para alta disponibilidade e failover automático.
</Tip>

Se você tem uma instância existente de Valkey ou Redis, pode desabilitar essa dependência e configurar os componentes do Midaz para usar sua instância externa.

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

  <Tab title="Onboarding/Transaction (legado)">
    ```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

* **Versão**: 16.3.5
* **Repositório**: [Bitnami](https://charts.bitnami.com/bitnami)
* **Desabilitar**: `postgresql.enabled = false`

<Tip>
  **Produção:** Use PostgreSQL gerenciado (RDS, CloudSQL, Azure Database) com backups automatizados e recuperação point-in-time.
</Tip>

Se você tem uma instância existente de PostgreSQL, pode desabilitar essa dependência e configurar os componentes do Midaz para usar seu PostgreSQL externo.

<Tabs>
  <Tab title="Ledger (recomendado)">
    ```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 (legado)">
    ```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>

#### Job de Bootstrap para PostgreSQL externo

Ao usar um PostgreSQL externo (`postgresql.enabled: false`), este chart fornece um Job de bootstrap único que:

* Cria os bancos de dados `onboarding` e `transaction` se não existirem.
* Cria o role/usuário `midaz` se não existir e define sua senha.
* Concede privilégios de banco de dados e permissões no schema `public` para que o `midaz` possa criar tabelas.
* Aguarda conectividade com timeout de 300s.
* É idempotente: se tudo já existir, apenas imprime e encerra.

Configure no `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>
  Todos os secrets devem estar no mesmo namespace que o release. O Job tem um TTL de 300 segundos após a conclusão.
</Note>

### MongoDB

* **Versão**: 16.4.0
* **Repositório**: [Bitnami](https://charts.bitnami.com/bitnami)
* **Desabilitar**: `mongodb.enabled = false`

<Tip>
  **Produção:** Use MongoDB gerenciado (Atlas, DocumentDB) para escalabilidade automática, backups e criptografia em repouso.
</Tip>

Se você tem uma instância existente de MongoDB, pode desabilitar essa dependência e configurar os componentes do Midaz para usar seu MongoDB externo.

<Tabs>
  <Tab title="Ledger (recomendado)">
    ```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 (legado)">
    ```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

* **Versão**: 2.1.11
* **Repositório**: [Groundhog2k](https://Groundhog2k.github.io/helm-charts)
* **Desabilitar**: `rabbitmq.enabled = false`

<Tip>
  **Produção:** Use RabbitMQ gerenciado (Amazon MQ, CloudAMQP) com configuração HA para durabilidade de mensagens e failover automático.
</Tip>

Se você está usando uma instância externa de RabbitMQ, você **precisa carregar** o arquivo [load\_definitions.json](https://github.com/LerianStudio/helm/blob/main/charts/midaz/files/rabbitmq/load_definitions.json) necessário. Sem essas filas, exchanges e bindings configurados, **o Midaz não funcionará como esperado**.

Você pode carregar as definições de duas formas:

**Automaticamente**

Habilite o job de bootstrap no seu `values.yaml` para aplicar automaticamente as definições do RabbitMQ na sua instância externa:

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

**Manualmente**

Se preferir aplicar as definições manualmente, use a API HTTP do RabbitMQ:

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

O arquivo `load_definitions.json` está localizado em: `charts/midaz/files/rabbitmq/load_definitions.json`.

#### Job de Bootstrap para RabbitMQ externo

Para simplificar a configuração de um RabbitMQ externo, este chart fornece um Job único que:

* Aplica o arquivo de definições padrão via API HTTP.
* Cria/atualiza os usuários `transaction` e `consumer` com senhas customizadas.
* Aguarda conectividade AMQP com timeout de 300s.
* É idempotente: se os usuários já existirem, pula e encerra.

Configure no `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>
  Todos os secrets devem estar no mesmo namespace que o release. O Job tem um TTL de 300 segundos após a conclusão. Usuários criados: `midaz` (admin), `transaction`, `consumer`.
</Note>

#### RabbitMQ com TLS/SSL

Se o seu servidor RabbitMQ requer TLS/SSL, atualize as variáveis de ambiente do cliente para usar protocolos seguros:

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

  <Tab title="Onboarding/Transaction (legado)">
    ```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 seu próprio RabbitMQ

Se você já tem uma instância de RabbitMQ em execução, pode desabilitar a dependência integrada e apontar os componentes do Midaz para sua configuração externa.

<Tabs>
  <Tab title="Ledger (recomendado)">
    ```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 (legado)">
    ```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>