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

# Instalando o Matcher

> Faça o deploy do Matcher em ambientes de desenvolvimento e produção usando Docker Compose, variáveis de ambiente e a stack de infraestrutura suportada.

O Matcher automatiza a reconciliação financeira entre múltiplas fontes de dados, eliminando o trabalho manual de conciliação e fornecendo uma trilha de auditoria completa para cada transação. Configurar o Matcher significa estabelecer a base para o gerenciamento de exceções, relatórios de conformidade e visibilidade operacional. Este guia apresenta o passo a passo para implantar o Matcher em ambientes de desenvolvimento e produção.

<Note>
  O Matcher está disponível para clientes licenciados; seu repositório é mantido internamente. As instruções a seguir presumem que você já tem acesso aos arquivos do projeto Matcher necessários.
</Note>

## Docker Compose (desenvolvimento)

***

Docker Compose é a abordagem recomendada para desenvolvimento local e testes.

### 1. Acesse o projeto Matcher

A partir do diretório do projeto Matcher:

```bash theme={null}
cd matcher
```

### 2. Configure o ambiente

O arquivo `docker-compose.yml` inclui valores padrão adequados para desenvolvimento local. Você pode sobrescrever qualquer valor definindo variáveis de ambiente no seu shell ou criando um arquivo `.env` na raiz do projeto.

Consulte [Variáveis de ambiente](#variáveis-de-ambiente) para detalhes sobre as configurações disponíveis.

### 3. Inicie os serviços

Inicie os serviços de infraestrutura necessários:

```bash theme={null}
docker-compose up -d postgres redis rabbitmq
```

Aguarde até que todos os serviços reportem status saudável:

```bash theme={null}
docker-compose ps
```

Inicie a aplicação do Matcher:

```bash theme={null}
docker-compose up -d app
```

Para iniciar todos os serviços de uma vez:

```bash theme={null}
docker-compose up -d
```

### 4. Verifique a instalação

Confirme que o Matcher está em execução listando os contextos de configuração (a chamada retorna um array vazio em uma instalação nova):

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" http://localhost:4018/v1/contexts
```

Se a chamada for bem-sucedida, a API do Matcher e suas dependências (PostgreSQL, Redis, RabbitMQ, object storage) estão acessíveis.

### Serviços do Docker Compose

O `docker-compose.yml` padrão inclui:

| Serviço            | Porta       | Propósito                                  |
| ------------------ | ----------- | ------------------------------------------ |
| `postgres`         | 5432        | Banco de dados PostgreSQL primário         |
| `postgres-replica` | 5433        | Réplica de leitura PostgreSQL              |
| `redis`            | 6379        | Cache Valkey (compatível com Redis)        |
| `rabbitmq`         | 5672, 15672 | RabbitMQ (AMQP e UI de gerenciamento)      |
| `seaweedfs`        | 8333, 9333  | Armazenamento de objetos compatível com S3 |
| `app`              | 4018        | API do Matcher                             |

### Desenvolvimento com hot reload

Para desenvolvimento ativo, use:

```bash theme={null}
make dev
```

Isso inicia o Matcher com live reload habilitado usando Air.

## Kubernetes / Helm (produção)

***

Implantações em produção devem usar o chart Helm oficial.

### Pré-requisitos

* Kubernetes 1.28+
* Helm 3.12+
* `kubectl` configurado para o cluster de destino

### 1. Crie um namespace

```bash theme={null}
kubectl create namespace matcher
```

### 2. Configure os valores

Crie um arquivo `values.yaml` com sua configuração de implantação:

```yaml theme={null}
replicaCount: 2

image:
 repository: lerianstudio/matcher
 tag: "latest"
 pullPolicy: IfNotPresent

service:
 type: ClusterIP
 port: 4018

ingress:
 enabled: true
 className: nginx
 hosts:
 - host: matcher.example.com
 paths:
 - path: /
 pathType: Prefix
 tls:
 - secretName: matcher-tls
 hosts:
 - matcher.example.com

postgresql:
 external: true
 host: postgres.example.com
 port: 5432
 database: matcher
 username: matcher
 existingSecret: matcher-db-credentials
 existingSecretKey: password

redis:
 external: true
 host: redis.example.com
 port: 6379
 existingSecret: matcher-redis-credentials

rabbitmq:
 external: true
 host: rabbitmq.example.com
 port: 5672
 username: matcher
 existingSecret: matcher-rabbitmq-credentials

auth:
 enabled: true
 serviceAddress: https://auth.example.com

observability:
 enabled: true
 otelExporterEndpoint: http://otel-collector:4317

resources:
 requests:
 cpu: 500m
 memory: 512Mi
 limits:
 cpu: 2000m
 memory: 2Gi
```

### 3. Crie os secrets

Crie secrets do Kubernetes para credenciais sensíveis:

```bash theme={null}
kubectl create secret generic matcher-db-credentials \
 --from-literal=password=your-db-password \
 -n matcher

kubectl create secret generic matcher-redis-credentials \
 --from-literal=password=your-redis-password \
 -n matcher

kubectl create secret generic matcher-rabbitmq-credentials \
 --from-literal=password=your-rabbitmq-password \
 -n matcher
```

### 4. Instale o chart

```bash theme={null}
helm install matcher oci://registry-1.docker.io/lerianstudio/matcher-helm \
 --version 4.1.0 \
 --namespace matcher \
 --values values.yaml
```

### 5. Verifique a implantação

```bash theme={null}
kubectl get pods -n matcher
kubectl get svc -n matcher
kubectl logs -f deployment/matcher -n matcher
```

### Atualizando

Para atualizar uma implantação existente:

```bash theme={null}
helm upgrade matcher oci://registry-1.docker.io/lerianstudio/matcher-helm \
 --version 4.1.0 \
 --namespace matcher \
 --values values.yaml
```

## Variáveis de ambiente

***

O Matcher é configurado inteiramente através de variáveis de ambiente.

### Aplicação

| Variável                | Padrão        | Descrição                                                               |
| ----------------------- | ------------- | ----------------------------------------------------------------------- |
| `ENV_NAME`              | `development` | Nome do ambiente de runtime                                             |
| `LOG_LEVEL`             | `info`        | Verbosidade do log                                                      |
| `DEPLOYMENT_MODE`       | `local`       | Modo de deploy (`local`, `byoc`, `saas`)                                |
| `SERVER_ADDRESS`        | `:4018`       | Endereço de bind do servidor HTTP                                       |
| `HTTP_BODY_LIMIT_BYTES` | `104857600`   | Tamanho máximo do corpo da requisição em buffer (bytes, padrão 100 MiB) |

### CORS

| Variável               | Padrão                                                  | Descrição                     |
| ---------------------- | ------------------------------------------------------- | ----------------------------- |
| `CORS_ALLOWED_ORIGINS` | `http://localhost:3000`                                 | Origens permitidas            |
| `CORS_ALLOWED_METHODS` | `GET,POST,PUT,PATCH,DELETE,OPTIONS`                     | Métodos HTTP permitidos       |
| `CORS_ALLOWED_HEADERS` | `Origin,Content-Type,Accept,Authorization,X-Request-ID` | Headers de request permitidos |

### Banco de dados (PostgreSQL)

| Variável                           | Padrão                 | Descrição                                 |
| ---------------------------------- | ---------------------- | ----------------------------------------- |
| `POSTGRES_HOST`                    | `localhost`            | Host do banco primário                    |
| `POSTGRES_PORT`                    | `5432`                 | Porta do banco primário                   |
| `POSTGRES_USER`                    | `matcher`              | Usuário                                   |
| `POSTGRES_PASSWORD`                | `matcher_dev_password` | Senha                                     |
| `POSTGRES_DB`                      | `matcher`              | Nome do banco de dados                    |
| `POSTGRES_SSLMODE`                 | `disable`              | Modo SSL                                  |
| `POSTGRES_TLS_REQUIRED`            | `false`                | Exigir TLS no bootstrap                   |
| `POSTGRES_MAX_OPEN_CONNS`          | `25`                   | Máximo de conexões abertas                |
| `POSTGRES_MAX_IDLE_CONNS`          | `5`                    | Máximo de conexões ociosas                |
| `POSTGRES_CONN_MAX_LIFETIME_MINS`  | `30`                   | Tempo máximo de vida da conexão (minutos) |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | `5`                    | Tempo máximo ocioso da conexão (minutos)  |
| `POSTGRES_CONNECT_TIMEOUT_SEC`     | `10`                   | Timeout de conexão (segundos)             |
| `POSTGRES_QUERY_TIMEOUT_SEC`       | `30`                   | Timeout de query (segundos)               |
| `MIGRATIONS_PATH`                  | `migrations`           | Caminho dos arquivos de migração          |

### Réplica do banco de dados (PostgreSQL)

| Variável                        | Padrão  | Descrição                 |
| ------------------------------- | ------- | ------------------------- |
| `POSTGRES_REPLICA_HOST`         | —       | Host da réplica           |
| `POSTGRES_REPLICA_PORT`         | —       | Porta da réplica          |
| `POSTGRES_REPLICA_USER`         | —       | Usuário da réplica        |
| `POSTGRES_REPLICA_PASSWORD`     | —       | Senha da réplica          |
| `POSTGRES_REPLICA_DB`           | —       | Nome do banco da réplica  |
| `POSTGRES_REPLICA_SSLMODE`      | —       | Modo SSL da réplica       |
| `POSTGRES_REPLICA_TLS_REQUIRED` | `false` | Exigir TLS para a réplica |

### Cache (Redis)

| Variável                 | Padrão           | Descrição                          |
| ------------------------ | ---------------- | ---------------------------------- |
| `REDIS_HOST`             | `localhost:6379` | Endereço do Redis (host:porta)     |
| `REDIS_MASTER_NAME`      | —                | Nome do master Sentinel            |
| `REDIS_PASSWORD`         | —                | Senha                              |
| `REDIS_DB`               | `0`              | Índice do banco de dados           |
| `REDIS_TLS`              | `false`          | Habilitar TLS                      |
| `REDIS_TLS_REQUIRED`     | `false`          | Exigir TLS no bootstrap            |
| `REDIS_CA_CERT`          | —                | Caminho do certificado CA          |
| `REDIS_POOL_SIZE`        | `10`             | Tamanho do pool de conexões        |
| `REDIS_MIN_IDLE_CONNS`   | `2`              | Mínimo de conexões ociosas         |
| `REDIS_READ_TIMEOUT_MS`  | `3000`           | Timeout de leitura (milissegundos) |
| `REDIS_WRITE_TIMEOUT_MS` | `3000`           | Timeout de escrita (milissegundos) |
| `REDIS_DIAL_TIMEOUT_MS`  | `5000`           | Timeout de conexão (milissegundos) |

### Mensageria (RabbitMQ)

| Variável                               | Padrão                   | Descrição                                      |
| -------------------------------------- | ------------------------ | ---------------------------------------------- |
| `RABBITMQ_URI`                         | `amqp`                   | Esquema URI (`amqp` ou `amqps`)                |
| `RABBITMQ_HOST`                        | `localhost`              | Host do broker                                 |
| `RABBITMQ_PORT`                        | `5672`                   | Porta do broker                                |
| `RABBITMQ_USER`                        | `matcher_admin`          | Usuário                                        |
| `RABBITMQ_PASSWORD`                    | `matcher_dev_password`   | Senha                                          |
| `RABBITMQ_VHOST`                       | `/`                      | Virtual host                                   |
| `RABBITMQ_HEALTH_URL`                  | `http://localhost:15672` | URL da API de gerenciamento para health checks |
| `RABBITMQ_ALLOW_INSECURE_HEALTH_CHECK` | `false`                  | Permitir health check HTTP (sem TLS)           |
| `RABBITMQ_TLS_REQUIRED`                | `false`                  | Exigir TLS no bootstrap                        |

### Autenticação

| Variável              | Padrão  | Descrição                                                                                                    |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `PLUGIN_AUTH_ENABLED` | `false` | Habilitar autenticação                                                                                       |
| `PLUGIN_AUTH_ADDRESS` | —       | URL do serviço de auth (a validação do token é delegada aqui; o Matcher não guarda nenhum segredo JWT local) |

### Armazenamento de objetos (compatível com S3)

| Variável                                 | Padrão                  | Descrição                        |
| ---------------------------------------- | ----------------------- | -------------------------------- |
| `OBJECT_STORAGE_ENDPOINT`                | `http://localhost:8333` | URL do endpoint S3               |
| `OBJECT_STORAGE_REGION`                  | `us-east-1`             | Região S3                        |
| `OBJECT_STORAGE_BUCKET`                  | `matcher-exports`       | Bucket para exportações          |
| `OBJECT_STORAGE_ACCESS_KEY_ID`           | —                       | ID da chave de acesso            |
| `OBJECT_STORAGE_SECRET_ACCESS_KEY`       | —                       | Chave de acesso secreta          |
| `OBJECT_STORAGE_USE_PATH_STYLE`          | `true`                  | Usar endereçamento path-style    |
| `OBJECT_STORAGE_ALLOW_INSECURE_ENDPOINT` | `false`                 | Permitir endpoint HTTP (sem TLS) |
| `OBJECT_STORAGE_TLS_REQUIRED`            | `false`                 | Exigir TLS no bootstrap          |

### Observabilidade

| Variável                               | Padrão                            | Descrição                             |
| -------------------------------------- | --------------------------------- | ------------------------------------- |
| `ENABLE_TELEMETRY`                     | `false`                           | Habilitar OpenTelemetry               |
| `OTEL_RESOURCE_SERVICE_NAME`           | `matcher`                         | Nome do serviço para traces/métricas  |
| `OTEL_LIBRARY_NAME`                    | `github.com/LerianStudio/matcher` | Nome da biblioteca de instrumentação  |
| `OTEL_RESOURCE_SERVICE_VERSION`        | `1.1.0`                           | Versão do serviço                     |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | `development`                     | Label do ambiente de deploy           |
| `OTEL_EXPORTER_OTLP_ENDPOINT`          | `localhost:4317`                  | Endpoint do coletor OTLP              |
| `DB_METRICS_INTERVAL_SEC`              | `15`                              | Intervalo de coleta de métricas do DB |

### TLS

| Variável                  | Padrão  | Descrição                                              |
| ------------------------- | ------- | ------------------------------------------------------ |
| `SERVER_TLS_CERT_FILE`    | —       | Caminho do certificado TLS                             |
| `SERVER_TLS_KEY_FILE`     | —       | Caminho da chave privada TLS                           |
| `TLS_TERMINATED_UPSTREAM` | `false` | Confiar na terminação TLS upstream (ex: load balancer) |
| `TRUSTED_PROXIES`         | —       | Ranges CIDR de proxies confiáveis                      |

### Limitação de taxa

| Variável                         | Padrão | Descrição                                      |
| -------------------------------- | ------ | ---------------------------------------------- |
| `RATE_LIMIT_ENABLED`             | `true` | Habilitar limitação de taxa global             |
| `RATE_LIMIT_MAX`                 | `100`  | Máximo de requisições por janela               |
| `RATE_LIMIT_EXPIRY_SEC`          | `60`   | Janela de limitação de taxa (segundos)         |
| `EXPORT_RATE_LIMIT_MAX`          | `10`   | Máximo de requisições de exportação por janela |
| `EXPORT_RATE_LIMIT_EXPIRY_SEC`   | `60`   | Janela de limitação de exportação (segundos)   |
| `DISPATCH_RATE_LIMIT_MAX`        | `50`   | Máximo de requisições de despacho por janela   |
| `DISPATCH_RATE_LIMIT_EXPIRY_SEC` | `60`   | Janela de limitação de despacho (segundos)     |
| `ADMIN_RATE_LIMIT_MAX`           | `30`   | Máximo de requisições admin por janela         |
| `ADMIN_RATE_LIMIT_EXPIRY_SEC`    | `60`   | Janela de limitação admin (segundos)           |

### Swagger

| Variável          | Padrão  | Descrição                                        |
| ----------------- | ------- | ------------------------------------------------ |
| `SWAGGER_ENABLED` | `false` | Habilitar Swagger UI                             |
| `SWAGGER_HOST`    | —       | Sobrescrever host da spec Swagger                |
| `SWAGGER_SCHEMES` | `https` | Esquemas da spec Swagger (separados por vírgula) |

### Idempotência

| Variável                        | Padrão | Descrição                                                          |
| ------------------------------- | ------ | ------------------------------------------------------------------ |
| `IDEMPOTENCY_RETRY_WINDOW_SEC`  | `300`  | Janela para retentar requisições idempotentes com falha (segundos) |
| `IDEMPOTENCY_SUCCESS_TTL_HOURS` | `168`  | Tempo de cache de chaves de idempotência concluídas (horas)        |
| `IDEMPOTENCY_HMAC_SECRET`       | —      | Segredo HMAC para assinar chaves de idempotência (mín 32 bytes)    |

### Deduplicação

| Variável         | Padrão | Descrição                                 |
| ---------------- | ------ | ----------------------------------------- |
| `DEDUPE_TTL_SEC` | `3600` | TTL das chaves de deduplicação (segundos) |

### Outbox

| Variável                       | Padrão | Descrição                                               |
| ------------------------------ | ------ | ------------------------------------------------------- |
| `OUTBOX_RETRY_WINDOW_SEC`      | `300`  | Cooldown antes de retentar eventos com falha (segundos) |
| `OUTBOX_DISPATCH_INTERVAL_SEC` | `2`    | Intervalo de polling do dispatcher (segundos)           |

### Workers

| Variável                          | Padrão | Descrição                                                |
| --------------------------------- | ------ | -------------------------------------------------------- |
| `EXPORT_WORKER_ENABLED`           | `true` | Habilitar worker de exportação                           |
| `EXPORT_WORKER_POLL_INTERVAL_SEC` | `5`    | Intervalo de polling do worker de exportação (segundos)  |
| `EXPORT_WORKER_PAGE_SIZE`         | `1000` | Linhas por página de exportação                          |
| `EXPORT_PRESIGN_EXPIRY_SEC`       | `3600` | Validade da URL pré-assinada para exportações (segundos) |
| `CLEANUP_WORKER_ENABLED`          | `true` | Habilitar worker de limpeza                              |
| `CLEANUP_WORKER_INTERVAL_SEC`     | `3600` | Intervalo do worker de limpeza (segundos)                |
| `CLEANUP_WORKER_BATCH_SIZE`       | `100`  | Tamanho do lote de limpeza                               |
| `CLEANUP_WORKER_GRACE_PERIOD_SEC` | `3600` | Período de graça antes da limpeza (segundos)             |
| `WEBHOOK_TIMEOUT_SEC`             | `30`   | Timeout de despacho de webhook (segundos)                |
| `CALLBACK_RATE_LIMIT_PER_MIN`     | `60`   | Máximo de callbacks por sistema externo por minuto       |

### Agendador

| Variável                 | Padrão | Descrição                                         |
| ------------------------ | ------ | ------------------------------------------------- |
| `SCHEDULER_INTERVAL_SEC` | `60`   | Intervalo de polling do agendador cron (segundos) |

### Arquivamento

| Variável                         | Padrão                | Descrição                                             |
| -------------------------------- | --------------------- | ----------------------------------------------------- |
| `ARCHIVAL_WORKER_ENABLED`        | `false`               | Habilitar worker de arquivamento de logs de auditoria |
| `ARCHIVAL_WORKER_INTERVAL_HOURS` | `24`                  | Intervalo de execução do arquivamento (horas)         |
| `ARCHIVAL_HOT_RETENTION_DAYS`    | `90`                  | Dias para manter dados em armazenamento quente        |
| `ARCHIVAL_WARM_RETENTION_MONTHS` | `24`                  | Meses para manter dados em armazenamento morno        |
| `ARCHIVAL_COLD_RETENTION_MONTHS` | `84`                  | Meses para manter dados em armazenamento frio         |
| `ARCHIVAL_BATCH_SIZE`            | `5000`                | Linhas por lote de arquivamento                       |
| `ARCHIVAL_STORAGE_BUCKET`        | `matcher-archives`    | Bucket S3 para arquivos                               |
| `ARCHIVAL_STORAGE_PREFIX`        | `archives/audit-logs` | Prefixo de chave S3 para arquivos                     |
| `ARCHIVAL_STORAGE_CLASS`         | `GLACIER`             | Classe de armazenamento S3 para arquivos              |
| `ARCHIVAL_PARTITION_LOOKAHEAD`   | `3`                   | Quantidade de partições antecipadas                   |
| `ARCHIVAL_PRESIGN_EXPIRY_SEC`    | `3600`                | Validade da URL pré-assinada para arquivos (segundos) |

### Fetcher / Discovery

Essas configurações controlam o Discovery, que lê bancos de dados externos através de um motor de extração em processo embarcado no Matcher — não um serviço em rede separado. Veja [Discovery](/pt/matcher/integrations/matcher-discovery) para entender como funciona.

| Variável                         | Padrão       | Descrição                                                                           |
| -------------------------------- | ------------ | ----------------------------------------------------------------------------------- |
| `FETCHER_DISCOVERY_INTERVAL_SEC` | `60`         | Intervalo de polling de discovery (segundos)                                        |
| `FETCHER_SCHEMA_CACHE_TTL_SEC`   | `300`        | TTL do cache de schema (segundos)                                                   |
| `FETCHER_EXTRACTION_TIMEOUT_SEC` | `600`        | Timeout de extração (segundos)                                                      |
| `FETCHER_MAX_EXTRACTION_BYTES`   | `2147483648` | Tamanho máximo do payload de extração (bytes, padrão 2 GiB)                         |
| `APP_ENC_KEY`                    | —            | Chave mestra codificada em Base64 para o protetor de credenciais do motor embarcado |

### Infraestrutura

| Variável                    | Padrão | Descrição                                                  |
| --------------------------- | ------ | ---------------------------------------------------------- |
| `INFRA_CONNECT_TIMEOUT_SEC` | `30`   | Timeout de conexão de infraestrutura no startup (segundos) |
| `HEALTH_CHECK_TIMEOUT_SEC`  | `5`    | Timeout legado por verificação (segundos)                  |
| `HEALTH_CHECK_TIMEOUT_MS`   | `800`  | Timeout por verificação (milissegundos, preferido)         |

<Note>
  Para configurações de implantação multi-tenant, veja [Modo Multi-Tenant](/pt/matcher/configuration/matcher-multi-tenant). Para gerenciamento de configuração em runtime, veja [Configuração em Runtime (Systemplane)](/pt/matcher/configuration/matcher-systemplane).
</Note>

## Verificar a instalação

***

Valide que o Matcher está operando corretamente exercitando a API:

```bash theme={null}
curl -X POST http://localhost:4018/v1/contexts \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Contexto de Teste",
   "type": "1:1"
 }'
```

Uma resposta bem-sucedida confirma que a API e suas dependências (banco de dados, cache, message broker, object storage) estão acessíveis. Os probes de liveness e readiness do Kubernetes são configurados no nível do cluster pela orquestração; você não precisa chamá-los diretamente.

## Solução de problemas

***

### Problemas comuns

<AccordionGroup>
  <Accordion title="Conexão recusada ao PostgreSQL">
    * **Causa:** PostgreSQL não está em execução ou inacessível.
    * **Resolução:**

    1. Verifique se o PostgreSQL está em execução: `docker-compose ps postgres`
    2. Verifique os valores de conexão em `.env`
    3. Teste a conectividade: `nc -zv localhost 5432`
    4. Revise os logs: `docker-compose logs postgres`
  </Accordion>

  <Accordion title="Timeout de conexão Redis">
    * **Causa:** Redis não está em execução ou as credenciais estão incorretas.
    * **Resolução:**

    1. Verifique se o Redis está em execução: `docker-compose ps redis`
    2. Confirme `REDIS_PASSWORD`
    3. Teste a conectividade: `redis-cli -h localhost ping`
  </Accordion>

  <Accordion title="Filas do RabbitMQ não criadas">
    * **Causa:** RabbitMQ ainda está inicializando ou o virtual host está faltando.
    * **Resolução:**

    1. Aguarde até que o RabbitMQ esteja saudável
    2. Acesse a UI de gerenciamento em [http://localhost:15672](http://localhost:15672)
    3. Verifique `RABBITMQ_VHOST`
  </Accordion>

  <Accordion title="Erros de autenticação">
    * **Causa:** Serviço de auth está inacessível ou o token é inválido.
    * **Resolução:**

    1. Verifique `PLUGIN_AUTH_ADDRESS`
    2. Desabilite auth para desenvolvimento: `PLUGIN_AUTH_ENABLED=false`
    3. Revise os logs do serviço de auth
  </Accordion>

  <Accordion title="Migration falhou">
    * **Causa:** Migrations do banco de dados não puderam ser aplicadas.
    * **Resolução:**

    1. Verifique o status das migrations: `make migrate-status`
    2. Revise os logs das migrations
    3. Aplique migrations manualmente: `make migrate-up`
    4. Inspecione a tabela `schema_migrations` se necessário
  </Accordion>

  <Accordion title="Erros de migração do banco de dados ao atualizar a partir da branch main">
    Ao atualizar a partir da branch main, as migrations 000020 e 000021 são executadas automaticamente. A migration 000020 renomeia as chaves de configuração do systemplane para padronização entre produtos. A migration 000021 converte a coluna `external_system` de um tipo enum para VARCHAR(255), permitindo identificadores arbitrários de sistema externo. Se as migrations falharem, verifique a tabela `schema_migrations` e certifique-se de que não existem alterações manuais conflitantes.
  </Accordion>
</AccordionGroup>

### Visualizando logs

```bash theme={null}
docker-compose logs -f app
kubectl logs -f deployment/matcher -n matcher
```

### Modo debug

Habilite logging de debug para visibilidade adicional:

```bash theme={null}
LOG_LEVEL=debug docker-compose up app
```

## Próximos passos

***

<Card title="Início rápido" icon="rocket" href="/pt/matcher/getting-started/matcher-quick-start" horizontal>
  Execute sua primeira conciliação.
</Card>

<Card title="Configuração" icon="gear" href="/pt/matcher/configuration/matcher-contexts-and-sources" horizontal>
  Configure contextos, fontes e regras de match.
</Card>