Tworzenie i uruchamianie projektu Koa.js z ServBay
ServBay to lokalne środowisko programistyczne obsługujące macOS i Windows, które integruje popularne pakiety narzędziowe, w tym środowisko wykonawcze Node.js oraz wiele baz danych. W tym przewodniku dowiesz się, jak w pełni wykorzystać możliwości ServBay, aby szybko stworzyć, uruchomić i zarządzać projektem Koa.js.
Czym jest Koa.js?
Koa.js to nowoczesny framework webowy dla Node.js, stworzony przez zespół Express.js. Słynie z przejrzystości, elastyczności i bogatego zestawu funkcji, co czyni go doskonałym wyborem do tworzenia aplikacji internetowych i API. Koa.js wykorzystuje nowoczesne możliwości JavaScript, a zwłaszcza składnię async/await
, dzięki czemu zarządzanie asynchronicznością i middleware jest uproszczone, a kod – bardziej przejrzysty i łatwiejszy w utrzymaniu.
Główne cechy Koa.js
- Oparty na async/await: Cała architektura bazuje na
async/await
, co upraszcza kontrolę nad asynchronicznymi procesami. - Lekki rdzeń: Biblioteka Koa ma niewielką objętość, zawiera tylko funkcje podstawowe, a dodatkowe możliwości dodaje się przez middleware.
- Potężny system middleware: Mechanizm przetwarzania żądań oparty jest na kaskadowym (cascading) middleware, co zapewnia przejrzysty i elastyczny flow obsługi żądań.
- Skoncentrowany na webie: Zaprojektowany specjalnie do aplikacji webowych i rozwoju API, bez zbędnych, pobocznych funkcji.
Dzięki tym cechom Koa.js pozwala programistom budować wydajne i łatwe w utrzymaniu aplikacje webowe.
Konfiguracja środowiska Koa.js z ServBay
ServBay udostępnia Node.js oraz najczęściej wykorzystywane bazy danych w gotowym do pracy środowisku. Dzięki funkcji Witryny (Website) w ServBay, możesz bezproblemowo ustawiać własne domeny i certyfikaty SSL do lokalnego projektu Koa.js.
Wymagania wstępne
Zanim zaczniesz, upewnij się, że wykonałeś następujące kroki:
- Zainstaluj ServBay: Pobierz najnowszą wersję z oficjalnej strony ServBay i zainstaluj ją.
- Zainstaluj pakiet Node.js: Otwórz aplikację ServBay, przejdź do sekcji Pakiety (Packages) i upewnij się, że masz wybraną odpowiednią wersję Node.js. Jeśli nie – zaznacz i naciśnij "Instaluj".
- Zapoznaj się z obsługą ServBay: Naucz się uruchamiania/zatrzymywania usług oraz zarządzania witrynami w ServBay.
Tworzenie projektu Koa.js
Korzystać będziemy z zalecanego katalogu głównego ServBay: /Applications/ServBay/www
.
Inicjalizacja katalogu projektu
Otwórz aplikację Terminal, przejdź do katalogu głównego ServBay i utwórz nowy folder projektu (np.
servbay-koa-app
). Następnie przejdź do tego folderu i zainicjuj nowy projekt Node.js:bashcd /Applications/ServBay/www mkdir servbay-koa-app cd servbay-koa-app npm init -y
1
2
3
4Polecenie
npm init -y
szybko utworzy domyślny plikpackage.json
.Instalacja Koa.js
W głównym katalogu
servbay-koa-app
, zainstaluj Koa.js oraz – jeśli korzystasz z TypeScript – jego definicje typów:bashnpm install koa # Jeśli korzystasz z TypeScript, zainstaluj definicje typów # npm install @types/koa --save-dev
1
2
3Tworzenie pliku wejściowego aplikacji
Utwórz plik
app.js
w katalogu projektu i wstaw poniższy przykładowy kod Koa.js:javascriptconst Koa = require('koa'); const app = new Koa(); // Middleware: loguje informacje o żądaniu app.use(async (ctx, next) => { const start = Date.now(); await next(); const ms = Date.now() - start; console.log(`${ctx.method} ${ctx.url} - ${ms}ms`); }); // Middleware: obsługuje żądania do ścieżki głównej app.use(async ctx => { ctx.body = 'Hello from ServBay Koa.js App!'; }); // Ustal port – najpierw użyj zmiennej środowiskowej PORT const port = process.env.PORT || 3000; // Uruchom serwer HTTP app.listen(port, () => { console.log(`Koa.js server running on http://localhost:${port}`); console.log(`Project path: ${__dirname}`); });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24Ten kod tworzy bazową aplikację Koa z dwoma middleware: jeden loguje czas i ścieżkę żądania, drugi odpowiada na żądania do
/
, zwracając "Hello from ServBay Koa.js App!". Aplikacja nasłuchuje na porcie określonym przez zmiennąPORT
lub domyślnie na3000
.
Tryb deweloperski
W trakcie developmentu aplikację Koa.js uruchamiamy jako lokalny proces Node.js i odwiedzamy ją poprzez funkcję Witryny (Website) ServBay.
Uruchamianie serwera Koa.js
Otwórz terminal, przejdź do katalogu
servbay-koa-app
i uruchom plikapp.js
za pomocą polecenianode
. By uniknąć konfliktu portów/desygnowania portu w ServBay, zaleca się użyć np. portu8585
:bashcd /Applications/ServBay/www/servbay-koa-app PORT=8585 node app.js
1
2W terminalu pojawi się komunikat podobny do
Koa.js server running on http://localhost:8585
, co potwierdza poprawne uruchomienie na tym porcie. Pozostaw terminal otwarty, by serwer działał dalej.Konfiguracja reverse proxy w ServBay
Aby uzyskać dostęp do aplikacji Koa.js działającej na
localhost:8585
pod własną domeną, skonfiguruj Witrynę (Website) jako reverse proxy w ServBay:- Uruchom ServBay.
- Przejdź do sekcji Witryny (Website).
- Kliknij "+" w lewym dolnym rogu, by dodać nową witrynę.
- Skonfiguruj następujące opcje:
- Nazwa:
ServBay Koa.js Dev Site
- Domena:
servbay-koa-dev.servbay.demo
(rekomendowany sufiks.servbay.demo
; ServBay automatycznie wygeneruje certyfikat SSL) - Typ: wybierz
Reverse Proxy
- Adres IP:
127.0.0.1
(do lokalnego procesu Node.js) - Port:
8585
(port nasłuchu aplikacji Koa.js) - Katalog główny: dla reverse proxy nie jest wymagany; możesz pozostawić puste lub podać ścieżkę projektu
/Applications/ServBay/www/servbay-koa-app
.
- Nazwa:
- Zapisz zmiany.
- Jeśli ServBay poprosi o zastosowanie zmian – kliknij "Zastosuj".
Po konfiguracji ServBay automatycznie doda wpis w pliku hosts i skieruje domenę
servbay-koa-dev.servbay.demo
na127.0.0.1
. Wbudowany serwer Caddy lub Nginx przekieruje żądania na port8585
. Dodatkowo, korzystając z.servbay.demo
, User CA ServBay wygeneruje i zaufa certyfikatowi SSL, umożliwiając bezpieczny dostęp HTTPS.Szczegółowe instrukcje znajdziesz w dokumentacji ServBay: Dodawanie witryn Node.js (zalecamy wersję anglojęzyczną dokumentacji).
Dostęp do witryny deweloperskiej Koa.js
Otwórz przeglądarkę i przejdź do
https://servbay-koa-dev.servbay.demo
.Jeśli wszystko zostało skonfigurowane poprawnie, zobaczysz komunikat "Hello from ServBay Koa.js App!". Oznacza to, że witryna jest poprawnie dostępna przez funkcję Website w ServBay. Po każdej edycji pliku
app.js
oraz restarcie procesu Node.js – odśwież stronę, by zobaczyć zmiany.
Symulacja wdrożenia produkcyjnego
W symulowanym środowisku produkcyjnym warto używać innych portów, zmiennych środowiskowych czy odmiennego sposobu uruchamiania. Konfiguracja reverse proxy w ServBay jest analogiczna.
Uruchamianie serwera produkcyjnego Koa.js (symulacja)
W nowym oknie terminala przerwij poprzedni serwer developerski (jeśli nadal działa) i uruchom aplikację w trybie produkcyjnym, np. na porcie
8586
z ustawioną zmiennąNODE_ENV
:bashcd /Applications/ServBay/www/servbay-koa-app PORT=8586 NODE_ENV=production node app.js
1
2Tak uruchomiony serwer nasłuchuje na porcie
8586
i symuluje środowisko produkcyjne.Konfiguracja reverse proxy (symulacja produkcji)
Dodaj nową witrynę w ServBay:
- Wejdź w sekcję Witryny (Website).
- Kliknij "+" dla nowej witryny.
- Skonfiguruj:
- Nazwa:
ServBay Koa.js Prod Site
- Domena:
servbay-koa-prod.servbay.demo
(lub własna domena i certyfikat Let's Encrypt przez ServBay) - Typ:
Reverse Proxy
- IP:
127.0.0.1
- Port:
8586
- Katalog główny: opcjonalnie – puste lub ścieżka projektu.
- Nazwa:
- Zapisz i zastosuj zmiany.
Domena
.servbay.demo
skorzysta z certyfikatu User CA, a przy własnej domenie możesz użyć Let's Encrypt poprzez ACME w ServBay. Więcej informacji: Korzystanie z SSL.Dostęp do wdrożenia produkcyjnego
Wejdź na
https://servbay-koa-prod.servbay.demo
w przeglądarce.Otrzymasz identyczną stronę jak w środowisku developerskim, z tą różnicą, że żądania przechodzą przez reverse proxy do procesu Node.js uruchomionego na porcie
8586
.
Połączenia z bazą danych
ServBay udostępnia najważniejsze bazy danych: MongoDB, Redis, MariaDB (MySQL kompatybilny) oraz PostgreSQL. Lokalna konfiguracja pozwala na bezpośredni dostęp do tych baz z projektu Koa.js przez localhost
.
Oto przykłady połączeń z bazami danych w Node.js. Upewnij się, że odpowiednie pakiety bazodanowe są zainstalowane i uruchomione w ServBay.
Połącz z MongoDB
Najpierw zainstaluj sterownik MongoDB dla Node.js (np.
mongoose
lubmongodb
):bashcd /Applications/ServBay/www/servbay-koa-app npm install mongoose # lub npm install mongodb
1
2Dodaj kod połączenia w pliku
app.js
lub odpowiednim module:javascript// Połączenie z MongoDB przez mongoose const mongoose = require('mongoose'); // Domyślnie ServBay nie wymaga autoryzacji, nazwa bazy dowolna mongoose.connect('mongodb://localhost:27017/servbay-koa-app', { useNewUrlParser: true, useUnifiedTopology: true }) .then(() => console.log('Connected to MongoDB')) .catch(err => console.error('MongoDB connection error:', err)); // W praktyce kod połączenia umieszczamy zwykle w logice startowej aplikacji // oraz uruchamiamy nasłuch dopiero po udanym połączeniu z bazą.
1
2
3
4
5
6
7
8
9
10
11
12
13MongoDB w ServBay nasłuchuje na porcie
27017
i domyślnie pozwala łączyć się bez autoryzacji.Połącz z Redis
Zainstaluj bibliotekę Redis dla Node.js:
bashcd /Applications/ServBay/www/servbay-koa-app npm install redis
1
2Połącz z Redis:
javascript// Połączenie z Redis przez klienta redis const redis = require('redis'); // Kontener Redis domyślnie pod localhost:6379 const client = redis.createClient({ url: 'redis://localhost:6379' // Domyślny port Redis w ServBay }); client.on('connect', () => { console.log('Connected to Redis'); }); client.on('error', (err) => { console.error('Redis connection error:', err); }); // Połącz z serwerem Redis client.connect(); // W praktyce zaleca się odczekać na nawiązanie połączenia (async/await z client.connect()) // przed wykonywaniem operacji na Redis.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21Redis w ServBay nasłuchuje na porcie
6379
i zwykle nie wymaga hasła.Połącz z MariaDB (MySQL)
MariaDB to fork MySQL, API obu jest praktycznie identyczne. ServBay dostarcza MariaDB – możesz traktować ją jak MySQL.
Zainstaluj sterownik dla Node.js:
bashcd /Applications/ServBay/www/servbay-koa-app npm install mariadb # lub npm install mysql2 (zalecane)
1
2Przykład z
mariadb
:javascript// Połączenie MariaDB klientem mariadb const mariadb = require('mariadb'); // Domyślne hasło użytkownika root w MariaDB ServBay to 'password' const pool = mariadb.createPool({ host: 'localhost', user: 'root', password: 'password', database: 'servbay_koa_app', // Upewnij się, że baza istnieje connectionLimit: 5 }); pool.getConnection() .then(conn => { console.log("Connected to MariaDB"); conn.release(); // Zwolnij połączenie do puli }) .catch(err => { console.error("MariaDB connection error:", err); }); // Połączenia z puli pozyskiwane są asynchronicznie
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22Przykład z
mysql2
(polecane):javascript// Połączenie MariaDB/MySQL klientem mysql2 (wersja z promisami) const mysql = require('mysql2/promise'); // Domyślne hasło root ds. MariaDB w ServBay to 'password' const pool = mysql.createPool({ host: 'localhost', user: 'root', password: 'password', database: 'servbay_koa_app', // Upewnij się, że baza istnieje waitForConnections: true, connectionLimit: 10, queueLimit: 0 }); pool.getConnection() .then(conn => { console.log("Connected to MariaDB/MySQL using mysql2"); conn.release(); // Zwolnij połączenie }) .catch(err => { console.error("MariaDB/MySQL connection error:", err); }); // Domyślne hasło użytkownika root znajdziesz i możesz zmienić w GUI ServBay dla bazy danych // Warto w praktyce unikać zapisywania hasła w kodzie – zalecane jest użycie zmiennych środowiskowych.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25MariaDB w ServBay nasłuchuje na porcie
3306
. Domyślne hasło użytkownika root znajdziesz w panelu zarządzania ServBay. By połączyć się do własnej bazy, najpierw ją utwórz w ServBay lub za pomocą klienta typu TablePlus, DBeaver itp.Połącz z PostgreSQL
Zainstaluj bibliotekę
pg
dla Node.js:bashcd /Applications/ServBay/www/servbay-koa-app npm install pg
1
2Połącz z PostgreSQL:
javascript// Połączenie z PostgreSQL przez klienta pg const { Pool } = require('pg'); // Domyślny użytkownik 'user', hasło 'password' dla PostgreSQL w ServBay const pool = new Pool({ user: 'user', // użytkownik ServBay host: 'localhost', database: 'servbay_koa_app', // Upewnij się, że baza istnieje password: 'password', port: 5432, // Domyślny port PostgreSQL w ServBay }); pool.connect((err, client, done) => { if (err) { console.error('PostgreSQL connection error:', err); return; } console.log('Connected to PostgreSQL'); client.release(); }); // Domyślne hasło użytkownika user znajdziesz i możesz zmienić w GUI ServBay dla bazy danych // Zalecane jest niehardkodowanie hasła w kodzie produkcyjnym.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23Postgres domyślnie nasłuchuje na porcie
5432
. Domyślny użytkownik i hasło są dostępne w panelu ServBay. Bazę danych możesz utworzyć ręcznie.
Zarządzanie bazami w ServBay
Poza połączeniami przez kod, możesz zarządzać bazami danych ServBay przez GUI. Bazy domyślnie nasłuchują na 127.0.0.1
/localhost
, używaj podanych w GUI portów i haseł.
- Sprawdzanie/zmiana hasła: W aplikacji ServBay wybierz odpowiedni pakiet bazy, kliknij ikonę ustawień i sprawdź lub zmień domyślne hasło (
root
dla MariaDB,user
dla PostgreSQL). - Tworzenie baz/użytkowników: Użyj TablePlus, DBeaver, pgAdmin, MongoDB Compass itp. Połącz się z bazą i utwórz potrzebne zasoby przez SQL lub GUI.
Wskazówki
- Konflikty portów: Przed uruchomieniem Koa.js wybierz port nieużywany przez inne aplikacje/system.
- Status ServBay: Upewnij się, że ServBay, Node.js oraz niezbędne bazy są uruchomione.
- Plik hosts: ServBay zarządza tym automatycznie; przy problemach z domeną sprawdź wpisy w
/etc/hosts
. - Firewall: Upewnij się, że firewall (macOS lub aplikacja trzecia) nie blokuje ServBay lub Node.js.
- Logi: W przypadku problemów przejrzyj logi ServBay (zakładka w aplikacji) oraz logi Node.js w terminalu.
Najczęściej zadawane pytania (FAQ)
Dlaczego warto korzystać z reverse proxy ServBay do obsługi projektu Koa.js?
Odpowiedź: Reverse proxy przez witrynę ServBay zapewnia:
- Symulację produkcji: Użycie domeny (np.
.servbay.demo
lub własnej) jest bliższe prawdziwej wdrożonej stronie niżlocalhost:PORT
. - SSL: Automatyczny certyfikat SSL (User CA ServBay lub Let's Encrypt) pozwala na testowanie HTTPS już podczas developmentu.
- Centralne zarządzanie: Łatwa administracja wszystkich lokalnych witryn w ServBay.
- Ukrycie portów: Dostęp przez standardowe porty 80/443, same żądania trafiają do Node.js na wyższych portach.
- Symulację produkcji: Użycie domeny (np.
Czy mogę korzystać bez reverse proxy, tylko przez
localhost:PORT
?Odpowiedź: Tak, możesz bezpośrednio odwiedzać
http://localhost:PORT
do celów developerskich. Jednak nie skorzystasz wtedy z personalizowanej domeny, SSL, zarządzania logami i innych wygód ServBay. Reverse proxy skuteczniej przypomina środowisko produkcyjne.Jakie są domyślne hasła do baz danych w ServBay i jak je zmienić?
Odpowiedź: Domyślne hasła dostępne są w sekcji Bazy danych aplikacji ServBay. Kliknij ikonę ustawień przy odpowiedniej bazie (np. MariaDB, PostgreSQL) i zobacz lub zmień bieżące hasło użytkownika. Zaleca się zmianę hasła ze względów bezpieczeństwa.
Podsumowanie
Po lekturze tego przewodnika potrafisz już uruchomić lokalne środowisko produkcyjne Koa.js na macOS z ServBay. Stworzyliśmy prostą aplikację Koa.js, skonfigurowaliśmy reverse proxy przez witrynę ServBay, uzyskaliśmy dostęp pod lokalną domeną i przez HTTPS – zarówno w trybie developerskim, jak i symulacji produkcji. Pokazaliśmy też, jak połączyć aplikację z najczęściej używanymi bazami danych w ServBay.
ServBay to rozbudowane i łatwe w obsłudze narzędzie dla programistów Node.js. Pozwala skupić się na kodzie, eliminując uciążliwą konfigurację środowiska. Wykorzystując jego funkcje znacznie usprawnisz swój workflow programistyczny.