Instalación de Matcher

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.

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.

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:

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 para detalles sobre las configuraciones disponibles.

3. Iniciar servicios

Inicia los servicios de infraestructura requeridos:

docker-compose up -d postgres redis rabbitmq

Espera hasta que todos los servicios reporten un estado saludable:

docker-compose ps

Inicia la aplicación de Matcher:

docker-compose up -d app

Para iniciar todos los servicios a la vez:

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):

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:

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

kubectl create namespace matcher

2. Configurar valores

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

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:

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

helm install matcher oci://registry-1.docker.io/lerianstudio/matcher-helm \
 --version 4.1.0 \
 --namespace matcher \
 --values values.yaml

5. Verificar el despliegue

kubectl get pods -n matcher
kubectl get svc -n matcher
kubectl logs -f deployment/matcher -n matcher

Actualización

Para actualizar un despliegue existente:

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 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)

Para configuraciones de despliegue multi-tenant, ver Modo Multi-Tenant. Para gestión de configuración en runtime, ver Configuración en Runtime (Systemplane).

Verificar la instalación

Valida que Matcher esté operando correctamente ejercitando la API:

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

Conexión rechazada a PostgreSQL

Causa: PostgreSQL no está ejecutándose o no es accesible.
Resolución:

Verifica que PostgreSQL esté ejecutándose: docker-compose ps postgres
Revisa los valores de conexión en .env
Prueba la conectividad: nc -zv localhost 5432
Revisa los logs: docker-compose logs postgres

Tiempo de espera de conexión a Redis

Causa: Redis no está ejecutándose o las credenciales son incorrectas.
Resolución:

Verifica que Redis esté ejecutándose: docker-compose ps redis
Confirma REDIS_PASSWORD
Prueba la conectividad: redis-cli -h localhost ping

Colas de RabbitMQ no creadas

Causa: RabbitMQ todavía está inicializando o falta el host virtual.
Resolución:

Espera hasta que RabbitMQ esté saludable
Accede a la interfaz de gestión en http://localhost:15672
Verifica RABBITMQ_VHOST

Errores de autenticación

Causa: El servicio de autenticación no es accesible o el token es inválido.
Resolución:

Verifica PLUGIN_AUTH_ADDRESS
Deshabilita la autenticación para desarrollo: PLUGIN_AUTH_ENABLED=false
Revisa los logs del servicio de autenticación

Migración fallida

Causa: Las migraciones de base de datos no pudieron aplicarse.
Resolución:

Verifica el estado de migración: make migrate-status
Revisa los logs de migración
Aplica las migraciones manualmente: make migrate-up
Inspecciona la tabla schema_migrations si es necesario

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.

Ver logs

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:

LOG_LEVEL=debug docker-compose up app

​Docker Compose (desarrollo)

​1. Acceder al proyecto Matcher

​2. Configurar el entorno

​3. Iniciar servicios

​4. Verificar la instalación

​Servicios de Docker Compose

​Desarrollo con recarga en caliente

​Kubernetes / Helm (producción)

​Prerrequisitos

​1. Crear un namespace

​2. Configurar valores

​3. Crear secrets

​4. Instalar el chart

​5. Verificar el despliegue

​Actualización

​Variables de entorno

​Aplicación

​CORS

​Base de datos (PostgreSQL)

​Réplica de base de datos (PostgreSQL)

​Caché (Redis)

​Mensajería (RabbitMQ)

​Autenticación

​Almacenamiento de objetos (compatible con S3)

​Observabilidad

​TLS

​Limitación de tasa

​Swagger

​Idempotencia

​Deduplicación

​Outbox

​Workers

​Programador

​Archivado

​Fetcher / Discovery

​Infraestructura

​Verificar la instalación

​Solución de problemas

​Problemas comunes

​Ver logs

​Modo de depuración

​Próximos pasos

Inicio rápido

Configuración

Docker Compose (desarrollo)

1. Acceder al proyecto Matcher

2. Configurar el entorno

3. Iniciar servicios

4. Verificar la instalación

Servicios de Docker Compose

Desarrollo con recarga en caliente

Kubernetes / Helm (producción)

Prerrequisitos

1. Crear un namespace

2. Configurar valores

3. Crear secrets

4. Instalar el chart

5. Verificar el despliegue

Actualización

Variables de entorno

Aplicación

CORS

Base de datos (PostgreSQL)

Réplica de base de datos (PostgreSQL)

Caché (Redis)

Mensajería (RabbitMQ)

Autenticación

Almacenamiento de objetos (compatible con S3)

Observabilidad

TLS

Limitación de tasa

Swagger

Idempotencia

Deduplicación

Outbox

Workers

Programador

Archivado

Fetcher / Discovery

Infraestructura

Verificar la instalación

Solución de problemas

Problemas comunes

Ver logs

Modo de depuración

Próximos pasos