So richtest du Node.js auf Saplo ein (eigenes Backend aus dem Repository)

Node.js ist kein Framework, sondern eine serverseitige JavaScript-Laufzeitumgebung - im Gegensatz zu Next.js oder Nuxt. Der "Node.js"-Stack im Saplo-Katalog erzwingt keine Konvention oder Projektstruktur. Du schreibst deinen eigenen HTTP-Server in Express, Fastify, Koa, NestJS oder ohne Framework. Saplo sorgt lediglich dafür, dass der Prozess ständig läuft und nach einem Ausfall wiederhergestellt wird. Dies ist die vielseitigste Backend-Option im Katalog: Es passt zu einer API für eine mobile Anwendung, einem Discord-Bot oder einem WebSocket-Server, solange das Projekt selbst einen HTTP-Port verfügbar macht.

Für wen ist Node.js bei Saplo geeignet?

Bevor du mit der Installation beginnst, prüfe, ob dies die richtige Wahl für dein Projekt ist:

• API für eine mobile Anwendung oder ein SPA-Frontend - du stellst REST oder GraphQL bereit und das Frontend (React, Vue) wird separat aus demselben Verzeichnis bereitgestellt,
• Bot oder Integration, die im Hintergrund läuft - Webhooks, Discord- und Slack-Bots, Queue-Worker,
• Backend für WebSockets - nginx auf Saplo-Seite leitet den Header Upgrade weiter, sodass langlebige Verbindungen ohne zusätzliche Konfiguration funktionieren,
• Du hast ein fertiges Node.js Projekt und möchtest automatische Deployments mit git push - du verbindest das Repository einmal, und Saplo baut und startet den Prozess automatisch neu.

Wenn dein Projekt in einem bestimmten Framework mit eigener Build- und Startkonvention (Next.js, Nuxt) ist, wähle im App-Katalog den dedizierten Stack aus - du erhältst eine fertige Konfiguration, ohne den Startbefehl manuell angeben zu müssen.

Anforderungen

Um Node.js auf Saplo zu installieren, benötigst du:

• Eine Box im Tarif L oder höher - der Node-Prozess wird ständig im Speicher gehalten und benötigt daher mehr RAM als eine statische Seite.
• Mindestens 512 MB freien RAM und 3 GB Speicherplatz auf der Festplatte für den Anwendungsprozess selbst.
• Eine Domain oder Subdomain *.saploapp.pl, die in jedem Tarif enthalten ist.
• Ein Git-Repository, wenn du die automatische Bereitstellung nutzen möchtest (optional für den Start, du kannst die Anwendung auch als .zip Archiv über das Panel hochladen).

Schritt für Schritt Installation

1. Gehe im Saplo-Panel zum App-Katalog und wähle Node.js (Kategorie "Anwendungen").
2. Wähle eine Box im L-Plan oder höher und den Namen der Anwendung - daraus wird die Standard-Subdomain generiert.
3. Wähle die Node.js-Version (18, 20 oder 22, standardmäßig 20) und bestätige die Installation.
4. Die Engine erstellt einen minimalen Express-Starter - package.json und server.js mit einem einzelnen Endpunkt - und startet ihn über Supervisor auf Port 3000, während Nginx den Traffic von der Domain auf diesen Port proxyed.
5. Nach Abschluss der Installation zeigt die Domain aus Schritt 2 den laufenden Starter an - ab diesem Zeitpunkt ersetzt du ihn durch deinen eigenen Code mittels Git Deploy.

Eigenen Code per Git bereitstellen

1. In den Anwendungsdetails findest du den Abschnitt Git / CI-CD. Klicke auf „GitHub verbinden“, bestätige die Installation der Anwendung „Saplo Deploy“ und wähle das Repository mit deinem Node-Projekt aus.
2. Lege die Datei saplo.yaml im Stammverzeichnis deines Repositorys ab. Im Gegensatz zu Stacks mit einer spezifischen Konvention (Next.js, Nuxt) hat der Node.js-Stack keinen Standard-Startbefehl. Du musst start.command explizit angeben, da der Build sonst erfolgreich ist, aber der Prozess nicht startet.
3. Committe die Datei und pushe sie auf den Produktions-Branch (standardmäßig main).
4. Jeder weitere git push auf diesen Branch löst einen Build und einen Prozessneustart aus. Den Status siehst du unter dem Tab Deploymenty.
5. Der Standardport der Anwendung ist 3000. Nginx leitet den Traffic von 80/443 darauf um, bis du ihn in start.port änderst.

Beispiel für eine minimale saplo.yaml-Datei für 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 auf Saplo vs. Alternativen

Häufig gestellte Fragen

Funktionieren alle Frameworks - Express, Fastify, NestJS? Ja, der Node.js Stack schreibt kein Framework vor. Er erfordert lediglich, dass der Prozess auf dem in start.port angegebenen Port (standardmäßig 3000) lauscht.

Was passiert, wenn ich start.command in saplo.yaml vergesse? Der Build wird erfolgreich sein, aber der Prozess startet nicht - den Fehler siehst du auf dem Tab "Deployments". Füge start.command hinzu und pushe eine neue Version.

Funktionieren WebSockets über den Nginx von Saplo? Ja, der Reverse Proxy leitet den Upgrade Header weiter, sodass lange bestehende WebSocket-Verbindungen ohne zusätzliche Konfiguration funktionieren.

Kann ich eine Datenbank neben meiner Anwendung haben? Ja, du erstellst die Datenbank (Postgres, MySQL, Redis) als separate Anwendung aus dem Katalog und verbindest die Verbindungs-Variable in env deines saplo.yaml.

Bekomme ich SSL und eine eigene Domain? Ja, das SSL-Zertifikat ist automatisch, und eine Domain oder Subdomain *.saploapp.pl ist im Preis jedes Plans enthalten.

Node.js auf Saplo stellst du in wenigen Minuten von Grund auf bis zur funktionierenden Domain bereit, und jeder weitere git push startet den Prozess mit einer neuen Version ohne dein Zutun neu. Wenn dein Projekt ein bestimmtes Framework mit eigener Konvention (Next.js, Nuxt) verwendet, überprüfe im selben Katalog dessen dedizierten Stack.