Instalación de Matcher

Esta guía describe cómo desplegar Matcher en entornos de desarrollo y producción.

Docker Compose (desarrollo)

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

1. Clonar el repositorio

git clone https://github.com/LerianStudio/matcher.git
cd matcher

2. Configurar el entorno

Crea un archivo de entorno local:

cp config/.env.example config/.env

Actualiza config/.env con valores apropiados para tu entorno. Consulta Variables de entorno para más detalles.

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

docker-compose up -d matcher

Para iniciar todos los servicios a la vez:

docker-compose up -d

4. Verificar la instalación

Confirma que Matcher está ejecutándose:

curl http://localhost:8080/health

Respuesta esperada:

{
  "status": "healthy",
  "services": {
    "postgres": "healthy",
    "redis": "healthy",
    "rabbitmq": "healthy"
  }
}

Servicios de Docker Compose

El docker-compose.yml por defecto incluye:

Servicio	Puerto	Propósito
`matcher`	8080	API de Matcher
`postgres`	5432	Base de datos PostgreSQL
`redis`	6379	Caché Redis
`rabbitmq`	5672, 15672	RabbitMQ (AMQP e interfaz de gestión)

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. Agregar el repositorio de Helm

helm repo add lerian https://charts.lerian.studio
helm repo update

2. Crear un namespace

kubectl create namespace matcher

3. 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: 8080

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

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

5. Instalar el chart

helm install matcher lerian/matcher \
 --namespace matcher \
 --values values.yaml

6. 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 repo update
helm upgrade matcher lerian/matcher \
 --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
`SERVER_ADDRESS`	`:8080`	Dirección del servidor HTTP
`HTTP_BODY_LIMIT_BYTES`	`104857600`	Tamaño máximo de solicitud

Base de datos (PostgreSQL)

Variable	Por defecto	Descripción
`POSTGRES_HOST`	`localhost`	Host de la base de datos
`POSTGRES_PORT`	`5432`	Puerto de la base de datos
`POSTGRES_USER`	`matcher`	Nombre de usuario
`POSTGRES_PASSWORD`	-	Contraseña
`POSTGRES_DB`	`matcher`	Nombre de la base de datos
`POSTGRES_SSLMODE`	`disable`	Modo SSL
`POSTGRES_MAX_OPEN_CONNS`	`25`	Máximo de conexiones abiertas
`POSTGRES_MAX_IDLE_CONNS`	`10`	Máximo de conexiones inactivas

Caché (Redis)

Variable	Por defecto	Descripción
`REDIS_HOST`	`localhost:6379`	Dirección de Redis
`REDIS_PASSWORD`	-	Contraseña
`REDIS_DB`	`0`	Índice de base de datos
`REDIS_POOL_SIZE`	`10`	Tamaño del pool

Mensajería (RabbitMQ)

Variable	Por defecto	Descripción
`RABBITMQ_HOST`	`localhost`	Host del broker
`RABBITMQ_PORT`	`5672`	Puerto del broker
`RABBITMQ_USER`	`guest`	Nombre de usuario
`RABBITMQ_PASSWORD`	`guest`	Contraseña
`RABBITMQ_VHOST`	`/`	Host virtual

Autenticación

Variable	Por defecto	Descripción
`AUTH_ENABLED`	`true`	Habilitar autenticación
`AUTH_SERVICE_ADDRESS`	-	URL del servicio de autenticación
`DEFAULT_TENANT_ID`	-	ID de tenant por defecto
`DEFAULT_TENANT_SLUG`	-	Slug de tenant por defecto

Observabilidad

Variable	Por defecto	Descripción
`OTEL_ENABLED`	`false`	Habilitar OpenTelemetry
`OTEL_SERVICE_NAME`	`matcher`	Nombre del servicio de trazas
`OTEL_EXPORTER_ENDPOINT`	-	Endpoint del exportador OTLP

TLS

Variable	Por defecto	Descripción
`SERVER_TLS_CERT_FILE`	-	Ruta del certificado TLS
`SERVER_TLS_KEY_FILE`	-	Ruta de la clave privada TLS

Verificar la instalación

Valida que Matcher esté operando correctamente.

Verificación de salud

curl http://localhost:8080/health

Verificación de disponibilidad

curl http://localhost:8080/ready

Verificación de la API

curl -X POST http://localhost:8080/v1/contexts \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Contexto de prueba",
   "type": "1:1"
 }'

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 AUTH_SERVICE_ADDRESS
Deshabilita la autenticación para desarrollo: 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

Ver logs

docker-compose logs -f matcher
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 matcher

Introduction

Primeros pasos

Configuración

Reconciliación diaria

Integraciones

Referencia

​Docker Compose (desarrollo)

​1. Clonar el repositorio

​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. Agregar el repositorio de Helm

​2. Crear un namespace

​3. Configurar valores

​4. Crear secrets

​5. Instalar el chart

​6. Verificar el despliegue

​Actualización

​Variables de entorno

​Aplicación

​Base de datos (PostgreSQL)

​Caché (Redis)

​Mensajería (RabbitMQ)

​Autenticación

​Observabilidad

​TLS

​Verificar la instalación

​Verificación de salud

​Verificación de disponibilidad

​Verificación de la API

​Solución de problemas

​Problemas comunes

​Ver logs

​Modo de depuración

​Próximos pasos

Inicio rápido