Zurück zum Blog

Node.js-App deployen: PM2 und Nginx auf dem Server

Node.js-App deployen auf dem Linux-Server: Node.js LTS, npm ci, PM2 mit Autostart und Reload, Nginx als Reverse Proxy, HTTPS, Updates und typische Fehler.

Nodesty-Team11 Min. LesezeitServer
Der Schriftzug Node.js Deploy mit PM2 und Nginx auf dunklem Nodesty-Hintergrund

Wer eine Node.js-App deployen möchte, kommt mit node server.js in einer SSH-Sitzung nicht weit: Die App endet, sobald die Sitzung geschlossen wird, bleibt nach einem Absturz aus und kommt nach einem Neustart nicht zurück. Üblich ist auf einem Linux-vServer daher PM2 als Prozessmanager, der die App am Laufen hält, und davor Nginx als Reverse Proxy für HTTPS und WebSocket-Verbindungen. Steht dieses Setup einmal, besteht jedes Update nur noch aus einer Handvoll Befehle.

In dieser Anleitung zeigen wir, wie Sie eine Node.js-Anwendung, etwa eine Express-API, auf einem frischen Ubuntu-Server deployen: Node.js LTS installieren, ein eigener Benutzer, npm ci, Umgebungsvariablen, PM2 mit Autostart und Cluster-Modus, Nginx als Reverse Proxy, Firewall, HTTPS, Updates und die häufigsten Fehler.

Voraussetzungen

  • Server: Ein Ubuntu-Server mit Root-Zugriff. In dieser Anleitung verwenden wir Ubuntu 24.04.
  • Anwendung: Ein Node.js-Projekt in einem Git-Repository mit package.json und package-lock.json.
  • Domain: Ein A-Eintrag, der auf die IP-Adresse Ihres Servers zeigt.

Ein Bot, der kein HTTP ausliefert, braucht kein Nginx; für diesen Fall lesen Sie unsere Anleitung Discord-Bot hosten.

Schritt 1: Node.js LTS, PM2 und Nginx

Nachdem Sie sich per SSH mit Ihrem Server verbunden haben:

sudo apt update
sudo apt install nginx git curl
curl -fsSL https://deb.nodesource.com/setup_lts.x -o nodesource_setup.sh
sudo -E bash nodesource_setup.sh
sudo apt install nodejs
sudo npm install -g pm2
node -v && npm -v && pm2 -v

Die eigenen Paketquellen von Ubuntu 24.04 enthalten Node.js 18, das nicht mehr unterstützt wird. Das NodeSource-Repository installiert die aktuelle LTS-Version systemweit als /usr/bin/node, zusammen mit npm; um bei einer Hauptversion zu bleiben, ersetzen Sie setup_lts.x zum Beispiel durch setup_24.x. Auf Servern ist uns dieser Weg lieber als nvm: nvm installiert Node.js im Home-Verzeichnis eines einzelnen Benutzers, was die Pfade für Dienste und den Autostart fehleranfälliger macht.

Unter AlmaLinux führen Sie curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash - und danach sudo dnf install nodejs nginx git aus. Nginx läuft dort als Benutzer nginx, und Site-Dateien gehören nach /etc/nginx/conf.d/. Die Grundlagen finden Sie in unserer Anleitung Nginx installieren.

Schritt 2: Benutzer, Code und npm ci

Führen Sie die Anwendung nicht als root aus. Legen Sie dafür einen Benutzer und einen Ordner unter /srv an:

sudo adduser --disabled-password --gecos "" deploy
sudo mkdir -p /srv/app
sudo chown deploy:deploy /srv/app
sudo -iu deploy
git clone git@github.com:user/app.git /srv/app
cd /srv/app
npm ci
npm run build   # nur, wenn Ihr Projekt einen Build-Schritt hat

npm ci löscht node_modules und installiert genau die Versionen, die in der package-lock.json festgehalten sind; so erhält der Server dieselben Pakete, mit denen Sie getestet haben. Passen Lock-Datei und package.json nicht zusammen, bricht der Befehl mit einem Fehler ab. Hat das Projekt keinen Build-Schritt, überspringt npm ci --omit=dev die Entwicklungsabhängigkeiten. Deploy Keys behandeln wir in unserer Anleitung Deployment mit Git, die Benutzerverwaltung in Linux-Benutzer anlegen. Führen Sie die Befehle der folgenden Schritte als Benutzer deploy aus, sofern sie nicht mit sudo beginnen.

Schritt 3: Umgebungsvariablen und Listen-Adresse

Halten Sie Geheimnisse aus dem Code und dem Repository heraus. Legen Sie die Datei /srv/app/.env an, tragen Sie sie in die .gitignore ein und schützen Sie sie mit chmod 600 .env:

SESSION_SECRET=hier-einen-langen-zufallswert-einfuegen
DATABASE_URL=postgres://app:ein-starkes-passwort@127.0.0.1:5432/app

Einen passenden Zufallswert erzeugt openssl rand -hex 32. Node.js ab Version 20.6 kann diese Datei mit dem Flag --env-file laden, ein zusätzliches Paket ist also nicht nötig; nutzt Ihr Projekt bereits dotenv, funktioniert auch das. Lesen Sie die Werte mit process.env aus und lassen Sie die App nur auf der lokalen Adresse lauschen:

const port = Number(process.env.PORT) || 3000;

app.set('trust proxy', 1); // Express: den X-Forwarded-*-Headern von Nginx vertrauen
app.listen(port, '127.0.0.1');

Ohne Host-Argument lauscht Node.js auf allen Netzwerkschnittstellen; die App würde dann auch unter http://SERVER-IP:3000 antworten, an Nginx vorbei und ohne HTTPS. Testen Sie sie nun:

node --env-file=.env server.js

Aus einer zweiten SSH-Sitzung sollte curl -I http://127.0.0.1:3000 eine Antwort liefern. Beenden Sie die App mit Strg+C.

Schritt 4: Die App mit PM2 starten

Beschreiben Sie die App in der Datei /srv/app/ecosystem.config.js; so stehen die Einstellungen in einer Datei statt in einem langen Befehl:

module.exports = {
    apps: [
        {
            name: 'app',
            script: 'server.js',
            cwd: '/srv/app',
            node_args: '--env-file=.env',
            env: {
                NODE_ENV: 'production',
                PORT: 3000,
            },
        },
    ],
};
pm2 start ecosystem.config.js
pm2 status

Enthält Ihre package.json den Eintrag "type": "module", nennen Sie die Datei stattdessen ecosystem.config.cjs. Die Befehle, die Sie am häufigsten brauchen:

BefehlWirkung
pm2 statusListet die Prozesse mit Status, Zahl der Neustarts (↺) und Speicher auf
pm2 logs appZeigt die Ausgabe der App live; die Dateien liegen in ~/.pm2/logs/
pm2 reload appStartet den neuen Code; im Cluster-Modus Prozess für Prozess
pm2 restart appStoppt und startet alle Prozesse der App gleichzeitig
pm2 stop app / pm2 delete appStoppt die App / entfernt sie aus der PM2-Liste
pm2 monitZeigt CPU, Speicher und Logs live im Terminal

Zwei Dinge sollten Sie wissen:

  • Umgebung: PM2 merkt sich die env-Werte vom ersten Start. Führen Sie nach einer Änderung pm2 reload ecosystem.config.js --update-env aus; pm2 reload app allein behält die alten Werte. Die Datei .env wird dagegen bei jedem Start neu gelesen, dort genügt ein normaler Reload.
  • Logs: Die Logdateien von PM2 wachsen unbegrenzt. pm2 install pm2-logrotate ergänzt eine automatische Rotation, damit die Logs nicht irgendwann die Festplatte füllen.

Schritt 5: Autostart beim Booten

PM2 selbst muss beim Booten des Servers starten und Ihre Apps zurückbringen. Speichern Sie die Prozessliste als deploy, wechseln Sie dann zurück in Ihr Admin-Konto und registrieren Sie PM2 für diesen Benutzer als systemd-Dienst:

pm2 save
exit
sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u deploy --hp /home/deploy

pm2 startup legt einen Dienst namens pm2-deploy an und aktiviert ihn; beim Booten stellt er die Liste wieder her, die pm2 save nach /home/deploy/.pm2/dump.pm2 geschrieben hat. Führen Sie pm2 save erneut aus, sobald Sie eine App hinzufügen oder entfernen. Um sicherzugehen, starten Sie den Server einmal mit sudo reboot neu und prüfen Sie als deploy die Ausgabe von pm2 status. Möchten Sie die App lieber allein mit systemd verwalten, lesen Sie unsere Anleitung systemd-Service erstellen.

Schritt 6: Cluster-Modus

Ein Node.js-Prozess führt Ihr JavaScript auf einem einzigen CPU-Kern aus. Im Cluster-Modus startet PM2 mehrere Kopien der App, die sich denselben Port teilen. Ergänzen Sie den App-Eintrag in der ecosystem.config.js um zwei Zeilen:

instances: 'max',
exec_mode: 'cluster',

max startet einen Prozess pro CPU-Kern; Sie können auch eine Zahl angeben. Ein Wechsel des Modus erfordert einen frischen Start: pm2 delete app, danach pm2 start ecosystem.config.js und pm2 save. Von da an ersetzt pm2 reload app die Prozesse nacheinander, ohne Ausfallzeit.

  • Kein Zustand im Speicher: Sitzungen, Caches oder Rate-Limit-Zähler, die in einer Variablen liegen, existieren einmal pro Prozess. Verlagern Sie sie in die Datenbank oder nach Redis. Socket.IO benötigt bei mehreren Instanzen zusätzlich Sticky Sessions.
  • Sauberes Beenden: Bei einem Reload sendet PM2 dem alten Prozess SIGINT und beendet ihn standardmäßig nach 1,6 Sekunden (kill_timeout). Fangen Sie das Signal ab, um offene Anfragen abzuschließen und Datenbankverbindungen zu schließen.
  • Speicher: Jede Instanz belegt ihren eigenen RAM. Leistet die App wenig CPU-Arbeit, reichen oft ein oder zwei Instanzen.

Schritt 7: Nginx als Reverse Proxy

Legen Sie die Datei /etc/nginx/sites-available/app an:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;
    client_max_body_size 20M;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}
sudo ln -s /etc/nginx/sites-available/app /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
  • Proxy-Header: Host, X-Real-IP, X-Forwarded-For und X-Forwarded-Proto teilen der App mit, welche Domain angefragt wurde, wer der Besucher ist und ob die Anfrage über HTTPS kam. Ohne sie sieht jede Anfrage wie einfaches HTTP von 127.0.0.1 aus.
  • WebSocket: proxy_http_version 1.1 zusammen mit den Headern Upgrade und Connection lässt WebSocket-Verbindungen (Socket.IO, Live-Updates) durch. Der map-Block sendet Connection: upgrade nur, wenn der Browser es anfordert.
  • Timeouts: Nginx schließt eine Proxy-Verbindung, auf der 60 Sekunden lang nichts ankommt (proxy_read_timeout). Senden Sie bei WebSockets regelmäßig Ping-Nachrichten oder erhöhen Sie den Wert.
  • client_max_body_size: Nginx erlaubt standardmäßig Uploads bis 1 MB; größere Anfragen erhalten einen 413-Fehler.
  • 127.0.0.1 statt localhost: localhost wird auch zur IPv6-Adresse ::1 aufgelöst, auf der die App nicht lauscht.

Unter AlmaLinux speichern Sie die Datei als /etc/nginx/conf.d/app.conf und erlauben Nginx mit sudo setsebool -P httpd_can_network_connect 1 Verbindungen zu lokalen Ports; andernfalls blockiert SELinux den Proxy und Sie erhalten einen 502-Fehler.

Schritt 8: Firewall und HTTPS

Öffnen Sie nur SSH und die Web-Ports. Port 3000 bleibt geschlossen:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

Läuft SSH auf einem anderen Port, geben Sie diesen frei, bevor Sie die Firewall aktivieren, sonst sperren Sie sich aus. Mehr dazu in unserer Anleitung UFW Firewall. Unter AlmaLinux verwenden Sie sudo firewall-cmd --permanent --add-service=http --add-service=https und danach sudo firewall-cmd --reload. Holen Sie anschließend das Zertifikat:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d www.example.com

Certbot holt das Zertifikat, ergänzt den HTTPS-Serverblock und richtet die automatische Verlängerung ein. Details finden Sie in unserem Artikel Was ist ein SSL-Zertifikat?.

Updates deployen

sudo -iu deploy
cd /srv/app
git pull
npm ci
npm run build   # nur, wenn Ihr Projekt einen Build-Schritt hat
pm2 reload app

Die laufenden Prozesse halten den alten Code bis zum Reload im Speicher. Prüfen Sie danach pm2 status und pm2 logs app --lines 50: Steigt die Zahl der Neustarts (↺) immer weiter, stürzt die neue Version beim Start ab. Da npm ci den Ordner node_modules neu aufbaut, während die alte Version noch läuft, bauen größere Projekte jedes Release in einem eigenen Ordner; diesen Ansatz und ein Deploy-Skript zeigt unsere Anleitung Deployment mit Git. Sichern Sie die Datenbank vor Migrationen, die Daten verändern; siehe unsere Anleitung Server-Backup.

Logs und typische Fehler

Die Ausgabe der App sehen Sie mit pm2 logs app, Nginx schreibt nach /var/log/nginx/error.log.

FehlerHäufige Ursache
502 Bad GatewayDie App läuft nicht oder stürzt immer wieder ab (errored in pm2 status), oder proxy_pass nutzt den falschen Port
EADDRINUSE: address already in useEin anderer Prozess belegt Port 3000, oft ein von Hand gestartetes node server.js oder ein zweites PM2 als root
Website öffnet sich unter http://SERVER-IP:3000Die App lauscht auf 0.0.0.0 oder :: statt auf 127.0.0.1 und die Firewall ist offen
EACCES: permission denied beim LauschenDie App will als normaler Benutzer einen Port unter 1024 nutzen; nehmen Sie 3000 und überlassen Sie 80 und 443 Nginx
EACCES bei npm ci oder beim SchreibenDateien gehören nach einem sudo npm oder sudo git pull root
Cannot find modulenpm ci wurde nach dem Update nicht ausgeführt, oder cwd zeigt auf den falschen Ordner
App ist nach einem Neustart verschwundenpm2 startup wurde nie eingerichtet, oder pm2 save wurde nach der letzten Änderung nicht ausgeführt
  • Port belegt: sudo ss -tlnp | grep :3000 zeigt, welcher Prozess den Port hält. Alles Weitere steht in unserer Anleitung Port bereits belegt.
  • 127.0.0.1 oder 0.0.0.0: Läuft Nginx auf demselben Server, ist 127.0.0.1 richtig. Nur wenn die App in einem Docker-Container läuft oder Nginx auf einem anderen Server steht, muss sie auf 0.0.0.0 lauschen; beschränken Sie den Port dann mit der Firewall.
  • Rechte: Korrigieren Sie den Besitzer mit sudo chown -R deploy:deploy /srv/app. Verwenden Sie im Alltag kein sudo pm2 ...: Das startet ein zweites PM2 als root mit eigener Prozessliste unter /root/.pm2, und beide streiten sich um denselben Port.

Eine Schritt-für-Schritt-Checkliste für 502-Fehler finden Sie in unserer Anleitung 502 Bad Gateway beheben.

Ein Hinweis zu Next.js, Nuxt und NestJS

Frameworks mit Build-Schritt funktionieren genauso: Führen Sie npm run build aus und lassen Sie script dann auf den gebauten Server zeigen. Bei NestJS ist das dist/main.js, bei Nuxt .output/server/index.mjs (es liest die Variablen HOST und PORT) und bei Next.js node_modules/next/dist/bin/next mit args: 'start -H 127.0.0.1 -p 3000'. Die Abkürzung pm2 start npm --name app -- start führt das start-Skript aus der package.json aus, eignet sich aber nicht für den Cluster-Modus, weil PM2 dann npm statt Ihrer App verwaltet. Nginx und HTTPS bleiben unverändert.

Nodesty Server für Node.js-Apps

Die AMD Ryzen 9 9950X vServer von Nodesty sorgen mit hoher Single-Core-Leistung für kurze Antwortzeiten bei Node.js, das Ihren Code pro Prozess auf einem einzigen Kern ausführt; die AMD EPYC 7763 vServer bieten viele Kerne und viel RAM, um den PM2-Cluster-Modus, die Datenbank und Hintergrundjobs auf demselben Server zu betreiben. Mit vollem Root-Zugriff, NVMe-Speicher, DDoS-Schutz durch nShield und kostenlosen täglichen Backups mit 7 Tagen Aufbewahrung bringen Sie Ihre Express-, NestJS- oder Next.js-Projekte sicher online.

Häufig gestellte Fragen

Warum starte ich auf dem Server nicht einfach node server.js oder npm start?

Ein von Hand gestarteter Prozess endet, sobald Sie die SSH-Sitzung schließen, bleibt nach einem Absturz aus und kommt nach einem Neustart des Servers nicht zurück. Ein Prozessmanager wie PM2 lässt die App im Hintergrund laufen, startet sie nach einem Absturz neu, sammelt ihre Logs und startet sie beim Booten des Servers wieder.

Soll ich für eine Node.js-App PM2 oder systemd verwenden?

Beide halten die App am Laufen und starten sie beim Booten. PM2 bringt Node.js-spezifische Komfortfunktionen mit, etwa den Cluster-Modus, Reloads ohne Ausfallzeit und eine eigene Log-Ansicht. systemd ist bereits Teil des Systems und funktioniert für jede Sprache gleich. PM2 nutzt selbst einen kleinen systemd-Dienst, um beim Booten zu starten.

Brauche ich Nginx vor einer Node.js-App?

Node.js kann HTTP-Anfragen auch allein beantworten, doch Nginx davor übernimmt die Ports 80 und 443, HTTPS-Zertifikate, mehrere Websites auf einem Server, Upload-Limits und langsame Clients. Ihre App läuft dann als normaler Benutzer auf einem lokalen Port wie 3000 und ist nie direkt aus dem Internet erreichbar.

Was ist der Unterschied zwischen pm2 restart und pm2 reload?

pm2 restart stoppt alle Prozesse der App und startet sie neu, was eine kurze Unterbrechung verursacht. pm2 reload ersetzt die Prozesse im Cluster-Modus nacheinander, sodass immer einer Anfragen beantwortet. Im Fork-Modus mit nur einem Prozess verhält sich reload wie restart.

Wie viele Instanzen sollte ich im Cluster-Modus starten?

Ein guter Ausgangswert ist eine Instanz pro CPU-Kern, genau das bewirkt die Einstellung max. Jede Instanz ist ein eigener Prozess mit eigenem Speicher; behalten Sie daher den RAM-Verbrauch im Blick und senken Sie die Zahl, sobald der Server swappt. Die App darf Sitzungen oder anderen gemeinsamen Zustand nicht im Prozessspeicher halten.

Warum zeigt meine Website den Fehler 502 Bad Gateway?

Nginx kann die Node.js-App nicht erreichen. Entweder läuft die App nicht, sie stürzt beim Start immer wieder ab oder sie lauscht auf einem anderen Port als dem in proxy_pass. Prüfen Sie zuerst pm2 status und pm2 logs und danach das Nginx-Fehlerlog unter /var/log/nginx/error.log.

Nodesty

Über den Autor

Nodesty-Team · Infrastruktur und Support

Das Nodesty-Team betreibt unsere Server, unser Netzwerk und unseren DDoS-Schutz im Alltag und beantwortet Support-Anfragen rund um die Uhr. Diese Ratgeber entstehen aus dieser Arbeit.

Verwandte Artikel

Starte deinen Server jetzt.

Erstellen, wachsen und skalieren Sie Ihre Projekte grenzenlos auf der Premium-Infrastruktur von Nodesty.

                                                                                                                                                                                                                            
                                                                                                                                                                                                                            
                                                                                                                                                                                                                            
                                                                                                                             ············································                                                   
                                                ··································································································..........···························                                     
                                       ················..........................................................................................................................··············                             
                                  ·············.................::::::::::::::::::::::::::::::::::::::::::::::....................:::::::::::::::::::::::::::::::::::::::................···········                        
                             ············................:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::............·········                     
                         ············.................:::::::::::::::::::::::::::::::::::::::::::::::::::------------::::::::::::::::::::::::::::::----------------:::::::::::::::::::::..........········                  
                    ············......................::::::::::::::::::::::::::::::::::::------------------------------------------------------------------------------------:::::::::::::.........········                
                ··········.............................................::::::::::::::::::-------------==========================================-----------------------------------:::::::::::........·······               
             ········..................:.....................................::::::::::--------=======+++++++++++++++++++++++++++++++++++++=========================------------------::::::::::.......·······              
           ······.........::::::::::::::::::::................................:::::::-----=====++++xxxxxx**************************xxxxxxxxx++++++++++++++===================------------::::::::.......·······             
          ·····.......:::::::::::::::::::::::::::.............................:::::----===+++xxx****%%%%&&&&&&#############&&&&&&&%%%%%*******xxxxxxxx++++++++++++++==============----------:::::::......······             
         ····......::::::::-------------:::::::::::..........................::::---===+++xx***%%%&&&####@@@@@@@@@@@@@@@@@@@@@@@@####&&&&&%%%%*******xxxxxxxxx+++++++++++++===========--------::::::......·····             
        ····.....:::::::--------------------:::::::::.......................::::---===++xxx**%%&&&###@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@###&&&&%%%%%********xxxxxxxxxxx++++++++++++========------::::::.....······            
        ····.....:::::--------------------------::::::::....................::::---===++xx***%%&&&####@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@###&&&&&%%%%%**********xxxxxxxxxxxxx+++++++++=======------:::::.....·····            
        ····....::::::-------=============---------:::::::::................:::::---===+++xx***%%%&&&#####@@@@@@@@@@@@@@@@@@@@@@@@@#####&&&&&%%%%%%*************xxxxxxxxxxxxxx+++++++++======-----:::::....·····            
         ····....:::::-------================---------:::::::::...............:::::----===++++xxx***%%%%&&&&&&#################&&&&&&%%%%%%%*******************xxxxxxxxxxxxxxxxx++++++++======----:::::....·····            
         ·····....:::::--------=================---------::::::::::..............:::::::-----====+++++xxxxxx**************************xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx++++++++=====-----::::....·····            
          ·····.....:::::--------=================----------:::::::::::.................:::::::::-------=============++++++++++++++++++++++++++++++++++++xxxxxxxxxxxxxxxxxxxxxxx++++++++======-----::::....·····            
            ·····.....:::::::----------===========-------------::::::::::::.........................::::::::::::::::::------------------=============+++++++++++++++++++++++++++++++++=======-----::::.....·····            
              ······......:::::::---------------------------------:::::::::::::........................................:::::::::::::::-----------============+++++++++++++++++++++========------:::::.....·····             
                 ······........:::::::::---------------------------:::::::::::::::::...........................................:::::::::::::------------=============================--------::::::.....······              
                    ·········.........:::::::::::::::-------------::::::::::::::::::::::::.......................................::::::::::::::::--------------------------------------::::::::......·······                
                          ··········............::::::::::::::::::::::::::::::::::::::::::::::::::................................::::::::::::::::::::::::::-------------:::::::::::::::.........········                   
                                  ············..................:::::::::::::::::::::::::::::::::::::::::::.........................:::::::::::::::::::::::::::::::::::::................···········                        
                                             ················.............................................................................................................·················                                 
                                                           ······················................................................................···························                                                
                                                                               ·········································································