Pomoc » Uruchomienie aplikacji Node.js na usłudze hostingowej

Uruchomienie aplikacji Node.js na usłudze hostingowej

Uwaga! Na wstępie chcielibyśmy podkreślić, że nie świadczymy wsparcia w zakresie administracji i debugowania dla aplikacji Node.js. Poniższa instrukcja przedstawia jedynie opis uruchomienia aplikacji za pomocą narzędzia dostępnego w panelu administracyjnym hostingu.

Dla usług hostingowych jest możliwe uruchomienie aplikacji opartej o Node.js z poziomu modułu „Aplikacje Node.js” w panelu Direct_Admin

Zalecane jest posiadanie pakietu z dostępem do SSH.

Aplikacje Node.js mogą znacznie obciążać usługę, dla tego należy upewnić się, że parametry pakietu są wystarczające względem danej aplikacji:
https://cyberfolks.pl/specyfikacja-techniczna-uslug.pdf

Aby uruchomić aplikację Node.js wykonaj następujące kroki:

1. Dodanie aplikacji
Nową aplikację można dodać z poziomu panelu hostingu w „Pozostałe ustawienia” -> „Aplikacje Node.js”

Następnie wybieramy opcję „Create Aplication”

2. Konfiguracja aplikacji
Po stworzeniu aplikacji przechodzimy do okna edycji, gdzie możemy zarządzać wersją Node.js, katalogiem głównym aplikacji czy plikami konfiguracyjnymi.

Node.js version
Wybieramy jedną z dostępnych wersji Node.js.
Uwaga! Jeżeli oczekiwanej wersji nie ma na liście należy wykonać instalację wybranej paczki binarnej albo użyć NVS (sekcja „Instalacja Node.js – inne sposoby” – opisane na końcu instrukcji).

Adds value for NODE_ENV variable
Służy do przełączania między wersjami development lub production

Application root
W tym miejscu podajemy ścieżkę do katalogu z naszą aplikacją – jest to lokalizacja, do której zostaną wgrane pliki aplikacji (lokalizacja z plikiem startowym package.json). Katalog domowy aplikacji nie musi znajdować się w katalogu domowym domeny, może być to dowolny katalog użytkownika.
Przykład ścieżki dla katalogu domyślnego public_html:
/home/login_serwera/domains/nazwa_domeny/public_html

Ścieżkami do katalogu domowego można zarządzać z poziomu panelu administracyjnego hostingu w „Serwer www i domeny” -> „Przypisz katalog domeny”.
Z uwagi na to, że zostanie utworzony specjalny wpis do pliku .htaccess przekierowujący z katalogu domeny głównej do katalogu naszej aplikacji, zalecamy tworzyć aplikacje na osobnych domenach z odseparowanymi katalogami.

Application URL
Tutaj należy podać nazwę domeny, pod jaką będzie odpowiadać aplikacja

Application startup file
Tutaj podajemy nazwę pliku startowego – w tym przypadku app.js

Zatwierdzenie Ustawień – Create
Po ustaleniu wstępnej konfiguracji generujemy aplikację przyciskiem „Create”. Zostanie
utworzone wirtualne środowisko. W katalogu głównym domeny tworzony jest też plik
.htaccess odpowiedzialny za ustawienia przekierowania na katalog aplikacji i działanie
Passenger’a. Z tego powodu zalecamy tworzenie aplikacji w wydzielonych domenach,
katalogach, aby nie kolidowały z innymi aplikacjami/stronami, zwłaszcza jeżeli chodzi o
ustawienia w pliku .htaccess

3. Sprawdzenie działania aplikacji
Na tym etapie należy sprawdzić, czy serwer Node.js poprawnie odpowiada. Pod zadeklarowaną nazwą domeny powinna zostać wyświetlona informacja o działającej wersji Node.js.
It works!
NodeJS 24.13.0
Dopiero teraz można rozpocząć zgrywanie plików właściwej aplikacji.

4. Logowanie do wirtualnego środowiska
Aby korzystać z serwera Node.js, wymagane jest zalogowanie do wirtualnego środowiska
poprzez SSH poleceniem dostępnym u góry aplikacji w sekcji „Enter to the virtual
environment.To enter to virtual environment, run the command.”
Teraz możemy odpytać dostępną wersję Node.js oraz wersję npm następującymi
poleceniami:
npm -v
node -v

Uwaga #1 ! npm jest wbudowany dla Node.js, dla tego będzie dostępny dopiero po zalogowaniu
do wirtualnego środowiska z uruchomionym serwerem Node.js.
Uwaga #2 ! Aplikacje Node.js mogą działać bez dostępu do SSH, aczkolwiek jest wskazane
posiadanie dostępów SSH do pracy na wirtualnym środowisku i tam wykonywanie dalszych
skryptów.

4. Konfiguracja pliku startowego package.json
Do poprawnego uruchomienia operacji npm install wymagany jest plik konfiguracyjny. Można
go utworzyć ręcznie lub za pomocą polecenia:
npm init -y

Dodatkowe informacje

Run NPM Install
Jeżeli aplikacja jest uruchomiona oraz posiada wygenerowany plik package.json to opcja
Run NPM Install powinna się podświetlić jako dostępna. Pojawi się też komunikat:
NPM Install completed successfully.
Do wykonania tego polecenia jest potrzebny poprawnie zadeklarowany plik package.json.
Zalecamy posługiwanie się konsolą ssh i wirtualnym środowiskiem, podając polecenie:
npm install

Run scripts
Służy do uruchomiania poleceń zadeklarowanych w package.json. Te same polecenia
możemy wykonywać z poziomu konsoli SSH w zależności od deklaracji w pliku package.json.

Zmienne środowiskowe
Zalecamy korzystanie z pliku .env jako miejsca do deklarowania zmiennych środowiskowych

Wskazanie na port
Domyślnie aplikacja uruchamiana jest na porcie http. Jeżeli chcemy skierować aplikację na
konkretny port można to zrobić z poziomu pliku .htaccess dla domeny w następujący sposób:
DirectoryIndex disabled RewriteEngine On RewriteRule ^$ http://127.0.0.1:NR_PORTU/ [P,L] RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^(.*)$ http://127.0.0.1:NR_PORTU/$1 [P,L]
gdzie NR_PORTU – numer portu – najlepiej podać z zakresu: 35100:35599

FAQ – Najczęściej zadawane pytania/błędy

Serwer Node.js można uruchomić na każdej usłudze, która ma dostęp do SSH. Aplikacje Node.js są dostępne na wszystkich serwerach współdzielonych. Dla serwerów VPS i Dedykowanych można dokonać ręcznej instalacji, patrz Instalacja Node.js – inne sposoby (poniżej FAQ)

Manager pakietów npm jest domyślnie wbudowany dla Node.js. Upewnij się, czy jesteś poprawnie zalogowany do środowiska wirtualnego i czy serwer jest aktywny.

Uruchomić będzie można wszystkie frameworki, dla których node.js ma spełnioną określoną wersję. Przykłady takich technologii to: React.js, Next.js. Nest.js, Nuxt.js, Vue.js, Gatsby. Nie świadczymy wsparcia technicznego w zakresie administracji i instalacji dla tych technologii

Najczęściej tego typu błąd dotyczy problemów z przekierowaniem aplikacji z katalogu domeny do katalogu aplikacji dla subdomen. Zalecamy tworzenie aplikacji node.js w osobnych domenach, gdzie katalogi i pliki .htaccess są odseparowane

Jeżeli pojawia się problem z zatrzymaniem/usunięciem, należy najpierw zatrzymać dla niej procesy. Procesy można zatrzymać z poziomu ssh/htop poleceniem kill. Uwaga: Przed usunięciem aplikacji nie należy usuwać plików Node.js oraz pliku .htaccess. Jeżeli dojdzie do takiej operacji, należy użyć opcji Destroy z poziomu Edycji aplikacji

Jeżeli pojawia się komunikat o błędnej ścieżce, należy zatrzymać aplikację i dokonać edycji. Kiedy błąd dalej się pojawia, a aplikacji nie można zatrzymać, konieczne będzie zatrzymanie procesu z poziomu ssh/htop poleceniem kill

Instalacja Node.js – inne sposoby

Serwer Node.js można zainstalować samodzielnie. Wymagany będzie dostęp do SSH.

Metoda 1 – Archiwum binarne
1. Logujemy się na danego użytkownika i następnie:
cd $HOME
2. Pobieramy plik Node.js z oficjalnej strony. Wersję dobieramy do danego projektu.
wget https://nodejs.org/dist/v24.13.0/node-v24.13.0-linux-x64.tar.xz
3. Należy pobrany plik, rozpakować go oraz przekopiować jego zawartość do konta:
tar -xvf node-v24.13.0-linux-x64.tar.xz
cp -a node-v24.13.0-linux-x64/{bin,lib,include,share} $HOME/
4. npm powinien być już dostępny, sprawdzamy wersje
npm -v
node -v
5. W przypadku braku dostępności należy ponownie ustawić linki symboliczne:
unlink npm
unlink npx
ln -s $HOME/node-v24.13.0-linux-x64/lib/node_modules/npm/bin/npm-cli.js npm
ln -s $HOME/node-v24.13.0-linux-x64/lib/node_modules/npm/bin/npx-cli.js npx

Metoda 2 – NVS
NVS jest wieloplatformowym narzędziem do przełączania się między różnymi wersjami Node.js. Następujące polecenia podajemy kolejno z poziomu SSH z katalogu domowego użytkownika:
export NVS_HOME="$HOME/.nvs"
git clone https://github.com/jasongin/nvs "$NVS_HOME"
"$NVS_HOME/nvs.sh" install

Uwaga! Na wstępie chcielibyśmy podkreślić, że nie świadczymy wsparcia w zakresie administracji i debugowania dla aplikacji Node.js. Poniższa instrukcja przedstawia jedynie opis uruchomienia aplikacji za pomocą narzędzia dostępnego w panelu administracyjnym hostingu.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że:

Masz dostęp do serwera przez SSH.
W panelu cyber_Admin masz utworzoną domenę, która będzie obsługiwać aplikację.
Znasz podstawy obsługi terminala Linux.
Znasz numer portu, na którym będzie działać Twoja aplikacja — musi to być port z zakresu 54xxx (np. 54321).

Tworzenie struktury projektu

Poniższe kroki przeprowadzą Cię przez założenie folderu projektu, inicjalizację środowiska Node.js oraz instalację przykładowej biblioteki HTTP.

1. Utwórz dedykowany folder projektu
Pliki aplikacji Node.js powinny znajdować się poza katalogiem publicznym (public_html), aby kod źródłowy nie był dostępny z zewnątrz. Utwórz osobny folder w katalogu domowym:

mkdir -p ~/node_app

WAŻNE! Możesz wybrać dowolną nazwę folderu zamiast node_app. Ważne, żeby folder znajdował się poza public_html lub innym katalogiem docRoot domeny.

2. Zainicjalizuj projekt Node.js
Przejdź do nowo utworzonego folderu i uruchom inicjalizację projektu:

cd node_app/

/opt/alt/alt-nodejs20/root/usr/bin/npm init -y

Polecenie npm init -y tworzy plik package.json z domyślnymi wartościami — stanowi on punkt startowy każdego projektu Node.js.

3. Zainstaluj bibliotekę HTTP (przykład: Express)
W poniższym przykładzie używamy frameworka Express jako ilustracji — nie jest on jednak wymagany. Express to biblioteka, która ułatwia i przyspiesza pisanie aplikacji w Node.js, ale z punktu widzenia serwera i mechanizmu Reverse Proxy (.htaccess) wybór biblioteki jest zupełnie dowolny. Serwerowi jest obojętne, co generuje ruch na danym porcie — ważne jest tylko to, aby proces nasłuchiwał na tym porcie i odpowiadał w standardzie HTTP. Możesz użyć innej biblioteki lub napisać serwer HTTP bez żadnych zewnętrznych zależności.

Aby zainstalować Express jako przykładową bibliotekę:

/opt/alt/alt-nodejs20/root/usr/bin/npm install express

Po zakończeniu instalacji w folderze ~/node_app pojawi się katalog node_modules z pobranymi zależnościami.

WAŻNE! Jeśli korzystasz z innego frameworka lub budujesz własny serwer HTTP, pomiń ten krok i dostosuj plik app.js do używanej biblioteki.

Tworzenie pliku głównego aplikacji

1. Utwórz plik app.js
Poniższy przykład wykorzystuje Express. Jeśli używasz innej biblioteki, dostosuj kod do jej składni — mechanizm Reverse Proxy w .htaccess zadziała tak samo, niezależnie od wybranego frameworka.

Otwórz edytor tekstowy w terminalu i utwórz główny plik aplikacji:

nano app.js

Wklej następującą zawartość:

const express = require('express');
const app = express();
const port = 54321; // aplikacja powinna nasłuchiwać na porcie z zakresu 54xxx

app.get('/', (req, res) => {
  res.send('Aplikacja Node.js działa bezpiecznie z prywatnego folderu');
});

app.listen(port, '127.0.0.1', () => {
  console.log(`Serwer nasłuchuje na lokalnym porcie ${port}`);
});

Zapisz plik skrótem Ctrl+O, a następnie wyjdź z edytora skrótem Ctrl+X.

WAŻNE! Aplikacja powinna nasłuchiwać wyłącznie na adresie 127.0.0.1 (localhost) — nigdy bezpośrednio na publicznym interfejsie sieciowym. Dostęp z zewnątrz będzie realizowany przez proxy Apache skonfigurowane w .htaccess.

Uruchamianie aplikacji

1. Uruchom aplikację w tle
Aby aplikacja działała nawet po zamknięciu sesji SSH, użyj polecenia nohup, które izoluje proces od terminala. Logi aplikacji zostaną zapisane do pliku app.log:

nohup /opt/alt/alt-nodejs20/root/usr/bin/node app.js > app.log 2>&1 &

2. Sprawdź, czy serwer działa
Zweryfikuj, czy aplikacja poprawnie odpowiada na żądania HTTP:

curl -si http://127.0.0.1:54321

Jeśli wszystko działa prawidłowo, powinieneś zobaczyć odpowiedź podobną do poniższej:

HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: text/html; charset=utf-8
Content-Length: 37
...
Aplikacja Node.js działa bezpiecznie

Jeśli serwer odpowiada kodem 200 OK, możesz przejść do kolejnego kroku.

Konfiguracja domeny

1. Skonfiguruj plik .htaccess
Po potwierdzeniu, że aplikacja działa, skonfiguruj domenę tak, aby przekazywała ruch do Twojej aplikacji Node.js. W tym celu edytuj plik .htaccess w katalogu public_html domeny:

nano /home/pomoc/sites/nodejs.pomoc-cyberadmin.pl/public_html/.htaccess

WAŻNE! Ścieżkę do katalogu public_html dostosuj do swojej domeny — znajdziesz ją w panelu cyber_Admin w ustawieniach domeny.

Wklej następującą konfigurację, podając numer portu swojej aplikacji:

RewriteEngine On
RewriteRule ^(.*)$ http://127.0.0.1:54321/$1 [P,L]

Zapisz plik skrótem Ctrl+O i zamknij edytor skrótem Ctrl+X.

WAŻNE! W katalogu public_html powinien znajdować się wyłącznie plik .htaccess. Katalog domeny zawiera tylko ten jeden plik, co jest prawidłową i bezpieczną konfiguracją.

Bezpieczeństwo – dlaczego projekt musi leżeć poza `public_html`?

Utrzymanie właściwej struktury folderów jest kluczowe dla bezpieczeństwa aplikacji:

Lokalizacja plików	Skutek
`~/node_app/` (poza `public_html`)	Pliki projektu są niedostępne z zewnątrz.
`public_html/` (katalog publiczny)	Każdy może odczytać kod źródłowy, `package.json`, zmienne środowiskowe.

W katalogu public_html (lub innym skonfigurowanym docRoot) powinien znajdować się wyłącznie plik .htaccess, który przekierowuje ruch do aplikacji Node.js działającej lokalnie.

Rozwiązywanie problemów

Problem	Możliwe rozwiązanie
`curl` zwraca błąd połączenia	Sprawdź, czy proces Node.js działa: `ps aux \| grep node`. Jeśli nie — uruchom aplikację ponownie poleceniem z Kroku 5.
Strona wyświetla błąd 503 lub 502	Upewnij się, że numer portu w `.htaccess` zgadza się z portem w `app.js`.
Aplikacja nie startuje	Sprawdź logi: `cat ~/node_app/app.log`. Mogą wskazywać na błąd składniowy w kodzie lub brakującą zależność.
Port jest zajęty	Zmień numer portu w `app.js` i `.htaccess` na inny z zakresu `54xxx` i uruchom aplikację ponownie.

Podsumowanie

Twoja aplikacja Node.js działa teraz w tle na lokalnym porcie, a domena skonfigurowana w panelu cyber_Admin serwuje jej zawartość za pośrednictwem pliku .htaccess. Pliki projektu są bezpiecznie przechowywane poza katalogiem publicznym, co chroni kod źródłowy przed nieautoryzowanym dostępem.

Magdalena Pietraszek

Uruchomienie aplikacji Node.js na usłudze hostingowej

Uwaga! Na wstępie chcielibyśmy podkreślić, że nie świadczymy wsparcia w zakresie administracji i debugowania dla aplikacji Node.js. Poniższa instrukcja przedstawia jedynie opis uruchomienia aplikacji za pomocą narzędzia dostępnego w panelu administracyjnym hostingu.

1 Dla jakiego serwera, pakietu jest dostępny Node.js?

2Dlaczego nie działa polecenie npm?

3Jakie frameworki można uruchomić?

4Dlaczego po uruchomieniu aplikacji pojawia się błąd 503?

5Dlaczego nie mogę usunąć aplikacji?

6Błąd ścieżki – z czego wynika ten komunikat?

Uwaga! Na wstępie chcielibyśmy podkreślić, że nie świadczymy wsparcia w zakresie administracji i debugowania dla aplikacji Node.js. Poniższa instrukcja przedstawia jedynie opis uruchomienia aplikacji za pomocą narzędzia dostępnego w panelu administracyjnym hostingu.

Wymagania wstępne

Tworzenie struktury projektu

Tworzenie pliku głównego aplikacji

Uruchamianie aplikacji

Konfiguracja domeny

Bezpieczeństwo – dlaczego projekt musi leżeć poza public_html?

Rozwiązywanie problemów

Podsumowanie

Bezpieczeństwo – dlaczego projekt musi leżeć poza `public_html`?