# Deploy de app Express em produção: do nodemon a um serviço no ar

Deploy de app Express com npm start, sem watcher. Escute em 0.0.0.0 e na PORT, /health e segredos em Variables. Node.js público pode se qualificar para o Free.

Canonical URL: https://unbroker.cloud/pt/blog/express-in-production
Published: 2026-11-11
Reviewed: 2026-11-11
Author: Timoteo Borgobello

## A resposta curta

O deploy de app Express em produção deixa `nodemon` e `node --watch` na máquina de desenvolvimento. O processo de produção roda `npm start`, escuta em `0.0.0.0` e em `process.env.PORT`, responde `GET /health` e fecha o servidor no `SIGTERM`. O lockfile entra no repositório. Se o projeto é TypeScript, o build gera JavaScript e o comando de início roda esse arquivo. Os segredos ficam em Variables. A origem do navegador entra numa política de CORS explícita. `trust proxy` acompanha o ingress que está na frente da app. Uma sessão que precisa sobreviver a um restart vive fora do processo. O pool do Postgres tem um teto.

Se a busca é hospedagem Express Node.js, na Unbroker esse caminho é o preset de Node.js e o comando `npm start`. O caminho público de Node.js gerenciado pode se qualificar para o Free. Domínios próprios, repositórios privados e acesso pela CLI exigem Pro. A página do produto é [Deploy de Express](https://unbroker.cloud/deploy/express). Os passos estão em [Deploy an Express API](https://docs.unbroker.cloud/guides/deploy-express). Fastify é outro framework HTTP de Node. Este texto fica no Express.

## Desenvolvimento e produção

`nodemon` e `node --watch` reiniciam o processo quando um arquivo muda. Esse loop é da máquina em que você está editando. O [guia de Express](https://docs.unbroker.cloud/guides/deploy-express) define o script de início como `node server.cjs` e manda rodar `npm start`. Um projeto TypeScript ganha um comando de build, e o início roda o arquivo gerado no lugar de um watcher de desenvolvimento.

O guia de Express diz watcher de desenvolvimento. Não nomeia `nodemon`, `node --watch` nem `ts-node`. Ele pede para iniciar o entry point gerado.

| | No laptop | Processo de produção |
| --- | --- | --- |
| Processo | `nodemon`, `node --watch`, ou um runtime de TypeScript que reinicia quando os arquivos mudam. | `npm start`. O script do exemplo é `node server.cjs`. TypeScript inicia o arquivo que o build escreveu. |
| Endereço | Muitas vezes `localhost` e uma porta escolhida na mão. | `0.0.0.0` e `process.env.PORT`. O exemplo usa 3000 só quando `PORT` está vazia. |
| Dependências | O que a máquina local tiver instalado. | O lockfile do gerenciador de pacotes, commitado junto com o manifest. |
| Configuração | Um `.env` ao lado do código. | A view Variables do serviço. O `.env` de produção fica fora do Git. |

## Um entry point de produção

O `server.cjs` do guia é o arquivo para publicar. Ele limita o body JSON, expõe `/health`, escuta em `PORT` e em `0.0.0.0`, e fecha no `SIGTERM`.

```js
const express = require("express");
const app = express();

app.use(express.json({ limit: "100kb" }));
app.get("/health", (_request, response) => response.json({ ok: true }));
app.get("/api/message", (_request, response) => {
  response.json({ message: "Hello from Unbroker" });
});

const server = app.listen(Number(process.env.PORT || 3000), "0.0.0.0");
process.on("SIGTERM", () => server.close());
```

O guia define esse script com `npm pkg set scripts.start="node server.cjs"`. `Number(process.env.PORT || 3000)` escuta em `PORT` quando ela existe, e em 3000 quando `PORT` está vazia. O bind é `0.0.0.0`. Um processo preso em `127.0.0.1` responde à máquina em que está, e esse endereço deixa de servir quando o processo não está mais no seu laptop. O guia de Node.js diz o mesmo quando você faz deploy de uma API Node.js sem Express: escute em `0.0.0.0` e na `PORT` recebida, não num localhost fixo. Essa página é o [guia de Node.js](https://docs.unbroker.cloud/guides/deploy-nodejs). O `express.json({ limit: "100kb" })` do exemplo é o limite deste arquivo. Este texto não descreve outro limite de body.

O health check de Express no exemplo é `GET /health`, e o body é `{"ok": true}`. O guia também tem `GET /api/message`. Ele aponta a [página hello-world do Express](https://expressjs.com/en/starter/hello-world.html) pelo modelo de rotas que este exemplo usa.

### Por que o SIGTERM importa num redeploy

Um redeploy substitui o processo que está no ar. A [página de health checks do Express](https://expressjs.com/en/advanced/healthcheck-graceful-shutdown.html) diz que o process manager envia `SIGTERM` para avisar que o processo vai ser morto. A app deve parar de aceitar pedidos novos, terminar os que já estão em curso, soltar o que está segurando (a página cita conexões de banco e locks de arquivo) e então sair. `server.close()` é a chamada do exemplo do Express e do exemplo acima. O desligamento ordenado do Node no `SIGTERM` é essa sequência. Este texto não diz quanto tempo a plataforma espera antes de matar o processo.

O [guia de performance do Express](https://expressjs.com/en/advanced/best-practice-performance.html) pede `NODE_ENV=production`. Nesse modo o Express guarda em cache os templates de view, guarda em cache o CSS gerado a partir de extensões de CSS e gera mensagens de erro menos verbosas. Este texto não afirma um ganho medido por essa variável, e não diz que a Unbroker define o valor por você.

## Build, lockfile e TypeScript

Faça commit do servidor, do manifest e do lockfile. O guia de Express diz isso. O guia de Node.js diz que uma aplicação com dependências deve commitar o lockfile que o gerenciador de pacotes produziu. O install do build precisa bater com o install que você revisou.

Um projeto sem etapa de compilação pode iniciar com `node server.cjs`. Um projeto TypeScript precisa de um build que escreva JavaScript, e de um comando de início que aponte para essa saída. O guia de Node.js diz que um arquivo compilado que nunca foi gerado é uma causa típica de o processo cair. Também é um start script ausente, e uma variável de ambiente que o processo exige antes de conseguir escutar.

Rode `npm start` localmente e peça `/health` antes de conectar o repositório. O check local do exemplo é `npm start` e um pedido a `/api/message`.

## Configuração e segredos

Coloque os segredos na view Variables do serviço. Deixe os `.env` de produção fora do Git. Defina as variáveis antes do deploy. Essas três frases são o guia de Express e o guia de Node.js.

Um valor no repositório fica no histórico. Um valor que só está em Variables fica no serviço. Como uma variável se limita a produção ou a um preview, e quando é preciso fazer redeploy, está em [Variáveis de ambiente e segredos](https://unbroker.cloud/pt/blog/environment-variables-and-secrets). Os passos estão em [Configure environment variables and secrets](https://docs.unbroker.cloud/guides/environment-variables).

## CORS, proxies e cookies

Se o frontend vive em outra origem, permita essa origem na política de CORS. O guia de Express diz que um endpoint JSON que responde no terminal não prova que o navegador pode chamá-lo. Autenticação com cookie precisa de uma política de cookie e de uma política de CSRF pensadas. Este texto não escolhe um valor de `SameSite` nem um pacote de CORS.

O trust proxy do Express é o jeito como o Express lê os headers que um proxy reverso acrescenta. A [página de proxies do Express](https://expressjs.com/en/guide/behind-proxies.html) diz que algumas APIs devolvem outros valores atrás de um proxy reverso, e que `trust proxy` é o ajuste. O caso que ela cita é o IP do cliente aparecendo como o endereço do próprio proxy.

O padrão é `false`: a app é tratada como se estivesse de frente para o cliente, e o IP sai de `req.socket.remoteAddress`. `true` toma o IP do cliente como a entrada mais à esquerda de `X-Forwarded-For`. O Express avisa que, com `true`, o último proxy reverso precisa remover ou reescrever `X-Forwarded-For`, `X-Forwarded-Host` e `X-Forwarded-Proto`. Senão, o cliente pode mandar qualquer valor. A página também aceita um número de saltos, uma lista de endereços de proxy ou uma função. Um número de saltos fica errado quando o cliente consegue chegar à app por um caminho mais curto do que o número configurado.

Com o ajuste ligado, `req.hostname` vem de `X-Forwarded-Host`, `req.protocol` vem de `X-Forwarded-Proto`, e `req.ip` / `req.ips` são preenchidos a partir do socket e de `X-Forwarded-For`. `X-Forwarded-Proto` pode ser `https`, `http` ou um nome que não é nenhum dos dois. O guia de Express diz para não ligar uma confiança de proxy sem limite só para os redirects funcionarem. Configure o comportamento para o ingress que você tem, e confira como a app decide que um pedido é HTTPS antes de se apoiar num cookie secure ou no IP do cliente. Este texto não nomeia os saltos do proxy da Unbroker.

## Sessões, réplicas e estado

Uma sessão guardada no processo pertence a esse processo. O guia de performance do Express diz que as instâncias não compartilham memória, então não dá para manter estado no código da aplicação. Ele cita o Redis como um lugar para dados de sessão, e diz que o mesmo limite vale para escalonamento horizontal em geral, não só para um cluster de processos numa máquina. Também diz que uma app sem estado não guarda dados locais no processo, e cita sessões como esse tipo de dado.

O guia de Express pede para manter as sessões fora da memória do processo quando elas precisam durar, ou quando mais de uma réplica vai atender a app. O guia de Node.js pede para mover sessões ou registros para um banco antes de escalar entre réplicas. Arquivos no filesystem do contêiner são temporários, a menos que vão para um volume persistente configurado. Esse volume exige Pro. A tabela de planos lista volumes persistentes como indisponíveis no Free.

O Free roda uma réplica, até 250m de CPU e 256 MiB, e sempre dorme quando fica idle. A [página de preços](https://unbroker.cloud/pt/precos) diz que a memória e os arquivos temporários são zerados quando uma app Free dorme. Uma sessão que só vivia nesse processo some com o sono, e some quando um processo novo substitui o antigo num redeploy. O Pro pode configurar réplicas, até o limite da célula compartilhada na [tabela de planos](https://docs.unbroker.cloud/billing/plans). Autoscaling de réplicas não está no Free. Como as cópias entram está em [Autoscaling de réplicas](https://unbroker.cloud/pt/blog/replica-autoscaling). Redis como lugar para sessões, cache e filas está em [Redis gerenciado](https://unbroker.cloud/pt/blog/managed-redis-cache-queues). Este texto não escolhe um store de sessão, e não diz que a plataforma prende um navegador a uma réplica.

## Conexões com o banco

O exemplo do guia de Express não tem banco. Quando você adiciona Postgres, o [guia de Node.js e PostgreSQL](https://docs.unbroker.cloud/guides/api-with-postgres) parte da Unbroker Pro e de um PostgreSQL que já existe. Bancos gerenciados não estão no Free. Você ainda escolhe um nó de Apps ou um cluster gerenciado. Um nó de Apps é um serviço privado que você opera: imagem, volume, upgrades e recuperação. Um cluster gerenciado deixa o host com o provedor. Mapeie a conexão para o nome que a sua app lê. O exemplo espera `DATABASE_URL` e lança um erro se ela falta. Esse valor vai em Variables. Não desligue a verificação do certificado para conseguir uma conexão. Operar o banco está em [Postgres em produção](https://unbroker.cloud/pt/blog/postgres-in-production).

Limite o pool. O exemplo de Express do guia é:

```js
const { Pool } = require("pg");
if (!process.env.DATABASE_URL) throw new Error("DATABASE_URL is required");

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 5,
  connectionTimeoutMillis: 5000,
  idleTimeoutMillis: 30000,
  statement_timeout: 5000,
});
```

`max` vale por processo. A conta do guia é três réplicas com um pool de cinco, que podem abrir quinze conexões, antes de jobs e ferramentas de administração. Deixe folga abaixo do limite de conexões do banco. Chame `pool.end()` no desligamento, depois de drenar os pedidos HTTP. Isso fica ao lado de `server.close()`, que para os pedidos novos para os que já estão abertos poderem terminar.

Deixe `GET /health` como um check barato do processo. O guia acrescenta `GET /ready`, que roda `SELECT 1` e devolve 503 quando essa query falha. Ele diz para separar o check do processo quando um incidente de banco não deve ser lido como um processo HTTP doente. A página de health checks do Express usa o Kubernetes como exemplo de dois checks: liveness decide quando reiniciar um contêiner, e readiness decide quando ele pode receber tráfego. Esses são os nomes da página para o Kubernetes. Este texto não diz que o caminho de health check da Unbroker é uma dessas duas probes.

Aplique mudanças de schema como um passo de release próprio, com as credenciais de runtime, e então faça o deploy. Comandos de migração exigem Pro. O que um rollback de código deixa no schema está em [Migrações de banco de dados no deploy](https://unbroker.cloud/pt/blog/database-migrations-on-deploy). Estime a API e o banco em separado. O guia de Express diz que o banco e os outros recursos pagos entram na [estimativa do plano](https://unbroker.cloud/pt/precos).

## Falhas comuns

A tabela do guia de Express é a lista para usar antes de mudar o tamanho da máquina.

| Sintoma | O que inspecionar |
| --- | --- |
| O serviço não fica saudável | Endereço de escuta, `PORT`, script de início e resposta de `/health` |
| A API devolve 404 | Prefixo da rota e método HTTP, incluindo qualquer base URL do frontend |
| O navegador bloqueia uma API que funciona | A resposta de CORS e a origem do frontend permitida |
| O login para de funcionar depois de um deploy | Persistência da sessão, cookies e o segredo de assinatura |

Leia os logs de runtime para separar um erro da aplicação de um erro do deploy. O guia de Node.js diz para fazer isso quando o processo cai. Por onde começar quando um release falha está em [Depurar um deploy que falhou](https://unbroker.cloud/pt/blog/debug-failed-deployment). Para que servem logs, métricas e alertas está em [Logs, métricas e alertas](https://unbroker.cloud/pt/blog/logs-metrics-alerts). Logs de runtime existem no Free e no Pro. A tabela de planos lista métricas de recursos como indisponíveis no Free e disponíveis no Pro.

## Como funciona na Unbroker

No Cloud, adicione um serviço de repositório, escolha Node.js e deixe o comando de início em `npm start`. Se o projeto compila TypeScript, configure o build e inicie o arquivo gerado. Coloque os segredos em Variables. Faça o deploy e então peça `/health` na URL que o Cloud mostra. No Pro, configure o caminho do health check para essa rota.

O caminho público de Node.js gerenciado pode se qualificar para o Free. Apps Node.js públicas que entram nessa condição podem usar o Free pelo Cloud. A [tabela de planos](https://docs.unbroker.cloud/billing/plans) lista Node.js gerenciado como incluído no Free. Domínios próprios, credenciais de repositório privado e acesso pela CLI exigem Pro. Criar um token de API exige Pro. Builds de Dockerfile não estão no Free e estão no Pro. Fazer deploy desta API a partir de um Dockerfile é esse outro caminho, e este texto não o descreve como caminho Free.

O Free é um projeto, dois serviços e três pedidos de deploy por dia UTC. Cada serviço Free roda uma réplica, até 250m de CPU e 256 MiB, e dorme quando fica idle. O primeiro pedido depois de um sono pode demorar mais enquanto o processo sobe. O Pro custa $25 por mês com $25 de crédito de uso. O crédito reinicia a cada ciclo de cobrança, não acumula e não tem valor em dinheiro. Se o uso elegível fica abaixo do crédito, a cobrança mensal continua o preço do plano. Se o uso elegível passa do crédito, só a diferença é somada. Esses termos estão em [preços](https://unbroker.cloud/pt/precos) e em [Plans](https://docs.unbroker.cloud/billing/plans). Conte a API e qualquer banco como linhas separadas. O caminho genérico de Node é [Deploy de Node.js](https://unbroker.cloud/deploy/nodejs) e [Deploy a Node.js application](https://docs.unbroker.cloud/guides/deploy-nodejs). Esses mesmos tetos do Free, inclusive o sono quando não há tráfego, estão em [um plano de $0 para uma API Node pequena](https://unbroker.cloud/pt/blog/free-backend-hosting).

## Checklist

1. Aponte `npm start` para `node server.cjs`, ou para o JavaScript que o build emitiu. Deixe `nodemon` e `node --watch` fora desse script.
2. Escute em `0.0.0.0`. Leia `PORT`. O exemplo usa 3000 só quando `PORT` está vazia.
3. Sirva `GET /health`. No Pro, configure o caminho do health check para essa rota.
4. Chame `server.close()` no `SIGTERM`. Chame `pool.end()` depois de drenar os pedidos, se a app tem um pool.
5. Faça commit do lockfile com o manifest. Uma app TypeScript faz o build primeiro e inicia o arquivo gerado.
6. Coloque os segredos em Variables. Deixe os `.env` de produção fora do Git.
7. Permita a origem do frontend no CORS. Configure `trust proxy` para o ingress que você tem, não como `true` de atalho.
8. Mantenha as sessões fora do processo se elas precisam sobreviver a um restart, a um sono do Free ou a mais de uma réplica.
9. Coloque um teto no pool. O exemplo do guia é `max: 5`, e esse máximo é por processo.
10. Abra `/health` depois do deploy. Leia os logs de runtime antes de aumentar CPU ou memória.

## Perguntas frequentes

### Posso rodar nodemon ou node --watch em produção?

Deixe os dois fora do script de início. O guia de Express define scripts.start como node server.cjs e o comando do serviço como npm start. nodemon e node --watch reiniciam o processo quando um arquivo muda. Isso é o loop da máquina em que você está editando. Se o projeto compila TypeScript, o mesmo guia pede um comando de build e manda iniciar o arquivo gerado, no lugar de um watcher de desenvolvimento. O watcher espera a árvore de trabalho. O release roda o comando que você configurou.

### Por que a app Express funciona localmente e some depois do deploy?

Olhe o endereço, a porta e o script de início. O exemplo escuta em 0.0.0.0 e em Number(process.env.PORT || 3000): se PORT está vazia, cai para 3000. O guia de Node.js diz que um build que terminou bem não prova que o servidor está alcançável. O processo precisa escutar em 0.0.0.0 e na PORT que recebe, não num localhost fixo. Se o serviço cai, o mesmo guia cita um start script ausente, um arquivo compilado que nunca foi gerado, ou uma variável de ambiente exigida na subida. Na tabela de falhas, um serviço que não fica saudável é o endereço, a PORT, o script e a resposta de /health.

### Devo definir app.set('trust proxy', true)?

Não como padrão. A página de proxies do Express diz que o padrão é false: a app é tratada como se estivesse de frente para o cliente, e o IP sai de req.socket.remoteAddress. true lê o IP do cliente como a entrada mais à esquerda de X-Forwarded-For. A mesma página avisa que, com true, o último proxy reverso precisa remover ou reescrever X-Forwarded-For, X-Forwarded-Host e X-Forwarded-Proto. Senão, o cliente pode enviar qualquer valor. O guia de Express diz para não ligar uma confiança de proxy sem limite só para os redirects funcionarem. Configure para o ingress que você realmente tem, e confira como a app lê HTTPS antes de confiar num cookie secure ou no IP do cliente. Este texto não escolhe um número de saltos.

### Como desligo um servidor Express com ordem num redeploy?

Feche o servidor HTTP quando o processo recebe SIGTERM. A página de health checks do Express diz que uma versão nova começa com o process manager enviando SIGTERM, para a app parar de aceitar pedidos novos, terminar os que já estão em curso, soltar recursos como conexões de banco e locks de arquivo, e então sair. O exemplo dessa página, e o da Unbroker, chamam server.close() nesse handler. O guia de Postgres pede pool.end() depois de drenar os pedidos HTTP. Este texto não diz quanto tempo a plataforma espera antes de matar o processo.

### Onde ficam os segredos do Express em produção?

Na view Variables do serviço, não num .env de produção dentro do Git. Essa é a instrução do guia de Express. Defina as variáveis da aplicação antes do deploy, que é o que o guia de Node.js diz. Como elas se dividem está em [Variáveis de ambiente e segredos](https://unbroker.cloud/pt/blog/environment-variables-and-secrets).

### Posso fazer deploy de uma API Express no plano Free da Unbroker?

O caminho público de Node.js gerenciado pode se qualificar para o Free. Apps Node.js públicas que entram nessa condição podem usar o Free pelo Cloud. Domínios próprios, repositórios privados e acesso pela CLI exigem Pro. Tokens de API e o fluxo de deploy pela CLI também exigem Pro. A tabela de planos marca Node.js gerenciado como incluído no Free, e builds de Dockerfile como indisponíveis no Free. Um Dockerfile é outro caminho. No Pro, o guia de Express diz para configurar o caminho do health check para bater com a rota. O Pro custa $25 por mês com $25 de crédito de uso. Os passos estão em [Deploy de Express](https://unbroker.cloud/deploy/express) e no [guia de Express](https://docs.unbroker.cloud/guides/deploy-express).

## Related reading

- [Deploy de Express](https://unbroker.cloud/deploy/express)
- [Deploy de Node.js](https://unbroker.cloud/deploy/nodejs)
- [Variáveis de ambiente e segredos](https://unbroker.cloud/pt/blog/environment-variables-and-secrets)
- [Postgres em produção](https://unbroker.cloud/pt/blog/postgres-in-production)
- [Migrações de banco de dados no deploy](https://unbroker.cloud/pt/blog/database-migrations-on-deploy)
- [Autoscaling de réplicas](https://unbroker.cloud/pt/blog/replica-autoscaling)
- [Redis gerenciado](https://unbroker.cloud/pt/blog/managed-redis-cache-queues)
- [Depurar um deploy que falhou](https://unbroker.cloud/pt/blog/debug-failed-deployment)
- [Logs, métricas e alertas](https://unbroker.cloud/pt/blog/logs-metrics-alerts)
- [Preços](https://unbroker.cloud/pt/precos)
- [Tetos do plano Free para uma API Node](https://unbroker.cloud/pt/blog/free-backend-hosting)
