Como fazer deploy de uma API Node.js na AWS sem VPS, com Lambda e API Gateway

Um post no TabNews lista os três erros que derrubam o primeiro deploy de uma API Node.js. Aqui está o mesmo problema resolvido com Lambda e API Gateway, sem servidor para gerenciar.

Um post no TabNews lista os três erros que derrubam o primeiro deploy de uma API Node.js. Aqui está o mesmo problema resolvido com Lambda e API Gateway, sem servidor para gerenciar.

Um post publicado no TabNews por GabrielAugusto, fundador da Hyze Cloud, resume em cinco passos como tirar uma API Node.js do localhost:3000 e colocá-la no ar sem alugar um VPS. O guia é genérico o bastante para valer em qualquer plataforma baseada em container, e o próprio autor cita Railway, Render e Fly como alternativas.

Para quem trabalha com Lambda e API Gateway no dia a dia, o caminho nativo da AWS resolve o mesmo problema por outra rota: em vez de um container ligado 24 horas, a API só existe (e só custa) quando alguém faz uma requisição. Este tutorial pega os três erros que o post do TabNews aponta como responsáveis pela maioria dos deploys quebrados e mostra como evitá-los ao publicar a mesma API via Lambda e API Gateway.

O que você vai construir

Uma API Express com uma rota /health, empacotada como função Lambda e exposta por uma HTTP API do API Gateway. Sem servidor para corrigir, sem porta para abrir manualmente, sem custo enquanto ninguém chama o endpoint.

O código roda igual em dois lugares: na sua máquina, com node src/local.js escutando em localhost, e na AWS, dentro do runtime do Lambda, sem escutar porta nenhuma de verdade (quem recebe a conexão TCP é o API Gateway). Essa separação resolve de cara o erro número um apontado pelo post do TabNews.

Pré-requisitos

• Conta AWS com um usuário IAM que tenha permissão para cloudformation:*, lambda:*, apigateway:*, iam:CreateRole, iam:PassRole, s3:PutObject (bucket de deploy do SAM) e logs:*. Para um ambiente de estudo, a policy gerenciada AdministratorAccess resolve; em produção, restrinja por recurso.
• AWS CLI v2 instalado e configurado (aws configure), apontando para a região sa-east-1.
• AWS SAM CLI instalado em uma versão recente (sam --version para conferir).
• Node.js 20.x instalado localmente, a mesma versão do runtime nodejs20.x que a função vai usar na nuvem.
• curl para os testes de fora, igual ao usado no post original.

Não é preciso Docker: o pacote vai como .zip, não como imagem de container, então o build do SAM roda direto com Node.js local.

Passo a passo

1. Criar o projeto e instalar as dependências

mkdir api-lambda && cd api-lambda
npm init -y
npm install express @codegenie/serverless-express

A biblioteca @codegenie/serverless-express traduz o evento que o API Gateway manda para o Lambda num objeto req/res que o Express entende. É essa camada que permite reaproveitar o mesmo app Express em dois contextos de execução diferentes.

2. Separar o app Express do handler

Crie src/app.js com a lógica da API, sem nenhuma chamada a listen():

import express from "express";

const app = express();

app.get("/health", (_req, res) => res.json({ ok: true, ts: Date.now() }));

export default app;

Essa separação é o que deixa o mesmo código rodar local e na Lambda: quem decide como a requisição chega até o Express muda, a lógica de negócio não.

3. Escrever o handler Lambda

Crie src/handler.js:

import serverlessExpress from "@codegenie/serverless-express";
import app from "./app.js";

let cachedHandler;

export const handler = async (event, context) => {
  cachedHandler = cachedHandler ?? serverlessExpress({ app });
  return cachedHandler(event, context);
};

O cache em cachedHandler evita recriar o adaptador a cada invocação quente, reduzindo a latência das chamadas subsequentes à primeira (o cold start).

4. Manter um modo de desenvolvimento local

O post do TabNews insiste em dois detalhes: escutar em 0.0.0.0 e ler a porta de process.env.PORT. Em Lambda isso não existe (não há porta TCP real), mas o hábito continua valendo para rodar e testar localmente antes do deploy. Crie src/local.js:

import app from "./app.js";

const port = Number(process.env.PORT) || 3000;
app.listen(port, "0.0.0.0", () => console.log(`rodando na ${port}`));

E em package.json:

{
  "type": "module",
  "scripts": {
    "start": "node src/local.js"
  }
}

Rode npm start e confira curl localhost:3000/health antes de ir para a nuvem. É a mesma recomendação do post original: se falha localmente, vai falhar no deploy.

5. Tirar segredos do código

O terceiro erro do post é subir senha ou token dentro do código. Para a versão AWS, a variável não vai num .env solto: vai no Systems Manager Parameter Store, como SecureString:

aws ssm put-parameter \
  --name "/api-lambda/db-password" \
  --value "minha-senha-de-exemplo" \
  --type SecureString \
  --region sa-east-1

E o template referencia o parâmetro por uma dynamic reference, sem nunca gravar o valor em texto plano no repositório.

6. Escrever o template do SAM

Crie template.yaml na raiz do projeto:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Resources:
  ApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/
      Handler: handler.handler
      Runtime: nodejs20.x
      Architectures: [arm64]
      MemorySize: 256
      Timeout: 10
      Environment:
        Variables:
          DB_PASSWORD: '{{resolve:ssm-secure:/api-lambda/db-password:1}}'
      Events:
        Api:
          Type: HttpApi
          Properties:
            Path: /{proxy+}
            Method: ANY

O Path: /{proxy+} com Method: ANY manda toda rota e todo verbo HTTP para a mesma função, deixando o roteamento por conta do Express, exatamente como ele já faz localmente.

7. Build e deploy

sam build
sam deploy --guided

No modo guiado, informe um nome de stack (api-lambda-stack), confirme a região sa-east-1 e aceite a criação da role do IAM. O SAM pode criar um bucket S3 próprio para artefatos de deploy durante esse processo; se isso acontecer, guarde o nome dele, pois ele reaparece na etapa de limpeza.

Ao final, o output ApiUrl traz a URL pública, no formato https://ABC123.execute-api.sa-east-1.amazonaws.com.

8. Ler o log quando algo falhar

O post do TabNews lista os motivos mais comuns de falha e recomenda ler o log. Na AWS, o comando equivalente é:

sam logs -n ApiFunction --stack-name api-lambda-stack --tail

O erro que mais derruba o primeiro deploy: o servidor sobe escutando só em localhost.

GabrielAugusto, autor do post no TabNews

No mundo Lambda esse erro específico não existe (não há listen() em produção), mas o equivalente é esquecer de exportar o handler certo no template.yaml, ou apontar Handler para um arquivo que não existe no pacote enviado.

Testando

Com a URL do output em mãos, repita o teste de fora que o post recomenda:

curl -i https://ABC123.execute-api.sa-east-1.amazonaws.com/health

A resposta esperada é HTTP/2 200 com o corpo {"ok":true,"ts":1761...}. Se vier 403 ou 404, o problema costuma estar no Path do template ou numa rota que não bate com o que o Express espera. Se vier 502, o handler lançou uma exceção antes de responder, e o log do sam logs mostra o stack trace.

Vale notar o cold start: a primeira chamada depois de um tempo sem tráfego tende a demorar mais do que as seguintes, porque a AWS precisa inicializar o ambiente de execução antes de rodar o código. Chamadas seguintes, enquanto o ambiente fica quente, costumam responder mais rápido.

Limpando os recursos

Apagar tudo criado nesse tutorial evita cobrança residual:

sam delete --stack-name api-lambda-stack

Esse comando remove a função Lambda, a role do IAM, a HTTP API do API Gateway e o stack do CloudFormation. Três coisas o sam delete não apaga sozinho:

• O parâmetro no SSM: aws ssm delete-parameter --name "/api-lambda/db-password" --region sa-east-1.
• O bucket S3 de artefatos do SAM, se ele não foi criado como gerenciado: aws s3 rb s3://NOME-DO-BUCKET --force.
• O log group no CloudWatch, que fica com retenção indefinida por padrão e segue gerando um custo pequeno de armazenamento: aws logs delete-log-group --log-group-name /aws/lambda/api-lambda-stack-ApiFunction-XXXX.

Próximos passos

Esse desenho atende bem uma API pequena, com tráfego irregular: dentro da camada gratuita do Lambda, que cobre um volume mensal de requisições e tempo de computação sem prazo de expiração (os números exatos estão na documentação oficial da AWS, que vale consultar antes de planejar custo), o gasto tende a ficar baixo ou zerado. O free tier do API Gateway também ajuda nos primeiros meses de uma conta nova; depois desse período, a cobrança passa a ser por volume de requisições processadas.

Isso é diferente do modelo do post original, em que a Hyze Cloud cobra R$ 5,99 por mês fixos, independente de tráfego. Para uma API que recebe poucas chamadas, o caminho serverless tende a sair mais barato; para uma API com tráfego constante e alto, o custo por requisição pode superar uma mensalidade fixa, e aí vale comparar com Fargate, que mantém um container rodando o tempo todo.

Alguns pontos para aprofundar depois deste tutorial:

• Domínio próprio: o API Gateway aceita custom domain names, combinados com um certificado do ACM e um registro no Route 53, para trocar a URL execute-api.amazonaws.com por algo como api.seudominio.com.br.
• Timeout de requisição: toda chamada via API Gateway REST ou HTTP API tem um limite de tempo de execução (consulte a documentação oficial da AWS para o valor vigente); rotas que processam algo demorado (upload grande, processamento pesado) precisam de outro desenho, como fila mais Lambda assíncrona.
• Provisioned concurrency: se o cold start incomodar numa rota crítica, o Lambda oferece um recurso para manter execuções já aquecidas (consulte a documentação oficial da AWS para detalhes de configuração e custo).
• Fargate como alternativa: para uma API que já roda como container Docker e precisa de estado em memória entre requisições, ou de tráfego alto e constante, migrar o mesmo container para o Fargate evita reescrever o código para um handler Lambda.

Fonte

GabrielAugusto. "Como colocar uma API Node.js no ar sem VPS (e os 3 erros que derrubam o primeiro deploy)". TabNews.

Fonte: TabNews