Instalando o Matcher

Este guia descreve como implantar o Matcher em ambientes de desenvolvimento e produção.

Docker Compose (desenvolvimento)

Docker Compose é a abordagem recomendada para desenvolvimento local e testes.

1. Clone o repositório

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

2. Configure o ambiente

Crie um arquivo de ambiente local:

cp config/.env.example config/.env

Atualize config/.env com valores apropriados para seu ambiente. Consulte Variáveis de ambiente para detalhes.

3. Inicie os serviços

Inicie os serviços de infraestrutura necessários:

docker-compose up -d postgres redis rabbitmq

Aguarde até que todos os serviços reportem status saudável:

docker-compose ps

Inicie o Matcher:

docker-compose up -d matcher

Para iniciar todos os serviços de uma vez:

docker-compose up -d

4. Verifique a instalação

Confirme que o Matcher está em execução:

curl http://localhost:8080/health

Resposta esperada:

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

Serviços do Docker Compose

O docker-compose.yml padrão inclui:

Serviço	Porta	Propósito
`matcher`	8080	API do Matcher
`postgres`	5432	Banco de dados PostgreSQL
`redis`	6379	Cache Redis
`rabbitmq`	5672, 15672	RabbitMQ (AMQP e UI de gerenciamento)

Desenvolvimento com hot reload

Para desenvolvimento ativo, use:

make dev

Isso inicia o Matcher com live reload habilitado usando Air.

Kubernetes / Helm (produção)

Implantações em produção devem usar o chart Helm oficial.

Pré-requisitos

Kubernetes 1.28+
Helm 3.12+
kubectl configurado para o cluster de destino

1. Adicione o repositório Helm

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

2. Crie um namespace

kubectl create namespace matcher

3. Configure os valores

Crie um arquivo values.yaml com sua configuração de implantação:

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. Crie os secrets

Crie secrets do Kubernetes para credenciais sensíveis:

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. Instale o chart

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

6. Verifique a implantação

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

Atualizando

Para atualizar uma implantação existente:

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

Variáveis de ambiente

O Matcher é configurado inteiramente através de variáveis de ambiente.

Aplicação

Variável	Padrão	Descrição
`ENV_NAME`	`development`	Nome do ambiente de runtime
`LOG_LEVEL`	`info`	Verbosidade do log
`SERVER_ADDRESS`	`:8080`	Endereço do servidor HTTP
`HTTP_BODY_LIMIT_BYTES`	`104857600`	Tamanho máximo da requisição

Banco de dados (PostgreSQL)

Variável	Padrão	Descrição
`POSTGRES_HOST`	`localhost`	Host do banco de dados
`POSTGRES_PORT`	`5432`	Porta do banco de dados
`POSTGRES_USER`	`matcher`	Usuário
`POSTGRES_PASSWORD`	-	Senha
`POSTGRES_DB`	`matcher`	Nome do banco de dados
`POSTGRES_SSLMODE`	`disable`	Modo SSL
`POSTGRES_MAX_OPEN_CONNS`	`25`	Máximo de conexões abertas
`POSTGRES_MAX_IDLE_CONNS`	`10`	Máximo de conexões ociosas

Cache (Redis)

Variável	Padrão	Descrição
`REDIS_HOST`	`localhost:6379`	Endereço do Redis
`REDIS_PASSWORD`	-	Senha
`REDIS_DB`	`0`	Índice do banco de dados
`REDIS_POOL_SIZE`	`10`	Tamanho do pool

Mensageria (RabbitMQ)

Variável	Padrão	Descrição
`RABBITMQ_HOST`	`localhost`	Host do broker
`RABBITMQ_PORT`	`5672`	Porta do broker
`RABBITMQ_USER`	`guest`	Usuário
`RABBITMQ_PASSWORD`	`guest`	Senha
`RABBITMQ_VHOST`	`/`	Virtual host

Autenticação

Variável	Padrão	Descrição
`AUTH_ENABLED`	`true`	Habilitar autenticação
`AUTH_SERVICE_ADDRESS`	-	URL do serviço de auth
`DEFAULT_TENANT_ID`	-	ID do tenant padrão
`DEFAULT_TENANT_SLUG`	-	Slug do tenant padrão

Observabilidade

Variável	Padrão	Descrição
`OTEL_ENABLED`	`false`	Habilitar OpenTelemetry
`OTEL_SERVICE_NAME`	`matcher`	Nome do serviço de trace
`OTEL_EXPORTER_ENDPOINT`	-	Endpoint do exportador OTLP

TLS

Variável	Padrão	Descrição
`SERVER_TLS_CERT_FILE`	-	Caminho do certificado TLS
`SERVER_TLS_KEY_FILE`	-	Caminho da chave privada TLS

Verificar a instalação

Valide que o Matcher está operando corretamente.

Health check

curl http://localhost:8080/health

Readiness check

curl http://localhost:8080/ready

Verificação da API

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

Solução de problemas

Problemas comuns

Conexão recusada ao PostgreSQL

Causa: PostgreSQL não está em execução ou inacessível.
Resolução:

Verifique se o PostgreSQL está em execução: docker-compose ps postgres
Verifique os valores de conexão em .env
Teste a conectividade: nc -zv localhost 5432
Revise os logs: docker-compose logs postgres

Timeout de conexão Redis

Causa: Redis não está em execução ou as credenciais estão incorretas.
Resolução:

Verifique se o Redis está em execução: docker-compose ps redis
Confirme REDIS_PASSWORD
Teste a conectividade: redis-cli -h localhost ping

Filas do RabbitMQ não criadas

Causa: RabbitMQ ainda está inicializando ou o virtual host está faltando.
Resolução:

Aguarde até que o RabbitMQ esteja saudável
Acesse a UI de gerenciamento em http://localhost:15672
Verifique RABBITMQ_VHOST

Erros de autenticação

Causa: Serviço de auth está inacessível ou o token é inválido.
Resolução:

Verifique AUTH_SERVICE_ADDRESS
Desabilite auth para desenvolvimento: AUTH_ENABLED=false
Revise os logs do serviço de auth

Migration falhou

Causa: Migrations do banco de dados não puderam ser aplicadas.
Resolução:

Verifique o status das migrations: make migrate-status
Revise os logs das migrations
Aplique migrations manualmente: make migrate-up
Inspecione a tabela schema_migrations se necessário

Visualizando logs

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

Modo debug

Habilite logging de debug para visibilidade adicional:

LOG_LEVEL=debug docker-compose up matcher

Introduction

Primeiros passos

Configurações

Reconciliação diária

Integrações

Referência

​Docker Compose (desenvolvimento)

​1. Clone o repositório

​2. Configure o ambiente

​3. Inicie os serviços

​4. Verifique a instalação

​Serviços do Docker Compose

​Desenvolvimento com hot reload

​Kubernetes / Helm (produção)

​Pré-requisitos

​1. Adicione o repositório Helm

​2. Crie um namespace

​3. Configure os valores

​4. Crie os secrets

​5. Instale o chart

​6. Verifique a implantação

​Atualizando

​Variáveis de ambiente

​Aplicação

​Banco de dados (PostgreSQL)

​Cache (Redis)

​Mensageria (RabbitMQ)

​Autenticação

​Observabilidade

​TLS

​Verificar a instalação

​Health check

​Readiness check

​Verificação da API

​Solução de problemas

​Problemas comuns

​Visualizando logs

​Modo debug

​Próximos passos

Início rápido

Configuração