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

# Instalación de Matcher

> Despliega Matcher en desarrollo y producción usando Docker Compose, variables de entorno y la pila de infraestructura compatible.

Matcher automatiza la conciliación financiera entre múltiples fuentes de datos, eliminando el trabajo de conciliación manual y proporcionando un registro de auditoría completo para cada transacción. Configurar Matcher significa establecer la base para la gestión de excepciones, los informes de cumplimiento y la visibilidad operacional. Esta guía te explica cómo desplegar Matcher en entornos de desarrollo y producción.

<Note>
  Matcher está disponible para clientes con licencia; su repositorio se mantiene internamente. Las instrucciones siguientes asumen que ya tienes acceso a los archivos del proyecto Matcher necesarios.
</Note>

## Docker Compose (desarrollo)

***

Docker Compose es el enfoque recomendado para desarrollo local y pruebas.

### 1. Acceder al proyecto Matcher

Desde el directorio del proyecto Matcher:

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

### 2. Configurar el entorno

El archivo `docker-compose.yml` incluye valores predeterminados adecuados para desarrollo local. Puedes sobrescribir cualquier valor definiendo variables de entorno en tu shell o creando un archivo `.env` en la raíz del proyecto.

Consulta [Variables de entorno](#variables-de-entorno) para detalles sobre las configuraciones disponibles.

### 3. Iniciar servicios

Inicia los servicios de infraestructura requeridos:

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

Espera hasta que todos los servicios reporten un estado saludable:

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

Inicia la aplicación de Matcher:

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

Para iniciar todos los servicios a la vez:

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

### 4. Verificar la instalación

Confirma que Matcher está ejecutándose listando los contextos de configuración (la llamada retorna un array vacío en una instalación nueva):

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

Si la llamada es exitosa, la API de Matcher y sus dependencias (PostgreSQL, Redis, RabbitMQ, object storage) están accesibles.

### Servicios de Docker Compose

El `docker-compose.yml` por defecto incluye:

| Servicio           | Puerto      | Propósito                                   |
| ------------------ | ----------- | ------------------------------------------- |
| `postgres`         | 5432        | Base de datos PostgreSQL primaria           |
| `postgres-replica` | 5433        | Réplica de lectura PostgreSQL               |
| `redis`            | 6379        | Caché Valkey (compatible con Redis)         |
| `rabbitmq`         | 5672, 15672 | RabbitMQ (AMQP e interfaz de gestión)       |
| `seaweedfs`        | 8333, 9333  | Almacenamiento de objetos compatible con S3 |
| `app`              | 4018        | API de Matcher                              |

### Desarrollo con recarga en caliente

Para desarrollo activo, usa:

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

Esto inicia Matcher con recarga en vivo habilitada usando Air.

## Kubernetes / Helm (producción)

***

Los despliegues de producción deben usar el chart oficial de Helm.

### Prerrequisitos

* Kubernetes 1.28+
* Helm 3.12+
* `kubectl` configurado para el clúster destino

### 1. Crear un namespace

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

### 2. Configurar valores

Crea un archivo `values.yaml` con tu configuración de despliegue:

```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. Crear secrets

Crea Kubernetes secrets para credenciales sensibles:

```bash theme={null}
kubectl create secret generic matcher-db-credentials \
 --from-literal=password=tu-contraseña-de-db \
 -n matcher

kubectl create secret generic matcher-redis-credentials \
 --from-literal=password=tu-contraseña-de-redis \
 -n matcher

kubectl create secret generic matcher-rabbitmq-credentials \
 --from-literal=password=tu-contraseña-de-rabbitmq \
 -n matcher
```

### 4. Instalar el 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. Verificar el despliegue

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

### Actualización

Para actualizar un despliegue existente:

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

## Variables de entorno

***

Matcher se configura completamente a través de variables de entorno.

### Aplicación

| Variable                | Por defecto   | Descripción                                                                            |
| ----------------------- | ------------- | -------------------------------------------------------------------------------------- |
| `ENV_NAME`              | `development` | Nombre del entorno de ejecución                                                        |
| `LOG_LEVEL`             | `info`        | Nivel de verbosidad del log                                                            |
| `DEPLOYMENT_MODE`       | `local`       | Modo de despliegue (`local`, `byoc`, `saas`)                                           |
| `SERVER_ADDRESS`        | `:4018`       | Dirección de bind del servidor HTTP                                                    |
| `HTTP_BODY_LIMIT_BYTES` | `104857600`   | Tamaño máximo del cuerpo de solicitud almacenado en búfer (bytes, 100 MiB por defecto) |

### CORS

| Variable               | Por defecto                                             | Descripción                     |
| ---------------------- | ------------------------------------------------------- | ------------------------------- |
| `CORS_ALLOWED_ORIGINS` | `http://localhost:3000`                                 | Orígenes permitidos             |
| `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 solicitud permitidos |

### Base de datos (PostgreSQL)

| Variable                           | Por defecto            | Descripción                                     |
| ---------------------------------- | ---------------------- | ----------------------------------------------- |
| `POSTGRES_HOST`                    | `localhost`            | Host de la base de datos primaria               |
| `POSTGRES_PORT`                    | `5432`                 | Puerto de la base de datos primaria             |
| `POSTGRES_USER`                    | `matcher`              | Nombre de usuario                               |
| `POSTGRES_PASSWORD`                | `matcher_dev_password` | Contraseña                                      |
| `POSTGRES_DB`                      | `matcher`              | Nombre de la base de datos                      |
| `POSTGRES_SSLMODE`                 | `disable`              | Modo SSL                                        |
| `POSTGRES_TLS_REQUIRED`            | `false`                | Exigir TLS en el bootstrap                      |
| `POSTGRES_MAX_OPEN_CONNS`          | `25`                   | Máximo de conexiones abiertas                   |
| `POSTGRES_MAX_IDLE_CONNS`          | `5`                    | Máximo de conexiones inactivas                  |
| `POSTGRES_CONN_MAX_LIFETIME_MINS`  | `30`                   | Tiempo máximo de vida de la conexión (minutos)  |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | `5`                    | Tiempo máximo inactivo de la conexión (minutos) |
| `POSTGRES_CONNECT_TIMEOUT_SEC`     | `10`                   | Timeout de conexión (segundos)                  |
| `POSTGRES_QUERY_TIMEOUT_SEC`       | `30`                   | Timeout de consulta (segundos)                  |
| `MIGRATIONS_PATH`                  | `migrations`           | Ruta de archivos de migración                   |

### Réplica de base de datos (PostgreSQL)

| Variable                        | Por defecto | Descripción                        |
| ------------------------------- | ----------- | ---------------------------------- |
| `POSTGRES_REPLICA_HOST`         | —           | Host de la réplica                 |
| `POSTGRES_REPLICA_PORT`         | —           | Puerto de la réplica               |
| `POSTGRES_REPLICA_USER`         | —           | Usuario de la réplica              |
| `POSTGRES_REPLICA_PASSWORD`     | —           | Contraseña de la réplica           |
| `POSTGRES_REPLICA_DB`           | —           | Nombre de la base de datos réplica |
| `POSTGRES_REPLICA_SSLMODE`      | —           | Modo SSL de la réplica             |
| `POSTGRES_REPLICA_TLS_REQUIRED` | `false`     | Exigir TLS para la réplica         |

### Caché (Redis)

| Variable                 | Por defecto      | Descripción                         |
| ------------------------ | ---------------- | ----------------------------------- |
| `REDIS_HOST`             | `localhost:6379` | Dirección de Redis (host:puerto)    |
| `REDIS_MASTER_NAME`      | —                | Nombre del master Sentinel          |
| `REDIS_PASSWORD`         | —                | Contraseña                          |
| `REDIS_DB`               | `0`              | Índice de base de datos             |
| `REDIS_TLS`              | `false`          | Habilitar TLS                       |
| `REDIS_TLS_REQUIRED`     | `false`          | Exigir TLS en el bootstrap          |
| `REDIS_CA_CERT`          | —                | Ruta del certificado CA             |
| `REDIS_POOL_SIZE`        | `10`             | Tamaño del pool de conexiones       |
| `REDIS_MIN_IDLE_CONNS`   | `2`              | Mínimo de conexiones inactivas      |
| `REDIS_READ_TIMEOUT_MS`  | `3000`           | Timeout de lectura (milisegundos)   |
| `REDIS_WRITE_TIMEOUT_MS` | `3000`           | Timeout de escritura (milisegundos) |
| `REDIS_DIAL_TIMEOUT_MS`  | `5000`           | Timeout de conexión (milisegundos)  |

### Mensajería (RabbitMQ)

| Variable                               | Por defecto              | Descripción                                 |
| -------------------------------------- | ------------------------ | ------------------------------------------- |
| `RABBITMQ_URI`                         | `amqp`                   | Esquema URI (`amqp` o `amqps`)              |
| `RABBITMQ_HOST`                        | `localhost`              | Host del broker                             |
| `RABBITMQ_PORT`                        | `5672`                   | Puerto del broker                           |
| `RABBITMQ_USER`                        | `matcher_admin`          | Nombre de usuario                           |
| `RABBITMQ_PASSWORD`                    | `matcher_dev_password`   | Contraseña                                  |
| `RABBITMQ_VHOST`                       | `/`                      | Host virtual                                |
| `RABBITMQ_HEALTH_URL`                  | `http://localhost:15672` | URL de la API de gestión para health checks |
| `RABBITMQ_ALLOW_INSECURE_HEALTH_CHECK` | `false`                  | Permitir health check HTTP (sin TLS)        |
| `RABBITMQ_TLS_REQUIRED`                | `false`                  | Exigir TLS en el bootstrap                  |

### Autenticación

| Variable              | Por defecto | Descripción                                                                                                            |
| --------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| `PLUGIN_AUTH_ENABLED` | `false`     | Habilitar autenticación                                                                                                |
| `PLUGIN_AUTH_ADDRESS` | —           | URL del servicio de autenticación (la validación del token se delega aquí; Matcher no guarda ningún secreto JWT local) |

### Almacenamiento de objetos (compatible con S3)

| Variable                                 | Por defecto             | Descripción                      |
| ---------------------------------------- | ----------------------- | -------------------------------- |
| `OBJECT_STORAGE_ENDPOINT`                | `http://localhost:8333` | URL del endpoint S3              |
| `OBJECT_STORAGE_REGION`                  | `us-east-1`             | Región S3                        |
| `OBJECT_STORAGE_BUCKET`                  | `matcher-exports`       | Bucket para exportaciones        |
| `OBJECT_STORAGE_ACCESS_KEY_ID`           | —                       | ID de clave de acceso            |
| `OBJECT_STORAGE_SECRET_ACCESS_KEY`       | —                       | Clave de acceso secreta          |
| `OBJECT_STORAGE_USE_PATH_STYLE`          | `true`                  | Usar direccionamiento path-style |
| `OBJECT_STORAGE_ALLOW_INSECURE_ENDPOINT` | `false`                 | Permitir endpoint HTTP (sin TLS) |
| `OBJECT_STORAGE_TLS_REQUIRED`            | `false`                 | Exigir TLS en el bootstrap       |

### Observabilidad

| Variable                               | Por defecto                       | Descripción                                |
| -------------------------------------- | --------------------------------- | ------------------------------------------ |
| `ENABLE_TELEMETRY`                     | `false`                           | Habilitar OpenTelemetry                    |
| `OTEL_RESOURCE_SERVICE_NAME`           | `matcher`                         | Nombre del servicio para trazas/métricas   |
| `OTEL_LIBRARY_NAME`                    | `github.com/LerianStudio/matcher` | Nombre de la biblioteca de instrumentación |
| `OTEL_RESOURCE_SERVICE_VERSION`        | `1.1.0`                           | Versión del servicio                       |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | `development`                     | Etiqueta del entorno de despliegue         |
| `OTEL_EXPORTER_OTLP_ENDPOINT`          | `localhost:4317`                  | Endpoint del colector OTLP                 |
| `DB_METRICS_INTERVAL_SEC`              | `15`                              | Intervalo de recolección de métricas de DB |

### TLS

| Variable                  | Por defecto | Descripción                                             |
| ------------------------- | ----------- | ------------------------------------------------------- |
| `SERVER_TLS_CERT_FILE`    | —           | Ruta del certificado TLS                                |
| `SERVER_TLS_KEY_FILE`     | —           | Ruta de la clave privada TLS                            |
| `TLS_TERMINATED_UPSTREAM` | `false`     | Confiar en terminación TLS upstream (ej: load balancer) |
| `TRUSTED_PROXIES`         | —           | Rangos CIDR de proxies de confianza                     |

### Limitación de tasa

| Variable                         | Por defecto | Descripción                                      |
| -------------------------------- | ----------- | ------------------------------------------------ |
| `RATE_LIMIT_ENABLED`             | `true`      | Habilitar limitación de tasa global              |
| `RATE_LIMIT_MAX`                 | `100`       | Máximo de solicitudes por ventana                |
| `RATE_LIMIT_EXPIRY_SEC`          | `60`        | Ventana de limitación de tasa (segundos)         |
| `EXPORT_RATE_LIMIT_MAX`          | `10`        | Máximo de solicitudes de exportación por ventana |
| `EXPORT_RATE_LIMIT_EXPIRY_SEC`   | `60`        | Ventana de limitación de exportación (segundos)  |
| `DISPATCH_RATE_LIMIT_MAX`        | `50`        | Máximo de solicitudes de despacho por ventana    |
| `DISPATCH_RATE_LIMIT_EXPIRY_SEC` | `60`        | Ventana de limitación de despacho (segundos)     |
| `ADMIN_RATE_LIMIT_MAX`           | `30`        | Máximo de solicitudes admin por ventana          |
| `ADMIN_RATE_LIMIT_EXPIRY_SEC`    | `60`        | Ventana de limitación admin (segundos)           |

### Swagger

| Variable          | Por defecto | Descripción                                         |
| ----------------- | ----------- | --------------------------------------------------- |
| `SWAGGER_ENABLED` | `false`     | Habilitar Swagger UI                                |
| `SWAGGER_HOST`    | —           | Sobrescribir host de la spec de Swagger             |
| `SWAGGER_SCHEMES` | `https`     | Esquemas de la spec de Swagger (separados por coma) |

### Idempotencia

| Variable                        | Por defecto | Descripción                                                          |
| ------------------------------- | ----------- | -------------------------------------------------------------------- |
| `IDEMPOTENCY_RETRY_WINDOW_SEC`  | `300`       | Ventana para reintentar solicitudes idempotentes fallidas (segundos) |
| `IDEMPOTENCY_SUCCESS_TTL_HOURS` | `168`       | Tiempo de caché de claves de idempotencia completadas (horas)        |
| `IDEMPOTENCY_HMAC_SECRET`       | —           | Secreto HMAC para firmar claves de idempotencia (mín 32 bytes)       |

### Deduplicación

| Variable         | Por defecto | Descripción                               |
| ---------------- | ----------- | ----------------------------------------- |
| `DEDUPE_TTL_SEC` | `3600`      | TTL de claves de deduplicación (segundos) |

### Outbox

| Variable                       | Por defecto | Descripción                                                  |
| ------------------------------ | ----------- | ------------------------------------------------------------ |
| `OUTBOX_RETRY_WINDOW_SEC`      | `300`       | Enfriamiento antes de reintentar eventos fallidos (segundos) |
| `OUTBOX_DISPATCH_INTERVAL_SEC` | `2`         | Intervalo de polling del dispatcher (segundos)               |

### Workers

| Variable                          | Por defecto | Descripción                                                 |
| --------------------------------- | ----------- | ----------------------------------------------------------- |
| `EXPORT_WORKER_ENABLED`           | `true`      | Habilitar worker de exportación                             |
| `EXPORT_WORKER_POLL_INTERVAL_SEC` | `5`         | Intervalo de polling del worker de exportación (segundos)   |
| `EXPORT_WORKER_PAGE_SIZE`         | `1000`      | Filas por página de exportación                             |
| `EXPORT_PRESIGN_EXPIRY_SEC`       | `3600`      | Expiración de URL pre-firmada para exportaciones (segundos) |
| `CLEANUP_WORKER_ENABLED`          | `true`      | Habilitar worker de limpieza                                |
| `CLEANUP_WORKER_INTERVAL_SEC`     | `3600`      | Intervalo del worker de limpieza (segundos)                 |
| `CLEANUP_WORKER_BATCH_SIZE`       | `100`       | Tamaño del lote de limpieza                                 |
| `CLEANUP_WORKER_GRACE_PERIOD_SEC` | `3600`      | Período de gracia antes de la limpieza (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          |

### Programador

| Variable                 | Por defecto | Descripción                                          |
| ------------------------ | ----------- | ---------------------------------------------------- |
| `SCHEDULER_INTERVAL_SEC` | `60`        | Intervalo de polling del programador cron (segundos) |

### Archivado

| Variable                         | Por defecto           | Descripción                                            |
| -------------------------------- | --------------------- | ------------------------------------------------------ |
| `ARCHIVAL_WORKER_ENABLED`        | `false`               | Habilitar worker de archivado de logs de auditoría     |
| `ARCHIVAL_WORKER_INTERVAL_HOURS` | `24`                  | Intervalo de ejecución del archivado (horas)           |
| `ARCHIVAL_HOT_RETENTION_DAYS`    | `90`                  | Días para mantener datos en almacenamiento caliente    |
| `ARCHIVAL_WARM_RETENTION_MONTHS` | `24`                  | Meses para mantener datos en almacenamiento tibio      |
| `ARCHIVAL_COLD_RETENTION_MONTHS` | `84`                  | Meses para mantener datos en almacenamiento frío       |
| `ARCHIVAL_BATCH_SIZE`            | `5000`                | Filas por lote de archivado                            |
| `ARCHIVAL_STORAGE_BUCKET`        | `matcher-archives`    | Bucket S3 para archivos                                |
| `ARCHIVAL_STORAGE_PREFIX`        | `archives/audit-logs` | Prefijo de clave S3 para archivos                      |
| `ARCHIVAL_STORAGE_CLASS`         | `GLACIER`             | Clase de almacenamiento S3 para archivos               |
| `ARCHIVAL_PARTITION_LOOKAHEAD`   | `3`                   | Cantidad de particiones anticipadas                    |
| `ARCHIVAL_PRESIGN_EXPIRY_SEC`    | `3600`                | Expiración de URL pre-firmada para archivos (segundos) |

### Fetcher / Discovery

Estas configuraciones controlan Discovery, que lee bases de datos externas a través de un motor de extracción en proceso integrado en Matcher, no un servicio en red aparte. Consulta [Discovery](/es/matcher/integrations/matcher-discovery) para saber cómo funciona.

| Variable                         | Por defecto  | Descripción                                                                              |
| -------------------------------- | ------------ | ---------------------------------------------------------------------------------------- |
| `FETCHER_DISCOVERY_INTERVAL_SEC` | `60`         | Intervalo de polling de discovery (segundos)                                             |
| `FETCHER_SCHEMA_CACHE_TTL_SEC`   | `300`        | TTL del caché de schema (segundos)                                                       |
| `FETCHER_EXTRACTION_TIMEOUT_SEC` | `600`        | Timeout de extracción (segundos)                                                         |
| `FETCHER_MAX_EXTRACTION_BYTES`   | `2147483648` | Tamaño máximo del payload de extracción (bytes, 2 GiB por defecto)                       |
| `APP_ENC_KEY`                    | —            | Clave maestra codificada en Base64 para el protector de credenciales del motor integrado |

### Infraestructura

| Variable                    | Por defecto | Descripción                                                    |
| --------------------------- | ----------- | -------------------------------------------------------------- |
| `INFRA_CONNECT_TIMEOUT_SEC` | `30`        | Timeout de conexión de infraestructura en el inicio (segundos) |
| `HEALTH_CHECK_TIMEOUT_SEC`  | `5`         | Timeout legado por verificación (segundos)                     |
| `HEALTH_CHECK_TIMEOUT_MS`   | `800`       | Timeout por verificación (milisegundos, preferido)             |

<Note>
  Para configuraciones de despliegue multi-tenant, ver [Modo Multi-Tenant](/es/matcher/configuration/matcher-multi-tenant). Para gestión de configuración en runtime, ver [Configuración en Runtime (Systemplane)](/es/matcher/configuration/matcher-systemplane).
</Note>

## Verificar la instalación

***

Valida que Matcher esté operando correctamente ejercitando la 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 prueba",
   "type": "1:1"
 }'
```

Una respuesta exitosa confirma que la API y sus dependencias (base de datos, caché, message broker, object storage) están accesibles. Las sondas de liveness y readiness de Kubernetes se configuran a nivel de cluster por la orquestación; no necesitas llamarlas directamente.

## Solución de problemas

***

### Problemas comunes

<AccordionGroup>
  <Accordion title="Conexión rechazada a PostgreSQL">
    * **Causa:** PostgreSQL no está ejecutándose o no es accesible.
    * **Resolución:**

    1. Verifica que PostgreSQL esté ejecutándose: `docker-compose ps postgres`
    2. Revisa los valores de conexión en `.env`
    3. Prueba la conectividad: `nc -zv localhost 5432`
    4. Revisa los logs: `docker-compose logs postgres`
  </Accordion>

  <Accordion title="Tiempo de espera de conexión a Redis">
    * **Causa:** Redis no está ejecutándose o las credenciales son incorrectas.
    * **Resolución:**

    1. Verifica que Redis esté ejecutándose: `docker-compose ps redis`
    2. Confirma `REDIS_PASSWORD`
    3. Prueba la conectividad: `redis-cli -h localhost ping`
  </Accordion>

  <Accordion title="Colas de RabbitMQ no creadas">
    * **Causa:** RabbitMQ todavía está inicializando o falta el host virtual.
    * **Resolución:**

    1. Espera hasta que RabbitMQ esté saludable
    2. Accede a la interfaz de gestión en [http://localhost:15672](http://localhost:15672)
    3. Verifica `RABBITMQ_VHOST`
  </Accordion>

  <Accordion title="Errores de autenticación">
    * **Causa:** El servicio de autenticación no es accesible o el token es inválido.
    * **Resolución:**

    1. Verifica `PLUGIN_AUTH_ADDRESS`
    2. Deshabilita la autenticación para desarrollo: `PLUGIN_AUTH_ENABLED=false`
    3. Revisa los logs del servicio de autenticación
  </Accordion>

  <Accordion title="Migración fallida">
    * **Causa:** Las migraciones de base de datos no pudieron aplicarse.
    * **Resolución:**

    1. Verifica el estado de migración: `make migrate-status`
    2. Revisa los logs de migración
    3. Aplica las migraciones manualmente: `make migrate-up`
    4. Inspecciona la tabla `schema_migrations` si es necesario
  </Accordion>

  <Accordion title="Errores de migración de base de datos al actualizar desde main">
    Al actualizar desde la rama main, las migraciones 000020 y 000021 se ejecutan automáticamente. La migración 000020 renombra las claves de configuración del systemplane para estandarización entre productos. La migración 000021 convierte la columna `external_system` de un tipo enum a VARCHAR(255), permitiendo identificadores arbitrarios de sistema externo. Si las migraciones fallan, verifica la tabla `schema_migrations` y asegúrate de que no existan cambios manuales en conflicto.
  </Accordion>
</AccordionGroup>

### Ver logs

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

### Modo de depuración

Habilita el logging de depuración para mayor visibilidad:

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

## Próximos pasos

***

<Card title="Inicio rápido" icon="rocket" href="/es/matcher/getting-started/matcher-quick-start" horizontal>
  Ejecuta tu primera conciliación.
</Card>

<Card title="Configuración" icon="gear" href="/es/matcher/configuration/matcher-contexts-and-sources" horizontal>
  Configura contextos, fuentes y reglas de conciliación.
</Card>