Como fazer deploy de uma aplicação NestJS no Brasil

NestJS tem uma pegadinha na hora de deploy que não existe em projetos Express puros: o build do TypeScript precisa rodar antes do container iniciar, e a imagem de produção não deveria carregar o compilador nem os arquivos .ts. Muita gente resolve isso com imagens de 1GB ou com um Dockerfile que copia tudo pra dentro. Dá pra fazer melhor.

Este tutorial cobre o caminho inteiro, do Dockerfile multi-stage até o serviço rodando com HTTPS na Guara Cloud, em infraestrutura no Brasil.

Resposta rápida

Para publicar uma aplicação NestJS no Brasil, compile o TypeScript em um estágio de build do Dockerfile, copie apenas o diretório dist e as dependências de produção para a imagem final, escute na porta definida por ENV PORT e publique o container na Guara Cloud. A plataforma cuida de HTTPS, domínio público, logs e cobra em Real.

Principais pontos

• Use Dockerfile multi-stage. O estágio de build compila TypeScript, o estágio final carrega só dist/ e node_modules de produção.
• Leia PORT do ambiente. Não hardcode 3000.
• Use o ConfigModule do NestJS para ler variáveis de ambiente com tipagem.
• Configure segredos pelo painel da Guara Cloud, nunca no repositório.
• Adicione um health check com @nestjs/terminus para a plataforma saber quando o serviço está pronto.

Quando este tutorial se aplica

Use este fluxo para APIs REST, GraphQL (com Apollo ou Mercurius) e microsserviços construídos com NestJS. Se a aplicação usa fila (BullMQ), websocket (Gateway) ou gRPC, o container funciona da mesma forma. A diferença fica nas portas expostas e nas variáveis de ambiente.

Quando não usar este fluxo

Se a aplicação é puramente um worker sem porta HTTP (só consome fila), o deploy é similar mas você não precisa do health check HTTP. Se o projeto usa serverless (Lambda, Cloud Functions), este guia não se aplica. Para monorepos com Nx onde vários apps NestJS convivem, ajuste os caminhos de build no Dockerfile para apontar para o app correto.

1. Configure a porta via variável de ambiente

O NestJS padrão escuta em 3000. Em container, a plataforma define a porta. Abra src/main.ts e ajuste:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
const app = await NestFactory.create(AppModule);
const port = Number(process.env.PORT ?? 3000);
await app.listen(port, '0.0.0.0');
}
bootstrap();

O 0.0.0.0 é obrigatório. Sem ele, a aplicação escuta apenas no loopback e o balanceador de carga não consegue alcançar o container.

2. Dockerfile multi-stage para NestJS

Aqui está o ponto que separa uma imagem de 50MB de uma de 800MB. O primeiro estágio instala tudo, compila TypeScript e roda os testes se quiser. O segundo estágio copia só o que precisa pra rodar.

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=builder /app/dist ./dist
ENV NODE_ENV=production
CMD ["node", "dist/main.js"]

Esse Dockerfile produz uma imagem com aproximadamente 80MB. O npm ci --omit=dev no estágio final garante que TypeScript, ESLint e Jest não vão pra produção.

3. Configure variáveis de ambiente com ConfigModule

O NestJS tem um módulo oficial para tipar e validar variáveis de ambiente. Se ainda não instalou:

npm install @nestjs/config

Depois, registre no AppModule:

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';

@Module({
imports: [
  ConfigModule.forRoot({
    isGlobal: true,
  }),
],
})
export class AppModule {}

No painel da Guara Cloud, configure as variáveis que a aplicação consome:

Nunca commite .env no repositório. Use .env.example como referência com valores fictícios.

4. Adicione health check

A Guara Cloud usa probes HTTP para decidir se o container está saudável. Instale o Terminus e crie um endpoint simples:

npm install @nestjs/terminus

import { Controller, Get } from '@nestjs/common';
import { HealthCheckService, HealthCheck, HttpHealthIndicator } from '@nestjs/terminus';

@Controller('health')
export class HealthController {
constructor(
  private health: HealthCheckService,
  private http: HttpHealthIndicator,
) {}

@Get()
@HealthCheck()
check() {
  return this.health.check([
    () => this.http.pingCheck('ping', 'https://www.google.com'),
  ]);
}
}

Para algo mais simples (sem dependências externas), basta retornar { status: 'ok' } em /health. A plataforma só precisa de um 200 OK.

5. Faça o deploy na Guara Cloud

Com o repositório no GitHub e o Dockerfile na raiz, o processo na Guara Cloud é:

O build roda o Dockerfile completo: instala dependências, compila TypeScript, gera a imagem final. O primeiro deploy leva entre 2 e 4 minutos dependendo do tamanho do projeto. Deploys seguintes são mais rápidos por causa do cache de camadas Docker.

6. Valide o serviço em produção

Após o deploy completar, verifique:

• A URL pública responde com 200.
• O endpoint /health retorna status ok.
• Os logs mostram a aplicação escutando na porta correta.
• O consumo de CPU e memória está dentro do esperado (no painel da Guara Cloud, aba de observabilidade).

Se algo falhar, os logs de build e de runtime ficam disponíveis no painel. A maioria dos problemas aparece nos primeiros segundos.

Dicas de performance para NestJS em container

Algumas configurações fazem diferença real quando a aplicação está sob carga:

• Limite de workers. O NestJS não clusteriza sozinho. Se precisar de múltiplos processos, use o @nestjs/microservices com múltiplas réplicas na Guara Cloud (escale horizontalmente) em vez de PM2 dentro do container.

• Lazy loading de módulos. Módulos carregados com LazyModuleLoader reduzem o tempo de cold start em aplicações com muitos módulos que nem toda request usa.

• Fastify em vez de Express. Troque o adapter para @nestjs/platform-fastify se a API recebe mais de mil requests por segundo. A diferença de throughput é mensurável.