Como instalar o Node.js no Saplo (backend próprio a partir do repositório)

O Node.js não é um framework, mas sim um runtime JavaScript do lado do servidor - ao contrário do Next.js ou Nuxt, a stack "Node.js" no Catálogo da Saplo não impõe qualquer convenção ou estrutura de projeto. Podes escrever o teu próprio servidor HTTP em Express, Fastify, Koa, NestJS ou sem qualquer framework, e a Saplo apenas garante que o processo está sempre a funcionar e que reinicia após uma falha. Esta é a opção mais universal para o backend no Catálogo: é adequada para APIs para aplicações móveis, bots do Discord ou servidores de websockets, desde que o projeto exponha a sua própria porta HTTP.

Para quem é o Node.js no Saplo

Antes de começares a instalação, verifica se é a escolha certa para o teu projeto:

• API para uma aplicação móvel ou frontend SPA - expões REST ou GraphQL, e o frontend (React, Vue) instalas separadamente no mesmo diretório,
• bot ou integração a correr em segundo plano - webhooks, bots para Discord e Slack, workers de filas,
• backend para websockets - o nginx do lado do Saplo permite o cabeçalho Upgrade, para que as ligações de longa duração funcionem sem configuração adicional,
• tens um projeto Node.js pronto e queres implementações com git push - ligas o repositório uma vez, e o Saplo constrói e reinicia o processo automaticamente.

Se o teu projeto está num framework específico com a sua própria convenção de construção e arranque (Next.js, Nuxt), escolhe a sua stack dedicada no catálogo - terás uma configuração pronta sem teres de especificar o comando de arranque manualmente.

Requisitos

Para instalares o Node.js no Saplo, precisas de:

• Uma Box no plano L ou superior - o processo Node é mantido constantemente na memória, por isso precisa de mais RAM do que uma página estática,
• No mínimo 512 MB de RAM livre e 3 GB de espaço em disco para o processo da aplicação,
• Um domínio ou subdomínio *.saploapp.pl incluído no preço de qualquer plano,
• Um repositório Git, se quiseres usar a implementação automática (opcional para começar, também podes carregar a aplicação como um arquivo .zip através do painel).

Instalação passo a passo

1. No Painel Saplo, vai a Catálogo de aplicações e escolhe Node.js (categoria "Aplicações").
2. Indica uma Box no plano L ou superior e o nome da aplicação - a partir dele será criado o subdomínio padrão.
3. Escolhe a versão do Node.js (18, 20 ou 22, por padrão 20) e confirma a instalação.
4. O motor cria um starter Express minimalista - package.json e server.js com um único endpoint - e executa-o através do supervisor na porta 3000, e o nginx encaminha o tráfego do domínio para essa porta.
5. Após a conclusão da instalação, o domínio do passo 2 mostra o starter em funcionamento - a partir deste momento, substitui-o pelo teu próprio código através do git deploy.

Implementar o teu próprio código via Git

1. Nos detalhes da aplicação, encontra a secção Git / CI-CD e clica em "Ligar GitHub", confirma a instalação da aplicação "Saplo Deploy" e indica o repositório com o projeto Node.
2. Na diretoria raiz do repositório, coloca o ficheiro saplo.yaml. Ao contrário dos stacks com uma convenção específica (Next.js, Nuxt), o stack Node.js não tem um comando de início padrão - tens de indicar explicitamente start.command, caso contrário, a construção será bem-sucedida, mas o processo não será iniciado.
3. Faz commit e envia o ficheiro para o branch de produção (por padrão main).
4. Cada git push subsequente para este branch inicia a construção e o reinício do processo, cujo estado podes ver no separador Deployments.
5. A porta padrão da aplicação é 3000 - o nginx direciona o tráfego de 80/443 para ela, até que a alteres em start.port.

Exemplo de um ficheiro saplo.yaml mínimo para Node.js:

name: my-project
stack: node
runtime:
  node: "22"
build:
  install: npm ci
start:
  command: node index.js
  port: 3000
env:
  NODE_ENV: production

Node.js na Saplo vs. alternativas

Perguntas frequentes

Qualquer framework - Express, Fastify, NestJS - funcionará? Sim, o stack Node.js não impõe um framework. Apenas exige que o processo ouça na porta indicada em start.port (por predefinição, 3000).

O que acontece se eu me esquecer de start.command no saplo.yaml? A compilação será bem-sucedida, mas o processo não será iniciado - o erro aparecerá no separador "Implementações". Adiciona start.command e envia uma nova versão.

Os websockets funcionam através do nginx da Saplo? Sim, o proxy reverso passa o cabeçalho Upgrade, pelo que as ligações WebSocket de longa duração funcionam sem configuração adicional.

Posso ter uma base de dados ao lado da aplicação? Sim, podes configurar a base de dados (Postgres, MySQL, Redis) como uma aplicação separada do catálogo e anexar a variável de ligação em env do teu saplo.yaml.

Vou ter SSL e um domínio próprio? Sim, o certificado SSL é automático, e um domínio ou subdomínio *.saploapp.pl está incluído no preço de qualquer plano.

No Saplo, configuras o Node.js do zero para um domínio funcional em poucos minutos, e cada git push subsequente reinicia o processo com a nova versão sem a tua intervenção. Se o teu projeto utiliza um framework específico com a sua própria convenção (Next.js, Nuxt), verifica no mesmo catálogo o seu stack dedicado.