Guia Backend

Instalação e Configuração

Suba o stack com Docker Compose ou instale os serviços no Ubuntu.

Requisitos

Para Docker

  • • Docker Engine + Compose v2
  • • Git
  • • (Opcional) Node.js 20/22 LTS se for rodar a API fora do container

Serviços do stack

  • • API NestJS (multi-stage Dockerfile + HEALTHCHECK)
  • • PostgreSQL 16 (TypeORM, connection pool)
  • • MongoDB 7 (Mongoose, connection pool)
  • • Redis 7
  • • Apache Kafka KRaft (sem Zookeeper)
  • • MinIO, MailHog, OpenSearch, Graylog

1. Docker Compose

O arquivo .env.docker já aponta hosts internos (postgres, mongo, redis, kafka, mailhog, graylog) e senhas de teste. Containers usam container_name estáveis (sem sufixo -1).

BashTerminal
# Na raiz do repositório
docker compose --env-file .env.docker up -d --build

# Status
docker compose --env-file .env.docker ps

# Logs da API
docker compose --env-file .env.docker logs -f api

# Parar
docker compose --env-file .env.docker down

Serviços e portas

  • /api/v1 — API · /swagger · / · /health · /swagger · / · /health
  • /mailhog/ — MailHog UI (SMTP 1025)
  • http://localhost:9000 / :9001 — MinIO API / Console
  • /graylog/ — Graylog UI (GELF 12201)
  • localhost:5432 — PostgreSQL
  • localhost:27017 — MongoDB
  • localhost:6379 — Redis (senha em REDIS_PASSWORD)
  • Kafka interno: kafka:9092 (modo KRaft, sem Zookeeper)
  • http://localhost:8088 — Kafka UI

HEALTHCHECK

A imagem da API faz healthcheck em GET /health, que inclui ping + metadados de pool Postgres/Mongo.

2. Configuração do projeto

Clone e dependências

BashTerminal
git clone https://github.com/mateuslacorte/backend-nestjs.git
cd backend-nestjs
npm install

Variáveis de ambiente

Copie .env.example → .env para desenvolvimento local. Em Compose, use .env.docker.

EnvironmentTrecho relevante
# JWT
API_VERSION=v1
JWT_SECRET=seu_jwt_secret
JWT_EXPIRATION_TIME=1h
JWT_REFRESH_SECRET=seu_refresh_secret
JWT_REFRESH_EXPIRATION_TIME=7d
JWT_JITTER_SECONDS=60

# Graylog (GELF)
GRAYLOG_ENABLED=true
GRAYLOG_ENDPOINT=http://localhost:12201/gelf
GRAYLOG_HOST=backend
GRAYLOG_FACILITY=nestjs

# Mongo pool
MONGO_URI=mongodb://localhost:27017/mongo
MONGO_POOL_MAX=10
MONGO_POOL_MIN=0
MONGO_POOL_IDLE=30000
MONGO_POOL_TIMEOUT=5000

# Postgres pool
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=backend
POSTGRES_SYNCHRONIZE=false
POSTGRES_POOL_MAX=10
POSTGRES_POOL_MIN=2
POSTGRES_POOL_IDLE=30000
POSTGRES_POOL_TIMEOUT=5000

# Kafka (KRaft broker; sem Zookeeper)
KAFKA_BROKERS=localhost:9092

# Argon2id
ARGON2_MEMORY_COST=19456
ARGON2_TIME_COST=2
ARGON2_PARALLELISM=1

Connection pools

Postgres (TypeORM/pg) e Mongo (Mongoose) usam pool configurável. O pool reutiliza conexões; max/min e timeouts controlam tamanho e reciclagem. Veja também Arquitetura.

3. API em modo desenvolvimento

Com a infra no Compose (ou serviços locais), rode a API no host:

BashTerminal
# Ajuste .env para hosts localhost (ou portas publicadas do Compose)
npm run start:dev

# Produção (build local)
npm run build
npm run start:prod

4. Ubuntu nativo

Instale Node, Postgres, Mongo, Redis e MinIO no host. Kafka (KRaft), Graylog, OpenSearch e MailHog podem continuar no Compose em setup híbrido.

Node.js LTS (20 ou 22)

BashTerminal
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version
npm --version

PostgreSQL

BashTerminal
sudo apt update
sudo apt install -y postgresql postgresql-contrib
sudo systemctl enable --now postgresql
sudo -u postgres psql -c "CREATE USER backend_user WITH PASSWORD 'sua_senha';"
sudo -u postgres psql -c "CREATE DATABASE backend_db OWNER backend_user;"

MongoDB

BashTerminal
# Siga a doc oficial da versão 7.x para Ubuntu
# https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-ubuntu/
sudo systemctl enable --now mongod

Redis

BashTerminal
sudo apt install -y redis-server
sudo systemctl enable --now redis-server
redis-cli ping

Kafka (KRaft — sem Zookeeper)

Este projeto usa Kafka em modo KRaft (sem Zookeeper). Exemplo com o serviço do Compose:

BashTerminal
docker compose --env-file .env.docker up -d kafka

MinIO

BashTerminal
# Binário oficial ou via Compose:
docker compose --env-file .env.docker up -d minio

MailHog / Graylog / OpenSearch

Use o Compose: docker compose --env-file .env.docker up -d mailhog opensearch graylog.

Troubleshooting

Compose / health

BashTerminal
docker compose --env-file .env.docker ps
curl -s https://nest.lacorte.dev/health | jq
docker compose --env-file .env.docker logs -f api

Serviços nativos

BashTerminal
sudo systemctl status postgresql
sudo systemctl status mongod
sudo systemctl status redis-server

Porta em uso

BashTerminal
sudo lsof -i :3000
# ou altere PORT no .env