Jak uruchomić aplikację Node.js w Plesk?

Krótka odpowiedź: w Plesku aplikację Node.js uruchamia rozszerzenie Node.js Toolkit. Wskazujesz katalog aplikacji (Application Root), katalog publiczny (Document Root) i plik startowy (np. app.js), wybierasz wersję Node.js, instalujesz zależności przyciskiem NPM install i uruchamiasz aplikację. Procesem zarządza Phusion Passenger. Nie potrzebujesz własnego VPS-a ani ręcznej konfiguracji nginx, a nowa aplikacja rusza w chwili, gdy serwer WWW wczyta nową konfigurację. Poniżej pełna instrukcja, przykładowa aplikacja i najczęstsze problemy.

Jak Plesk uruchamia aplikację Node.js

Node.js Toolkit nie uruchamia aplikacji w tle przez pm2 ani systemd. Zamiast tego wpisuje do konfiguracji serwera WWW dyrektywy Phusion Passenger. Przy pierwszym żądaniu Passenger startuje proces Node.js, przekazuje mu port w zmiennej PORT i kieruje do niego ruch z domeny. Nieużywany proces może zostać wyłączony i wystartuje ponownie przy kolejnym wejściu.

Z tego wynikają trzy praktyczne zasady:

• aplikacja nasłuchuje na porcie z process.env.PORT, a nie na wpisanym na sztywno 3000;
• pliki statyczne z katalogu publicznego serwuje serwer WWW, a pozostałe adresy trafiają do aplikacji;
• zmiana konfiguracji zaczyna działać dopiero po przeładowaniu serwera WWW, które Plesk wykonuje z opóźnieniem (u nas do 30 minut).

Przygotowanie domeny lub subdomeny

Aplikację najwygodniej uruchomić na osobnej subdomenie, np. app.twojafirma.pl. Strona główna na WordPressie działa wtedy dalej bez zmian. Utwórz subdomenę w Witryny i domeny → Dodaj subdomenę i jako katalog główny dokumentów wpisz katalog publiczny aplikacji, np. app/public. Katalog aplikacji (app) leży wtedy poza katalogiem publicznym, więc plików .env czy node_modules nie da się pobrać z przeglądarki.

Minimalna aplikacja i package.json

Najprostsza działająca aplikacja nie potrzebuje żadnych bibliotek. Zapisz ją jako app/app.js:

const http = require('http');

const port = process.env.PORT || 3000;   // port podaje Passenger

http.createServer((req, res) => {
  res.setHeader('Content-Type', 'application/json; charset=utf-8');
  res.end(JSON.stringify({ ok: true, node: process.version, path: req.url }));
}).listen(port);

Z biblioteką Express aplikacja wygląda podobnie. Zależności opisuje app/package.json:

{
  "name": "moja-aplikacja",
  "version": "1.0.0",
  "private": true,
  "main": "app.js",
  "scripts": {
    "build": "echo \"brak kroku budowania\""
  },
  "dependencies": {
    "express": "^4.21.2"
  }
}

const express = require('express');
const app = express();

app.get('/', (req, res) => res.json({ ok: true }));
app.listen(process.env.PORT || 3000);

Konfiguracja w Node.js Toolkit

W panelu domeny otwórz Node.js i kliknij Włącz Node.js. Najważniejsze pola:

Tabelę można przewijać w poziomie.

Po zapisaniu Plesk wygeneruje konfigurację Passengera. Jeśli w katalogu publicznym leży domyślny plik index.html utworzony przy zakładaniu subdomeny, usuń go. Serwer WWW poda go zamiast odpowiedzi aplikacji i będzie wyglądało, że Node.js nie działa.

Zależności: NPM install i skrypty

Przycisk NPM install instaluje zależności z package.json w katalogu aplikacji. Run script uruchamia skrypt z sekcji scripts, np. build dla aplikacji z krokiem kompilacji (TypeScript, Next.js w trybie produkcyjnym). Z dostępem SSH możesz zrobić to samo z konsoli, pamiętając o wskazaniu właściwej wersji Node.js:

cd ~/app
export PATH=/opt/plesk/node/24/bin:$PATH
node -v
npm ci --omit=dev

Biblioteki kompilowane przy instalacji (np. bcrypt, sharp w starszych wersjach) potrzebują narzędzi budowania. Na hostingu współdzielonym bywają one niedostępne, więc przed wyborem biblioteki sprawdź, czy ma gotowe binaria albo wersję w czystym JavaScripcie (np. bcryptjs).

Zmienne środowiskowe

Hasła, adresy baz i klucze API wpisuj w Custom environment variables albo w pliku .env w katalogu aplikacji (poza katalogiem publicznym). Nie trzymaj ich w repozytorium. Przykład odczytu:

const dbUrl = process.env.DATABASE_URL;
if (!dbUrl) throw new Error('Brak DATABASE_URL');

Jak zbudować DATABASE_URL dla bazy z panelu, pokazujemy w poradniku o bazie PostgreSQL w Plesku.

Restart i logi

Po wgraniu nowej wersji kodu aplikację trzeba zrestartować:

• w panelu: Restart App;
• przez SSH albo menedżer plików: utwórz lub dotknij plik tmp/restart.txt w katalogu aplikacji — Passenger zrestartuje proces przy najbliższym żądaniu.

mkdir -p ~/app/tmp && touch ~/app/tmp/restart.txt

Błędy startu (np. brak modułu, zły plik startowy) Passenger wypisuje na stronie błędu i w logach domeny (Logi w panelu). To, co aplikacja pisze przez console.log, również trafia do logu serwera WWW.

Wdrażanie z Gita

W pakietach z rozszerzeniem Git możesz podłączyć repozytorium do katalogu aplikacji i wdrażać zmiany ręcznie albo automatycznie po git push. W akcjach po wdrożeniu dopisz instalację zależności i restart, np.:

npm ci --omit=dev && mkdir -p tmp && touch tmp/restart.txt

Najczęstsze problemy

• Widzisz domyślną stronę Pleska zamiast aplikacji — w katalogu publicznym jest index.html; usuń go.
• Zmiany w konfiguracji nie działają — serwer WWW jeszcze nie wczytał nowej konfiguracji; poczekaj na przeładowanie albo poproś obsługę hostingu.
• „Cannot find module” — zależności nie zostały zainstalowane w katalogu aplikacji albo Application Root wskazuje inny katalog niż ten z package.json.
• Aplikacja nasłuchuje, ale nic nie odpowiada — port jest wpisany na sztywno zamiast process.env.PORT.
• „The application process exited prematurely” — błąd przy starcie aplikacji albo w środowisku uruchomieniowym; szczegóły są w logach. Na hostingu z izolacją kont (CageFS) przyczyną bywa też konfiguracja Passengera po stronie serwera — wtedy potrzebna jest obsługa hostingu.
• Aplikacja działa lokalnie, a na serwerze nie — różna wersja Node.js; ustaw w panelu tę samą, której używasz lokalnie, i zapisz ją w package.json ("engines").

FAQ

Czy do Node.js potrzebuję VPS-a?

Nie zawsze. API, panel administracyjny czy mały serwis w Express działają w Plesku na hostingu z Node.js Toolkit. VPS ma sens przy długotrwałych procesach w tle, WebSocketach z dużym ruchem albo niestandardowych usługach systemowych.

Czy mogę uruchomić Next.js?

Tak, jako aplikację Node.js: zbuduj projekt (npm run build) i wskaż plik startowy serwera produkcyjnego. Wersję w pełni statyczną (output: 'export' w konfiguracji Next.js) wystarczy wgrać do katalogu publicznego.

Jak zrestartować aplikację bez panelu?

Utwórz lub zaktualizuj plik tmp/restart.txt w katalogu aplikacji.

Gdzie trzymać hasła do bazy danych?

W zmiennych środowiskowych aplikacji albo w pliku .env poza katalogiem publicznym — nigdy w repozytorium.

Weryfikacja techniczna: 17.09.2026, Plesk Obsidian 18.0.80, Node.js Toolkit 2.5, Node.js 24.21 i 26.8, Passenger 6.1. Powiązane poradniki: PostgreSQL w Plesku, Docker i Docker Compose w Plesku, aplikacja Ruby w Plesku. Pakiety: hosting NVMe (Business) i hosting VIP.