Come installare Node.js su Saplo (backend personalizzato dal repository)

Node.js non è un framework, ma un runtime JavaScript lato server. A differenza di Next.js o Nuxt, lo stack "Node.js" nel catalogo di Saplo non impone alcuna convenzione o struttura di progetto. Puoi scrivere il tuo server HTTP in Express, Fastify, Koa, NestJS o senza alcun framework, e Saplo si assicura solo che il processo sia sempre attivo e riparta dopo un errore. È l'opzione di backend più universale nel catalogo: adatta per API per app mobili, bot Discord o server websocket, a condizione che il progetto esponga una porta HTTP.

A chi si rivolge Node.js su Saplo?

Prima di iniziare l'installazione, verifica se è la scelta giusta per il tuo progetto:

• API per un'applicazione mobile o un frontend SPA - esponi REST o GraphQL e imposti il frontend (React, Vue) separatamente dalla stessa directory.
• Bot o integrazione in background - webhook, bot Discord e Slack, worker di coda.
• Backend su websockets - Nginx lato Saplo consente l'header Upgrade, quindi le connessioni a lunga durata funzionano senza configurazione aggiuntiva.
• Hai un progetto Node.js pronto e desideri distribuzioni con git push - colleghi il repository una volta e Saplo crea e riavvia il processo automaticamente.

Se il tuo progetto si basa su un framework specifico con una propria convenzione di build e avvio (Next.js, Nuxt), scegli lo stack dedicato nel catalogo - otterrai una configurazione pronta senza dover indicare manualmente il comando di avvio.

Requisiti

Per installare Node.js su Saplo, ti serviranno:

• Un Box nel piano L o superiore - il processo Node è mantenuto costantemente in memoria, quindi richiede più RAM di una pagina statica.
• Almeno 512 MB di RAM libera e 3 GB di spazio su disco per il processo dell'applicazione.
• Un Dominio o sottodominio *.saploapp.pl incluso in ogni piano.
• Un repository Git, se desideri utilizzare il deployment automatico (opzionale all'inizio, puoi anche caricare l'applicazione come archivio .zip tramite il Pannello).

Installazione passo dopo passo

1. Nel Pannello di Saplo, vai su Catalogo delle applicazioni e seleziona Node.js (categoria "Applicazioni").
2. Indica un Box con piano L o superiore e il nome dell'applicazione - da questo verrà creato il sottodominio predefinito.
3. Scegli la versione di Node.js (18, 20 o 22, predefinito 20) e conferma l'installazione.
4. Il motore crea uno starter minimo di Express - package.json e server.js con un singolo endpoint - e lo avvia tramite supervisor sulla porta 3000, mentre nginx effettua il proxy del traffico dal dominio a questa porta.
5. Al termine dell'installazione, il dominio del passo 2 mostrerà lo starter funzionante - da questo momento lo potrai sostituire con il tuo codice tramite git deploy.

Deploy del tuo codice con Git

1. Nei dettagli dell'applicazione, trova la sezione Git / CI-CD e clicca su "Connetti GitHub", conferma l'installazione dell'applicazione "Saplo Deploy" e indica il repository con il progetto Node.
2. Nella directory principale del repository, inserisci il file saplo.yaml. A differenza degli stack con una convenzione specifica (Next.js, Nuxt), lo stack Node.js non ha un comando di avvio predefinito: devi indicare esplicitamente start.command, altrimenti la build avrà successo ma il processo non si avvierà.
3. Effettua il commit e il push del file sul ramo di produzione (di default main).
4. Ogni successivo git push su questo ramo avvia la build e il riavvio del processo; lo stato è visibile nella scheda Deploymenti.
5. La porta predefinita dell'applicazione è la 3000: nginx instrada il traffico da 80/443 verso di essa, a meno che tu non la modifichi in start.port.

Esempio di file saplo.yaml minimo per 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 su Saplo vs. alternative

Domande frequenti

Qualsiasi framework, Express, Fastify, NestJS, funzionerà? Sì, lo stack Node.js non impone un framework. Richiede solo che il processo sia in ascolto sulla porta specificata in start.port (default 3000).

Cosa succede se dimentico start.command in saplo.yaml? La build avrà successo, ma il processo non si avvierà - vedrai l'errore nella scheda "Deployment". Aggiungi start.command ed esegui il push di una nuova versione.

I websocket funzionano tramite nginx Saplo? Sì, il reverse proxy passa l'intestazione Upgrade, quindi le connessioni WebSocket a lunga durata funzionano senza configurazione aggiuntiva.

Posso avere un database accanto all'applicazione? Sì, puoi installare un database (Postgres, MySQL, Redis) come applicazione separata dal Catalogo delle applicazioni e collegare la variabile di connessione in env del tuo saplo.yaml.

Otterrò SSL e il mio Dominio? Sì, il certificato SSL è automatico e il Dominio o sottodominio *.saploapp.pl è incluso nel prezzo di ogni piano.

Puoi installare Node.js su Saplo da zero a un Dominio funzionante in pochi minuti, e ogni successivo git push riavvia il processo con una nuova versione senza il tuo intervento. Se il tuo progetto utilizza un framework specifico con la propria convenzione (Next.js, Nuxt), controlla il suo stack dedicato nello stesso catalogo.