Backend Guide

Installation and Configuration

Bring up the stack with Docker Compose or install services on Ubuntu.

Requirements

For Docker

  • • Docker Engine + Compose v2
  • • Git
  • • (Optional) Node.js 20/22 LTS if running the API outside the container

Stack services

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

1. Docker Compose

The .env.docker file already points to internal hosts (postgres, mongo, redis, kafka, mailhog, graylog) and test passwords. Containers use stable container_name values (no -1 suffix).

BashTerminal
# At the repository root
docker compose --env-file .env.docker up -d --build

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

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

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

Services and ports

  • /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 (password from REDIS_PASSWORD)
  • Internal Kafka: kafka:9092 (KRaft mode, no Zookeeper)
  • http://localhost:8088 — Kafka UI

HEALTHCHECK

The API image runs a health check against GET /health, which includes ping + Postgres/Mongo pool metadata.

2. Project configuration

Clone and dependencies

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

Environment variables

Copy .env.example → .env for local development. With Compose, use .env.docker.

EnvironmentRelevant excerpt
# 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; no Zookeeper)
KAFKA_BROKERS=localhost:9092

# Argon2id
ARGON2_MEMORY_COST=19456
ARGON2_TIME_COST=2
ARGON2_PARALLELISM=1

Connection pools

Postgres (TypeORM/pg) and Mongo (Mongoose) use a configurable pool. The pool reuses connections; max/min and timeouts control size and recycling. See also Architecture.

3. API in development mode

With infrastructure in Compose (or local services), run the API on the host:

BashTerminal
# Adjust .env for localhost hosts (or published Compose ports)
npm run start:dev

# Production (local build)
npm run build
npm run start:prod

4. Native Ubuntu

Install Node, Postgres, Mongo, Redis, and MinIO on the host. Kafka (KRaft), Graylog, OpenSearch, and MailHog can remain in Compose for a hybrid setup.

Node.js LTS (20 or 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
# Follow the official 7.x docs for 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 — no Zookeeper)

This project uses Kafka in KRaft mode (no Zookeeper). Example using the Compose service:

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

MinIO

BashTerminal
# Official binary or via Compose:
docker compose --env-file .env.docker up -d minio

MailHog / Graylog / OpenSearch

Use 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

Native services

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

Port in use

BashTerminal
sudo lsof -i :3000
# or change PORT in .env