Self-Host com Docker

Implante o Batida na sua própria infraestrutura usando Docker Compose. Este guia cobre tudo o que você precisa para ter uma instância pronta para produção.

Pré-requisitos

• Um servidor Linux (recomendado: Ubuntu 22.04+) ou qualquer máquina com Docker instalado
• Docker Engine 20.10+ e Docker Compose v2+
• Pelo menos 2 GB de RAM e 10 GB de espaço em disco
• Um domínio apontando para o seu servidor (opcional, mas recomendado para TLS)

Arquitetura

O Batida possui três componentes que você executará:

Componente	Descrição	Porta
batida-api	Backend em Rust (API REST, processamento de eventos)	5678
batida-web	Frontend React (SPA)	8080
PostgreSQL	Banco de dados principal	5432
Redis	Cache e idempotência de eventos	6379
NATS	Barramento de eventos (JetStream habilitado)	4222

Passo 1 — Clonar os repositórios

git clone https://github.com/batida/batida-api.git
git clone https://github.com/batida/batida-web.git

Passo 2 — Criar o arquivo Docker Compose

Crie um docker-compose.yml no diretório de implantação:

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: batida
      POSTGRES_USER: batida
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-changeme}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U batida"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  nats:
    image: nats:2-alpine
    restart: unless-stopped
    command: "--jetstream --store_dir /data"
    volumes:
      - nats_data:/data
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8222/healthz"]
      interval: 10s
      timeout: 5s
      retries: 5

  api:
    build:
      context: ./batida-api
      dockerfile: Dockerfile
    restart: unless-stopped
    environment:
      DATABASE_URL: postgresql://batida:${POSTGRES_PASSWORD:-changeme}@postgres:5432/batida
      REDIS_URL: redis://redis:6379
      NATS_URL: nats://nats:4222
      APP_INTERNAL_PORT: "5678"
      RUST_LOG: info
      # Gere com: openssl rand -hex 32
      JWT_SECRET: ${JWT_SECRET:-changeme_jwt_secret}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
      nats:
        condition: service_healthy
    ports:
      - "5678:5678"

  web:
    build:
      context: ./batida-web
      dockerfile: Dockerfile
    restart: unless-stopped
    ports:
      - "8080:8080"
    depends_on:
      - api

volumes:
  postgres_data:
  redis_data:
  nats_data:

networks:
  default:
    name: batida-network

WARNING

Altere todas as senhas padrão antes de implantar. Gere um JWT secret forte com openssl rand -hex 32.

Passo 3 — Configurar ambiente

Crie um arquivo .env no mesmo diretório:

POSTGRES_PASSWORD=sua-senha-forte-aqui
JWT_SECRET=seu-jwt-secret-aqui

Passo 4 — Construir e iniciar

docker-compose up -d --build

A API executa as migrações do banco de dados automaticamente na inicialização. Aguarde cerca de 30 segundos para que todos os serviços fiquem saudáveis:

docker-compose ps

Todos os serviços devem mostrar healthy ou running.

Passo 5 — Acessar o Batida

Abra o navegador em:

http://ip-do-seu-servidor:8080

Crie sua conta de administrador e organização no primeiro acesso.

TLS com proxy reverso

Para produção, coloque o Batida atrás de um proxy reverso com TLS. Aqui está um exemplo mínimo com Caddy:

batida.exemplo.com {
    reverse_proxy web:8080
    reverse_proxy /api/* api:5678
}

Ou com Nginx:

server {
    listen 443 ssl http2;
    server_name batida.exemplo.com;

    ssl_certificate /etc/ssl/certs/batida.pem;
    ssl_certificate_key /etc/ssl/private/batida.key;

    location / {
        proxy_pass http://web:8080;
        proxy_set_header Host $host;
    }

    location /api/ {
        proxy_pass http://api:5678;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Atualizando

git pull  # em cada diretório do repositório
docker-compose up -d --build

A API cuida das migrações na inicialização — nenhuma etapa manual necessária.

Backups

Os dados do PostgreSQL estão em um volume Docker. Para fazer backup:

docker-compose exec postgres pg_dump -U batida batida > backup_$(date +%Y%m%d).sql

Para restaurar:

cat backup_20260523.sql | docker-compose exec -T postgres psql -U batida batida

Solução de problemas

API não inicia

Verifique os logs com docker-compose logs api. O problema mais comum é o banco de dados não estar pronto — a API tenta novamente com backoff, então aguarde 60 segundos antes de investigar.

Conexão com banco recusada

Verifique se o PostgreSQL está saudável: docker-compose exec postgres pg_isready -U batida.

Eventos não processando

Verifique a saúde do NATS: docker-compose exec nats wget -qO- http://localhost:8222/healthz.

Conflito de portas

Se as portas 5432, 6379, 4222, 5678 ou 8080 já estiverem em uso, altere os mapeamentos no seu docker-compose.yml (ex.: "5433:5432").

Para mais ajuda, veja Solução de problemas.