Começando

Configurar variáveis de ambiente, rodar a API localmente e fazer a primeira chamada autenticada.

Pré-requisitos

Node.js 20+
pnpm
PostgreSQL
Redis
Um realm Keycloak acessível (para emissão/validação de tokens)

Variáveis de ambiente

A configuração é validada por Zod na inicialização (src/infra/env/env.ts). Se qualquer variável obrigatória faltar, a aplicação não sobe.

Variável	Obrigatória	Padrão	Descrição
`DATABASE_URL`	sim	—	URL de conexão do PostgreSQL.
`PORT`	não	`3000`	Porta HTTP da API.
`NODE_ENV`	não	`development`	Ambiente de execução.
`KEYCLOAK_AUTH_URL`	sim	—	URL do realm usado na autenticação de serviço (`/service/*`).
`KEYCLOAK_CLIENT_ID`	sim	—	Client ID da API no Keycloak.
`KEYCLOAK_CLIENT_SECRET`	sim	—	Client secret correspondente.
`KEYCLOAK_REALM_URL`	sim	—	URL do realm usado na autenticação de usuário (`/api/*`).
`REDIS_HOST`	sim	—	Host do Redis (cache de permissões/usuário).
`REDIS_PORT`	não	`6379`	Porta do Redis.
`REDIS_DB`	não	`0`	Índice do banco Redis.
`REDIS_PASS`	não	`""`	Senha do Redis.

Exemplo de .env (baseado em .env.example):

.env

PORT=3000
NODE_ENV=development

DATABASE_URL=postgresql://user:password@localhost:5432/profile_server

# Auth de usuário final
KEYCLOAK_REALM_URL=https://auth.reutilizaja.com.br/realms/teste-cleyton

# Auth app-to-app
KEYCLOAK_AUTH_URL=https://auth.reutilizaja.com.br/realms/teste-cleyton
KEYCLOAK_CLIENT_ID=api-cooperativas
KEYCLOAK_CLIENT_SECRET=troque-por-um-secret

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASS=

Subir a aplicação

# instalar dependências
pnpm install

# gerar o Prisma Client
pnpm prisma:generate

# aplicar migrations
pnpm prisma:migrate

# rodar em modo watch
pnpm start:dev

Ao subir, o console indica:

Application running on port 3000
Swagger docs available at http://localhost:3000/docs

Primeira chamada autenticada

Toda rota de usuário exige um Bearer token emitido pelo Keycloak (KEYCLOAK_REALM_URL). Com o token em mãos:

curl http://localhost:3000/api/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Uma resposta paginada típica:

{
  "data": [
    {
      "id": "u1b2c3d4-e5f6-4789-a123-456789abcdef",
      "idIdentity": "a3f5c9d2-keycloak-sub",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "type": "Admin",
      "customerId": null,
      "createdAt": "2026-07-10T12:00:00.000Z",
      "updatedAt": "2026-07-10T12:00:00.000Z"
    }
  ],
  "total": 1,
  "totalPages": 1,
  "currentPage": 1
}

Sem o header Authorization: Bearer <token> a resposta é 401 Unauthorized (Token missing). Um token inválido/expirado retorna 401 (Invalid or expired token).

Rodar esta documentação

A documentação Fumadocs vive na pasta docs/:

cd docs
pnpm install
pnpm dev   # http://localhost:3333

Pré-requisitos

Variáveis de ambiente

Subir a aplicação

Primeira chamada autenticada

Rodar esta documentação

On this page