Como fazer deploy de uma API Node.js no Hangar

Uma API publicada precisa de um processo que escute na porta configurada, um comando de início e uma forma de verificar a resposta. Neste guia, você prepara uma API pequena em Node.js e segue o caminho do GitHub até o painel do Hangar.

O exemplo usa apenas módulos nativos. Ele não tem autenticação nem banco e serve para validar a publicação antes de acrescentar a lógica do seu produto.

Prepare três arquivos

Use Node.js 24 para executar o exemplo. Crie package.json:

{
  "name": "minha-api",
  "private": true,
  "type": "module",
  "engines": { "node": "24.x" },
  "scripts": {
    "start": "node server.mjs",
    "check": "node --check app.mjs && node --check server.mjs",
    "test": "node --test"
  }
}

Em app.mjs, separe a resposta HTTP da abertura da porta:

import { createServer } from "node:http";

export function createApp() {
  return createServer((request, response) => {
    const healthy = request.method === "GET" && request.url === "/health";
    response.writeHead(healthy ? 200 : 404, {
      "Content-Type": "application/json; charset=utf-8",
    });
    response.end(JSON.stringify(healthy ? { status: "ok" } : { error: "not_found" }));
  });
}

Em server.mjs, use a porta do ambiente e um endereço acessível pelo roteamento do container:

import { createApp } from "./app.mjs";

const port = Number(process.env.PORT ?? "3000");
if (!Number.isInteger(port) || port < 1 || port > 65535) {
  throw new Error("PORT deve ser uma porta válida entre 1 e 65535.");
}

const server = createApp();
server.listen(port, "0.0.0.0", () => {
  console.log(`API escutando na porta ${port}`);
});

function shutdown() {
  server.close(() => process.exit(0));
  setTimeout(() => process.exit(1), 10000).unref();
}

process.once("SIGTERM", shutdown);
process.once("SIGINT", shutdown);

O endereço explícito evita depender da configuração do framework. O Node, quando recebe uma porta e nenhum host, pode escutar em :: ou 0.0.0.0; omitir o host não significa necessariamente limitar o servidor a localhost. Veja a documentação de server.listen.

Verifique localmente antes de publicar

Na pasta do projeto, execute:

npm install --package-lock-only
npm run check
npm start

Abra http://localhost:3000/health: a resposta esperada é status HTTP 200 com {"status":"ok"}. Outra rota deve responder 404. Interrompa o processo com Ctrl+C depois da verificação.

Versione os três arquivos e o package-lock.json em seu repositório GitHub. Mantenha .env e credenciais fora do Git. Para acrescentar um teste automatizado à API, siga o guia de GitHub Actions.

Conecte o código ao Hangar

Crie sua conta e escolha um plano com capacidade para o projeto. Quando houver trial, duração e condições aparecem na contratação; não há plano gratuito permanente.

No workspace, crie um projeto e um ambiente. Adicione uma aplicação, autorize o repositório GitHub e confira a branch e a pasta que contém o package.json. Selecione o build por Railpack ou use o Dockerfile do guia Node.js.

Para esta API em JavaScript, não há compilação. O comando de início é npm start. Confira a versão do Node nos logs de build e configure PORT=3000 com a porta do serviço correspondente. Se o formulário já oferecer uma porta, mantenha o mesmo valor na aplicação e no serviço.

Publique e confirme o resultado

Inicie o deploy pelo painel. Acompanhe separadamente o build e o estado da aplicação: aceitar a solicitação de deploy ainda não confirma que a API está disponível.

Quando o serviço estiver ativo, use o endereço informado no painel e acesse /health. Verifique o status HTTP, o corpo da resposta e os logs. Um endpoint de saúde criado no código só participa das verificações da plataforma quando a configuração correspondente o utiliza.

Sintoma	Primeira verificação
Build não encontra arquivos	Repositório, branch e pasta de origem
Processo encerra ao iniciar	Comando de início, versão do Node e logs
Aplicação não responde	Porta do serviço e endereço de escuta
/health retorna 404	Caminho exato e versão publicada

Adicione domínio e dados quando precisar

Cadastre seu domínio no serviço, copie os registros DNS exibidos e aguarde a validação do domínio e do certificado. Teste o endereço HTTPS antes de divulgá-lo.

Se a aplicação precisar de PostgreSQL, crie o banco no ambiente e configure a conexão nas variáveis da aplicação. Credenciais, permissões, TLS e migrações precisam corresponder ao banco escolhido. Não acrescente comandos de migração ao build sem definir acesso, concorrência e recuperação.

O PostgreSQL do Hangar ainda não oferece backup, restauração ou recuperação pontual nativos. Para dados que precisam ser recuperáveis, prepare cópias externas e ensaie a restauração antes de usá-los em produção.

Depois do primeiro deploy, você pode ativar publicação por push na branch configurada, acompanhar logs e métricas e ajustar CPU, memória e réplicas manualmente dentro do plano. O guia inicial reúne o fluxo da plataforma para o próximo projeto.