Instalar Matcher

Matcher automatiza la conciliación financiera entre varias fuentes de datos, elimina el trabajo manual de coincidencia y ofrece un registro de auditoría completo para cada transacción. Esta guía te lleva por el despliegue de Matcher en entornos de desarrollo y producción.

Matcher está disponible para clientes con licencia. Lerian mantiene su repositorio de forma interna. Las instrucciones siguientes suponen que ya tienes acceso a los archivos del proyecto Matcher necesarios.

Docker compose (desarrollo)

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

1. Accede al proyecto Matcher

Desde el directorio del proyecto Matcher:

cd matcher

2. Configura el entorno

El archivo docker-compose.yml incluye valores predeterminados razonables para el 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 más detalles sobre los ajustes disponibles.

3. Inicia los servicios

Inicia los servicios de infraestructura necesarios:

docker-compose up -d postgres redis rabbitmq

Espera hasta que todos los servicios reporten un estado saludable:

docker-compose ps

Inicia la aplicación Matcher:

docker-compose up -d app

Para iniciar todos los servicios de una vez:

docker-compose up -d

4. Verifica la instalación

Lista los contextos de configuración para confirmar que Matcher está activo. 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 necesarias mediante el endpoint público de readiness:

curl http://localhost:4018/readyz

El endpoint devuelve 200 cuando cada dependencia necesaria está lista. Devuelve 503 con detalles por verificación cuando una dependencia necesaria no está disponible.

Servicios de Docker compose

El docker-compose.yml predeterminado incluye:

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

Desarrollo con hot reload

Para desarrollo activo, usa:

make dev

Esto inicia Matcher con la recarga en vivo habilitada usando Air.

Kubernetes / helm (producción)

Se recomienda que los despliegues de producción usen el Helm chart oficial.

Requisitos previos

Kubernetes 1.28+
Helm 3.12+
kubectl configurado para el cluster destino

1. Crea un namespace

kubectl create namespace matcher

2. Configura los valores

Crea un archivo values.yaml con la configuración de tu 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. Crea los secrets

Crea secrets de Kubernetes para las credenciales sensibles:

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. Instala el chart

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

5. Verifica 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 bootstrap de Matcher. Systemplane puede sobrescribir los ajustes mutables en tiempo de ejecución después del arranque.

Aplicación

Variable	Predeterminado	Descripción
`ENV_NAME`	`development`	Nombre del entorno de ejecución
`LOG_LEVEL`	`info`	Nivel de detalle del log
`DEPLOYMENT_MODE`	`local`	Modo de despliegue (`local`, `byoc`, `saas`)
`SERVER_ADDRESS`	`:4018`	Dirección de enlace del servidor HTTP
`HTTP_BODY_LIMIT_BYTES`	`104857600`	Tamaño máximo del cuerpo de la solicitud con buffer (bytes, 100 MiB de forma predeterminada)

CORS

Variable	Predeterminado	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	Predeterminado	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`	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`	Exige 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`	Vida máxima de la conexión (minutos)
`POSTGRES_CONN_MAX_IDLE_TIME_MINS`	`5`	Tiempo máximo de inactividad 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 la base de datos (PostgreSQL)

Variable	Predeterminado	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 de la réplica
`POSTGRES_REPLICA_SSLMODE`	—	Modo SSL de la réplica
`POSTGRES_REPLICA_TLS_REQUIRED`	`false`	Exige TLS para la réplica

Caché (Redis)

Variable	Predeterminado	Descripción
`REDIS_HOST`	`localhost:6379`	Dirección de Redis (host:port)
`REDIS_MASTER_NAME`	—	Nombre del master de Sentinel
`REDIS_PASSWORD`	—	Contraseña
`REDIS_DB`	`0`	Índice de la base de datos
`REDIS_TLS`	`false`	Habilita TLS
`REDIS_TLS_REQUIRED`	`false`	Exige TLS en el bootstrap
`REDIS_CA_CERT`	—	Ruta del certificado de 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 inicial (milisegundos)

Mensajería (RabbitMQ)

Variable	Predeterminado	Descripción
`RABBITMQ_URI`	`amqp`	Esquema de URI (`amqp` o `amqps`)
`RABBITMQ_HOST`	`localhost`	Host del broker
`RABBITMQ_PORT`	`5672`	Puerto del broker
`RABBITMQ_USER`	`matcher_admin`	Usuario
`RABBITMQ_PASSWORD`	`matcher_dev_password`	Contraseña
`RABBITMQ_VHOST`	`/`	Host virtual
`RABBITMQ_HEALTH_URL`	`http://localhost:15672`	URL de la API de administración para los health checks
`RABBITMQ_ALLOW_INSECURE_HEALTH_CHECK`	`false`	Permite health check HTTP (sin TLS)
`RABBITMQ_TLS_REQUIRED`	`false`	Exige TLS en el bootstrap

Autenticación

Variable	Predeterminado	Descripción
`PLUGIN_AUTH_ENABLED`	`false`	Habilita la 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	Predeterminado	Descripción
`OBJECT_STORAGE_ENDPOINT`	`http://localhost:8333`	URL del endpoint de S3
`OBJECT_STORAGE_REGION`	`us-east-1`	Región de S3
`OBJECT_STORAGE_BUCKET`	`matcher-exports`	Bucket para las exportaciones
`OBJECT_STORAGE_ACCESS_KEY_ID`	—	ID de la clave de acceso
`OBJECT_STORAGE_SECRET_ACCESS_KEY`	—	Clave de acceso secreta
`OBJECT_STORAGE_USE_PATH_STYLE`	`true`	Usa direccionamiento de estilo ruta
`OBJECT_STORAGE_ALLOW_INSECURE_ENDPOINT`	`false`	Permite endpoint HTTP (sin TLS)
`OBJECT_STORAGE_TLS_REQUIRED`	`false`	Exige TLS en el bootstrap

Observabilidad

Variable	Predeterminado	Descripción
`ENABLE_TELEMETRY`	`false`	Habilita OpenTelemetry
`OTEL_RESOURCE_SERVICE_NAME`	`matcher`	Nombre del servicio para traces/métricas
`OTEL_LIBRARY_NAME`	`github.com/LerianStudio/matcher`	Nombre de la librería 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 collector OTLP
`DB_METRICS_INTERVAL_SEC`	`15`	Intervalo de recolección de métricas de la base de datos

TLS

Variable	Predeterminado	Descripción
`SERVER_TLS_CERT_FILE`	—	Ruta del certificado TLS
`SERVER_TLS_KEY_FILE`	—	Ruta de la clave privada TLS
`TLS_TERMINATED_UPSTREAM`	`false`	Confía en la terminación TLS upstream (p. ej., load balancer)
`TRUSTED_PROXIES`	—	Rangos CIDR de proxies de confianza

Rate limiting

Variable	Predeterminado	Descripción
`RATE_LIMIT_ENABLED`	`true`	Habilita el rate limiting global
`RATE_LIMIT_MAX`	`100`	Máximo de solicitudes por ventana
`RATE_LIMIT_EXPIRY_SEC`	`60`	Ventana de rate limit (segundos)
`EXPORT_RATE_LIMIT_MAX`	`10`	Máximo de solicitudes de exportación por ventana
`EXPORT_RATE_LIMIT_EXPIRY_SEC`	`60`	Ventana de rate limit 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 rate limit de despacho (segundos)
`ADMIN_RATE_LIMIT_MAX`	`30`	Máximo de solicitudes de administración por ventana
`ADMIN_RATE_LIMIT_EXPIRY_SEC`	`60`	Ventana de rate limit de administración (segundos)

Swagger

Variable	Predeterminado	Descripción
`SWAGGER_ENABLED`	`false`	Habilita la UI de Swagger
`SWAGGER_HOST`	—	Sobrescribe el host de la especificación de Swagger
`SWAGGER_SCHEMES`	`https`	Esquemas de la especificación de Swagger (separados por comas)

Idempotencia

Variable	Predeterminado	Descripción
`IDEMPOTENCY_RETRY_WINDOW_SEC`	`300`	Ventana para reintentar solicitudes idempotentes fallidas (segundos)
`IDEMPOTENCY_SUCCESS_TTL_HOURS`	`168`	Cuánto tiempo se guardan en caché las claves de idempotencia completadas (horas)
`IDEMPOTENCY_HMAC_SECRET`	—	Secreto HMAC para firmar las claves de idempotencia (mín. 32 bytes)

Deduplicación

Variable	Predeterminado	Descripción
`DEDUPE_TTL_SEC`	`3600`	TTL para las claves de deduplicación (segundos)

Outbox

Variable	Predeterminado	Descripción
`OUTBOX_RETRY_WINDOW_SEC`	`300`	Enfriamiento antes de reintentar los eventos fallidos (segundos)
`OUTBOX_DISPATCH_INTERVAL_SEC`	`2`	Intervalo de sondeo del dispatcher (segundos)

Workers

Variable	Predeterminado	Descripción
`EXPORT_WORKER_ENABLED`	`true`	Habilita el worker de exportación
`EXPORT_WORKER_POLL_INTERVAL_SEC`	`5`	Intervalo de sondeo 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 la URL prefirmada para las exportaciones (segundos)
`CLEANUP_WORKER_ENABLED`	`true`	Habilita el 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 del webhook (segundos)
`CALLBACK_RATE_LIMIT_PER_MIN`	`60`	Máximo de callbacks por sistema externo por minuto

Planificador

Variable	Predeterminado	Descripción
`SCHEDULER_INTERVAL_SEC`	`60`	Intervalo de sondeo del planificador basado en cron (segundos)

Archivado

Variable	Predeterminado	Descripción
`ARCHIVAL_WORKER_ENABLED`	`false`	Habilita el worker de archivado del log de auditoría
`ARCHIVAL_WORKER_INTERVAL_HOURS`	`24`	Intervalo de ejecución del archivado (horas)
`ARCHIVAL_HOT_RETENTION_DAYS`	`90`	Días para mantener los datos en almacenamiento caliente
`ARCHIVAL_WARM_RETENTION_MONTHS`	`24`	Meses para mantener los datos en almacenamiento tibio
`ARCHIVAL_COLD_RETENTION_MONTHS`	`84`	Meses para mantener los datos en almacenamiento frío
`ARCHIVAL_BATCH_SIZE`	`5000`	Filas por lote de archivado
`ARCHIVAL_STORAGE_BUCKET`	`matcher-archives`	Bucket de S3 para los archivos
`ARCHIVAL_STORAGE_CLASS`	`GLACIER`	Clase de almacenamiento de S3 para los archivos
`ARCHIVAL_PARTITION_LOOKAHEAD`	`3`	Conteo de anticipación de particiones
`ARCHIVAL_PRESIGN_EXPIRY_SEC`	`3600`	Expiración de la URL prefirmada para los archivos (segundos)

Discovery

Estos ajustes controlan Discovery, que lee de bases de datos externas mediante un motor de extracción en proceso embebido en Matcher, no un servicio de red aparte. Consulta Discovery para ver cómo funciona.

Variable	Predeterminado	Descripción
`FETCHER_DISCOVERY_INTERVAL_SEC`	`60`	Intervalo de sondeo de Discovery (segundos)
`FETCHER_SCHEMA_CACHE_TTL_SEC`	`300`	TTL de la caché de esquema (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 de forma predeterminada)
`APP_ENC_KEY`	—	Clave maestra codificada en Base64 para el protector de credenciales del motor embebido

Infraestructura

Variable	Predeterminado	Descripción
`INFRA_CONNECT_TIMEOUT_SEC`	`30`	Timeout de conexión al arranque de la infraestructura (segundos)
`HEALTH_CHECK_TIMEOUT_SEC`	`5`	Timeout heredado de sonda por verificación (segundos)
`HEALTH_CHECK_TIMEOUT_MS`	`800`	Timeout de sonda por verificación (milisegundos, preferido)

Para los ajustes de despliegue multi-tenant, consulta Modo multi-tenant. Para la gestión de la configuración en tiempo de ejecución, consulta Configuración en tiempo de ejecución (Systemplane).

Verifica la instalación

Valida que Matcher y sus dependencias necesarias estén listos:

curl http://localhost:4018/readyz

El endpoint devuelve 200 cuando cada dependencia necesaria está lista. Devuelve 503 con detalles por verificación cuando una dependencia necesaria no está disponible. Configura las sondas de readiness de Kubernetes para que usen este endpoint.

Solución de problemas

Problemas comunes

Conexión rechazada a PostgreSQL

Causa: PostgreSQL está caído o inalcanzable.
Resolución:

Verifica que PostgreSQL esté activo: 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

Timeout de conexión a Redis

Causa: Redis está caído o las credenciales son incorrectas.
Resolución:

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

Las colas de RabbitMQ no se crean

Causa: RabbitMQ sigue arrancando, o el host virtual no existe.
Resolución:

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

Errores de autenticación

Causa: el servicio de autenticación es inalcanzable o el token no es vá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

La migración falló

Causa: no se pudieron aplicar las migraciones de la base de datos.
Resolución:

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

Ver los logs

docker-compose logs -f app
kubectl logs -f deployment/matcher -n matcher

Modo debug

Habilita el log de debug para más visibilidad:

LOG_LEVEL=debug docker-compose up app

​Docker compose (desarrollo)

​1. Accede al proyecto Matcher

​2. Configura el entorno

​3. Inicia los servicios

​4. Verifica la instalación

​Servicios de Docker compose

​Desarrollo con hot reload

​Kubernetes / helm (producción)

​Requisitos previos

​1. Crea un namespace

​2. Configura los valores

​3. Crea los secrets

​4. Instala el chart

​5. Verifica el despliegue

​Actualización

​Variables de entorno

​Aplicación

​CORS

​Base de datos (PostgreSQL)

​Réplica de la base de datos (PostgreSQL)

​Caché (Redis)

​Mensajería (RabbitMQ)

​Autenticación

​Almacenamiento de objetos (compatible con S3)

​Observabilidad

​TLS

​Rate limiting

​Swagger

​Idempotencia

​Deduplicación

​Outbox

​Workers

​Planificador

​Archivado

​Discovery

​Infraestructura

​Verifica la instalación

​Solución de problemas

​Problemas comunes

​Ver los logs

​Modo debug

​Próximos pasos

Inicio rápido

Configuración

Docker compose (desarrollo)

1. Accede al proyecto Matcher

2. Configura el entorno

3. Inicia los servicios

4. Verifica la instalación

Servicios de Docker compose

Desarrollo con hot reload

Kubernetes / helm (producción)

Requisitos previos

1. Crea un namespace

2. Configura los valores

3. Crea los secrets

4. Instala el chart

5. Verifica el despliegue

Actualización

Variables de entorno

Aplicación

CORS

Base de datos (PostgreSQL)

Réplica de la base de datos (PostgreSQL)

Caché (Redis)

Mensajería (RabbitMQ)

Autenticación

Almacenamiento de objetos (compatible con S3)

Observabilidad

TLS

Rate limiting

Swagger

Idempotencia

Deduplicación

Outbox

Workers

Planificador

Archivado

Discovery

Infraestructura

Verifica la instalación

Solución de problemas

Problemas comunes

Ver los logs

Modo debug

Próximos pasos