Installating Matcher

This guide describes how to deploy Matcher in both development and production environments.

Docker compose (development)

Docker Compose is the recommended approach for local development and testing.

1. Clone the repository

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

2. Configure the environment

Create a local environment file:

cp config/.env.example config/.env

Update config/.env with values appropriate for your environment. Refer to Environment variables for details.

3. Start services

Start the required infrastructure services:

docker-compose up -d postgres redis rabbitmq

Wait until all services report a healthy status:

docker-compose ps

Start Matcher:

docker-compose up -d matcher

To start all services at once:

docker-compose up -d

4. Verify the installation

Confirm that Matcher is running:

curl http://localhost:8080/health

Expected response:

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

Docker compose services

The default docker-compose.yml includes:

Service	Port	Purpose
`matcher`	8080	Matcher API
`postgres`	5432	PostgreSQL database
`redis`	6379	Redis cache
`rabbitmq`	5672, 15672	RabbitMQ (AMQP and management UI)

Development with hot reload

For active development, use:

make dev

This starts Matcher with live reload enabled using Air.

Kubernetes / helm (production)

Production deployments should use the official Helm chart.

Prerequisites

Kubernetes 1.28+
Helm 3.12+
kubectl configured for the target cluster

1. Add the helm repository

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

2. Create a namespace

kubectl create namespace matcher

3. Configure values

Create a values.yaml file with your deployment configuration:

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. Create secrets

Create Kubernetes secrets for sensitive credentials:

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

5. Install the chart

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

6. Verify the deployment

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

Upgrading

To upgrade an existing deployment:

helm repo update
helm upgrade matcher lerian/matcher \
 --namespace matcher \
 --values values.yaml

Environment variables

Matcher is configured entirely through environment variables.

Application

Variable	Default	Description
`ENV_NAME`	`development`	Runtime environment name
`LOG_LEVEL`	`info`	Log verbosity
`SERVER_ADDRESS`	`:8080`	HTTP server address
`HTTP_BODY_LIMIT_BYTES`	`104857600`	Maximum request size

Database (postgresql)

Variable	Default	Description
`POSTGRES_HOST`	`localhost`	Database host
`POSTGRES_PORT`	`5432`	Database port
`POSTGRES_USER`	`matcher`	Username
`POSTGRES_PASSWORD`	-	Password
`POSTGRES_DB`	`matcher`	Database name
`POSTGRES_SSLMODE`	`disable`	SSL mode
`POSTGRES_MAX_OPEN_CONNS`	`25`	Max open connections
`POSTGRES_MAX_IDLE_CONNS`	`10`	Max idle connections

Cache (redis)

Variable	Default	Description
`REDIS_HOST`	`localhost:6379`	Redis address
`REDIS_PASSWORD`	-	Password
`REDIS_DB`	`0`	Database index
`REDIS_POOL_SIZE`	`10`	Pool size

Messaging (rabbitmq)

Variable	Default	Description
`RABBITMQ_HOST`	`localhost`	Broker host
`RABBITMQ_PORT`	`5672`	Broker port
`RABBITMQ_USER`	`guest`	Username
`RABBITMQ_PASSWORD`	`guest`	Password
`RABBITMQ_VHOST`	`/`	Virtual host

Authentication

Variable	Default	Description
`AUTH_ENABLED`	`true`	Enable authentication
`AUTH_SERVICE_ADDRESS`	-	Auth service URL
`DEFAULT_TENANT_ID`	-	Default tenant ID
`DEFAULT_TENANT_SLUG`	-	Default tenant slug

Observability

Variable	Default	Description
`OTEL_ENABLED`	`false`	Enable OpenTelemetry
`OTEL_SERVICE_NAME`	`matcher`	Trace service name
`OTEL_EXPORTER_ENDPOINT`	-	OTLP exporter endpoint

TLS

Variable	Default	Description
`SERVER_TLS_CERT_FILE`	-	TLS certificate path
`SERVER_TLS_KEY_FILE`	-	TLS private key path

Verify the installation

Validate that Matcher is operating correctly.

Health check

curl http://localhost:8080/health

Readiness check

curl http://localhost:8080/ready

API verification

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

Troubleshooting

Common issues

Connection refused to PostgreSQL

Cause: PostgreSQL is not running or unreachable.
Resolution:

Verify PostgreSQL is running: docker-compose ps postgres
Check connection values in .env
Test connectivity: nc -zv localhost 5432
Review logs: docker-compose logs postgres

Redis connection timeout

Cause: Redis is not running or credentials are incorrect.
Resolution:

Verify Redis is running: docker-compose ps redis
Confirm REDIS_PASSWORD
Test connectivity: redis-cli -h localhost ping

RabbitMQ queues not created

Cause: RabbitMQ is still initializing or the virtual host is missing.
Resolution:

Wait until RabbitMQ is healthy
Access the management UI at http://localhost:15672
Verify RABBITMQ_VHOST

Authentication errors

Cause: Auth service is unreachable or the token is invalid.
Resolution:

Verify AUTH_SERVICE_ADDRESS
Disable auth for development: AUTH_ENABLED=false
Review auth service logs

Migration failed

Cause: Database migrations could not be applied.
Resolution:

Check migration status: make migrate-status
Review migration logs
Apply migrations manually: make migrate-up
Inspect the schema_migrations table if needed

Viewing logs

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

Debug mode

Enable debug logging for additional visibility:

LOG_LEVEL=debug docker-compose up matcher

Introduction

Getting started

Configuration

Daily reconciliation

Integrations

Reference

​Docker compose (development)

​1. Clone the repository

​2. Configure the environment

​3. Start services

​4. Verify the installation

​Docker compose services

​Development with hot reload

​Kubernetes / helm (production)

​Prerequisites

​1. Add the helm repository

​2. Create a namespace

​3. Configure values

​4. Create secrets

​5. Install the chart

​6. Verify the deployment

​Upgrading

​Environment variables

​Application

​Database (postgresql)

​Cache (redis)

​Messaging (rabbitmq)

​Authentication

​Observability

​TLS

​Verify the installation

​Health check

​Readiness check

​API verification

​Troubleshooting

​Common issues

​Viewing logs

​Debug mode

​Next steps

Quick start