Instalación de Matcher

Despliega Matcher en desarrollo y producción con Docker Compose, variables de entorno y la pila de infraestructura compatible con todos sus servicios.

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 mediante la lista de contextos de configuración. En una instalación nueva, la respuesta paginada por cursor tiene un arreglo items vacío:

curl -H "Authorization: Bearer $TOKEN" http://localhost:4018/v1/contexts

Luego verifica las dependencias requeridas mediante el endpoint público de disponibilidad:

curl http://localhost:4018/readyz

El endpoint devuelve 200 cuando todas las dependencias requeridas están disponibles. Devuelve 503 con detalles de cada verificación cuando alguna dependencia requerida no está disponible.

​

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

---

Las variables de entorno proporcionan la configuración de arranque de Matcher. Systemplane puede sobrescribir las configuraciones modificables en tiempo de ejecución después del inicio.

​

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)

​

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_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 y sus dependencias requeridas estén disponibles:

curl http://localhost:4018/readyz

El endpoint devuelve 200 cuando todas las dependencias requeridas están disponibles. Devuelve 503 con detalles de cada verificación cuando alguna dependencia requerida no está disponible. Configura las sondas de disponibilidad de Kubernetes para usar este endpoint.

​

Solución de problemas

---

​

Problemas comunes

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

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

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
3. Verifica RABBITMQ_VHOST

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

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

​

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

​

Próximos pasos

---

Inicio rápido

Ejecuta tu primera conciliación.

Configuración

Configura contextos, fuentes y reglas de conciliación.