Tworzenie i uruchamianie projektu Koa.js z ServBay

ServBay to lokalne środowisko programistyczne dla macOS, zaprojektowane z myślą o deweloperach webowych. Integruje wiele popularnych narzędzi, takich jak środowisko uruchomieniowe Node.js czy różnorodne bazy danych. W tym przewodniku dowiesz się, jak szybko i wygodnie utworzyć, uruchomić oraz zarządzać projektem Koa.js z wykorzystaniem możliwości oferowanych przez ServBay.

Czym jest Koa.js?

Koa.js to nowoczesny framework webowy oparty na Node.js, opracowany przez twórców Express.js. Znany jest z prostoty, przejrzystego API i bogactwa funkcji – to idealny wybór przy budowie serwisów webowych oraz API. Koa.js w pełni wykorzystuje możliwości współczesnego JavaScriptu, w szczególności składni async/await, dzięki czemu kod asynchroniczny oraz middleware stają się znacznie prostsze w tworzeniu i utrzymaniu.

Kluczowe cechy Koa.js

• Opiera się na async/await: Konstrukcja frameworka została zaprojektowana wokół asynchronicznego sterowania przepływem.
• Lekki rdzeń: Minimalistyczna biblioteka bazowa – rdzeń zawiera jedynie najpotrzebniejsze funkcje; pełnię możliwości rozszerza się poprzez modularne middleware.
• Potężny system middleware: Mechanizm kaskadowy obiegu middleware sprawia, że obsługa żądań jest jasna i elastyczna.
• Dedykowany webdevelopmentowi: Skoncentrowany tylko na budowie aplikacji internetowych i API, bez zbędnych, pobocznych funkcji.

Korzystając z Koa.js, możesz szybko tworzyć wydajne i łatwe w utrzymaniu usługi webowe.

Konfiguracja środowiska Koa.js przy użyciu ServBay

ServBay oferuje deweloperom Node.js gotowe do pracy środowisko, integrujące zarówno runtime Node.js, jak i popularne bazy danych. Dzięki funkcji Website w ServBay możesz bezproblemowo przypisywać własne domeny i certyfikaty SSL do lokalnych projektów Koa.js.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że:

1. Zainstalowano ServBay: Pobierz i zainstaluj najnowszą wersję z oficjalnej strony ServBay.
2. Zainstalowano pakiet Node.js: Uruchom aplikację ServBay, przejdź do sekcji Packages i sprawdź, czy właściwa wersja Node.js jest dostępna. Jeśli nie – wybierz i zainstaluj.
3. Znajomość podstaw obsługi ServBay: Wiesz, jak startować/stopować usługi oraz zarządzać witrynami (Websites) w aplikacji.

Zakładanie projektu Koa.js

Jako katalog domyślny użyjemy sugerowanego przez ServBay: /Applications/ServBay/www.

1. Inicjalizacja katalogu projektu

   Otwórz terminal i przejdź do folderu głównego ServBay, następnie utwórz nowy folder projektu (np. servbay-koa-app). Przejdź do niego i zainicjalizuj projekt Node.js:

   cd /Applications/ServBay/www
   mkdir servbay-koa-app
   cd servbay-koa-app
   npm init -y

   Komenda npm init -y błyskawicznie wygeneruje domyślny plik package.json.

2. Instalacja Koa.js

   W głównym katalogu projektu servbay-koa-app użyj npm do instalacji Koa.js i ewentualnie plików typów (gdy pracujesz z TypeScript):

   npm install koa
   # Jeśli używasz TypeScript, doinstaluj pliki typów:
   # npm install @types/koa --save-dev

3. Tworzenie pliku startowego aplikacji

   W katalogu projektu servbay-koa-app utwórz plik app.js z prostą aplikacją Koa.js:

   const Koa = require('koa');
   const app = new Koa();
   
   // Middleware: logowanie informacji 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ługa żądania do ścieżki głównej
   app.use(async ctx => {
     ctx.body = 'Hello from ServBay Koa.js App!';
   });
   
   // Ustalanie portu, najpierw sprawdza zmienną środowiskową PORT
   const port = process.env.PORT || 3000;
   
   // Uruchomienie serwera HTTP
   app.listen(port, () => {
     console.log(`Koa.js server running on http://localhost:${port}`);
     console.log(`Project path: ${__dirname}`);
   });

   Ten kod buduje prostą aplikację Koa z dwoma middleware: jeden rejestruje czas i ścieżkę zapytania, a drugi odpowiada na żądania do /, zwracając komunikat "Hello from ServBay Koa.js App!". Serwer domyślnie nasłuchuje na porcie 3000, lub na wskazanym poprzez zmienną PORT.

Tryb deweloperski

Podczas developmentu najczęściej uruchamiasz lokalny proces Node.js, a dostęp do aplikacji uzyskujesz poprzez funkcję Website w ServBay.

1. Uruchomienie deweloperskiego serwera Koa.js

   W terminalu przejdź do folderu servbay-koa-app, uruchom app.js komendą node. Aby uniknąć konfliktu portów i ułatwić konfigurację ServBay, możesz wybrać port np. 8585:

   cd /Applications/ServBay/www/servbay-koa-app
   PORT=8585 node app.js

   Terminal wypisze np. Koa.js server running on http://localhost:8585, co potwierdza uruchomienie serwera na wskazanym porcie. Pozostaw to okno otwarte, by serwer działał cały czas.

2. Konfiguracja reverse proxy Website w ServBay

   Aby wykorzystać własną domenę do obsługi aplikacji działającej na localhost:8585, skonfiguruj opcję Website w ServBay jako reverse proxy:

   • Otwórz aplikację ServBay,
   • Przejdź do zakładki Website,
   • Kliknij + w lewym dolnym rogu, dodając nową witrynę,
   • Uzupełnij konfigurację:
     • Nazwa (Name): ServBay Koa.js Dev Site
     • Domena (Domain): servbay-koa-dev.servbay.demo (zalecana końcówka .servbay.demo – ServBay automatycznie generuje dla niej certyfikat SSL)
     • Typ (Type): wybierz Reverse Proxy
     • Adres IP (IP Address): 127.0.0.1 (wskazuje lokalny proces Node.js)
     • Port: 8585 (port, na którym działa aplikacja Koa.js)
     • Katalog główny (Document Root): Możesz pominąć lub podać ścieżkę /Applications/ServBay/www/servbay-koa-app.
   • Zapisz ustawienia.
   • ServBay może poprosić o zatwierdzenie zmian – kliknij "Apply/Zaaplikuj".

   Po zapisaniu ServBay automatycznie aktualizuje plik hosts, kierując servbay-koa-dev.servbay.demo na 127.0.0.1, a poprzez wbudowany serwer Caddy lub Nginx przekazuje ruch do Twojej aplikacji na porcie 8585. Dodatkowo, używając domeny .servbay.demo, ServBay User CA wystawi i zaufa odpowiedniemu certyfikatowi SSL, umożliwiając bezpieczny dostęp HTTPS.

   Szczegółowy przewodnik znajdziesz w dokumentacji ServBay: dodawanie Node.js development website (zalecamy wersję angielską).

3. Dostęp do witryny Koa.js

   Otwórz przeglądarkę i wpisz https://servbay-koa-dev.servbay.demo.

   Jeśli wszystko zostało poprawnie skonfigurowane, zobaczysz komunikat "Hello from ServBay Koa.js App!". Po każdej modyfikacji pliku app.js i restarcie procesu Node.js, wystarczy odświeżyć stronę, aby potwierdzić zmiany.

Wdrożenie produkcyjne (symulacja)

Podczas symulacji środowiska produkcyjnego możesz wybrać inny port, inne zmienne środowiskowe lub zmodyfikowany sposób startu. Reverse proxy w ServBay obsłuży ustawienia analogicznie.

1. Uruchomienie "produkcji" Koa.js (symulacja)

   W nowym oknie terminala zatrzymaj wcześniejszy serwer i uruchom go ponownie, na przykład na porcie 8586 z ustawioną zmienną NODE_ENV na production:

   cd /Applications/ServBay/www/servbay-koa-app
   PORT=8586 NODE_ENV=production node app.js

   Aplikacja będzie nasłuchiwać na porcie 8586, symulując środowisko produkcyjne.

2. Konfiguracja reverse proxy Website dla produkcji

   Analogicznie stwórz nową witrynę dla środowiska produkcyjnego:

   • Otwórz aplikację ServBay i przejdź do zakładki Website,
   • Kliknij +, aby dodać nową witrynę,
   • Uzupełnij dane:
     • Nazwa: ServBay Koa.js Prod Site
     • Domena: servbay-koa-prod.servbay.demo (lub własna domena – wówczas możesz łatwo dodać certyfikat SSL Let’s Encrypt przez ServBay)
     • Typ: wybierz Reverse Proxy
     • Adres IP: 127.0.0.1
     • Port: 8586
     • Katalog główny: dowolny lub pozostaw puste.
   • Zapisz i zastosuj zmiany.

   Używając .servbay.demo, nadal korzystasz z wewnętrznych certyfikatów ServBay User CA. Przy użyciu własnej domeny możesz aktywować darmowy certyfikat SSL/TLS (Let's Encrypt) przez ACME. Szczegóły znajdziesz w dokumentacji ServBay: zabezpieczanie witryny SSL.

3. Dostęp do "produkcyjnej" witryny Koa.js

   Przejdź do https://servbay-koa-prod.servbay.demo w przeglądarce.

   Zobaczysz taki sam output jak w środowisku developerskim, lecz teraz Twój reverse proxy obsługuje osobny proces Node.js na porcie 8586.

Połączenie z bazą danych

ServBay oferuje integrację z najpopularniejszymi bazami danych: MongoDB, Redis, MariaDB (zgodną z MySQL) i PostgreSQL. Wszystkie domyślnie działają lokalnie i możesz się z nimi łączyć przez localhost.

Oto przykłady kodu Node.js łączącego się z tymi bazami. Przed użyciem upewnij się, że zainstalowałeś wybrany serwer bazy przez panel Packages oraz że serwis ten jest uruchomiony.

1. Połączenie z MongoDB

   Najpierw zainstaluj sterownik Node.js, np. mongoose lub mongodb:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mongoose # lub npm install mongodb

   Następnie podłącz się w pliku app.js lub innym module:

   // Łączenie z MongoDB za pomocą Mongoose
   const mongoose = require('mongoose');
   
   // Domyślnie w ServBay: brak uwierzytelnienia, możesz dowolnie nazwać bazę
   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));
   
   // Uwaga: W praktyce kod połączenia umieszcza się w logice startowej aplikacji
   // i ustawia nasłuchiwanie portu dopiero po ustanowieniu połączenia z bazą.

   Domyślna instalacja MongoDB przez ServBay nasłuchuje na porcie 27017 i pozwala na połączenie bez hasła. Nazwę bazy możesz podać dowolnie – zostanie utworzona automatycznie, jeśli jej nie ma.

2. Połączenie z Redis

   Zainstaluj klienta Node.js dla Redis:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install redis

   Następnie podłącz się do serwera:

   // Łączenie z Redis
   const redis = require('redis');
   
   // Domyślne połączenie do localhost:6379
   const client = redis.createClient({
     url: 'redis://localhost:6379' // Domyślny port Redis w ServBay: 6379
   });
   
   client.on('connect', () => {
     console.log('Connected to Redis');
   });
   
   client.on('error', (err) => {
     console.error('Redis connection error:', err);
   });
   
   // Rozpoczęcie połączenia z serwerem Redis
   client.connect();
   
   // Uwaga: w praktyce warto poczekać na ukończenie połączenia (np. używając async/await)

   W ServBay Redis domyślnie nasłuchuje na porcie 6379, bez konieczności podawania hasła.

3. Połączenie z MariaDB (lub MySQL)

   MariaDB to forka MySQL z szeroką kompatybilnością API – ServBay udostępnia właśnie MariaDB.

   Zainstaluj sterownik Node.js:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mariadb # lub alternatywnie mysql2 (zalecane)

   Połączenie przez mariadb:

   // Połączenie do MariaDB
   const mariadb = require('mariadb');
   
   // Domyślne hasło root w ServBay: '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(); // Zwolnienie połączenia do puli
     })
     .catch(err => {
       console.error("MariaDB connection error:", err);
     });
   
   // Uwaga: pobieranie połączenia z puli odbywa się asynchronicznie

   Połączenie przez mysql2 (zalecane):

   // Połączenie z MariaDB/MySQL przez mysql2 (Promise API)
   const mysql = require('mysql2/promise');
   
   // Domyślne hasło root w ServBay: '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();
     })
     .catch(err => {
       console.error("MariaDB/MySQL connection error:", err);
     });
   
   // Uwaga: hasło root domyślnie znajdziesz i zmienisz w panelu ServBay GUI w ustawieniach bazy.
   // Zalecamy nie trzymać haseł w kodzie, lecz korzystać ze zmiennych środowiskowych.

   MariaDB w ServBay nasłuchuje na porcie 3306. Domyślne hasło root znajdziesz w panelu ServBay (możesz je tam również zmienić). Przed połączeniem utwórz bazę servbay_koa_app manualnie (np. przez TablePlus lub DBeaver).

4. Połączenie z PostgreSQL

   Zainstaluj klienta Node.js:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install pg

   Następnie połącz się z serwerem:

   // Połączenie z PostgreSQL przez pg
   const { Pool } = require('pg');
   
   // W ServBay domyślny użytkownik: 'user', hasło: 'password'
   const pool = new Pool({
     user: 'user',
     host: 'localhost',
     database: 'servbay_koa_app', // Upewnij się, że baza istnieje
     password: 'password',
     port: 5432, // Domyślny port PostgreSQL
   });
   
   pool.connect((err, client, done) => {
     if (err) {
       console.error('PostgreSQL connection error:', err);
       return;
     }
     console.log('Connected to PostgreSQL');
     client.release();
   });
   
   // Uwaga: dane logowania znajdziesz/zmienisz w panelu ServBay.
   // Nie zapisuj haseł na stałe w kodzie!

   Domyślnie PostgreSQL w ServBay nasłuchuje na porcie 5432. Nazwę użytkownika i hasło znajdziesz w panelu zarządzania bazami ServBay. Bazy zwykle trzeba utworzyć ręcznie (np. TablePlus, DBeaver, pgAdmin).

Zarządzanie bazami danych przez GUI w ServBay

Możesz korzystać z narzędzi graficznych do zarządzania bazami ServBay (nasłuchują one na 127.0.0.1/localhost i domyślne porty):

• Domyślne hasła: Sprawdź lub zmień domyślne hasło użytkownika w panelu ServBay – przy odpowiednim pakiecie bazy wybierz ikonę ustawień.
• Tworzenie baz i użytkowników: Podłącz się do bazy np. przez TablePlus, DBeaver, pgAdmin czy MongoDB Compass korzystając z localhost i domyślnych poświadczeń, następnie twórz bazy, użytkowników i tabele/encje wedle potrzeb.

Wskazówki i uwagi

• Konflikt portów: Upewnij się, że wybrane porty (np. 8585, 8586) nie są zajęte przez inne procesy.
• Status ServBay: Sprawdź, czy aplikacja i wymagane pakiety Node.js/baz danych są uruchomione.
• Plik hosts: ServBay zarządza nim automatycznie, w razie problemów sprawdź /etc/hosts pod kątem odpowiednich wpisów.
• Zapora sieciowa: Zweryfikuj, czy firewall macOS lub aplikacje firm trzecich nie blokują połączeń do ServBay/Node.js.
• Logi: W razie trudności sprawdź dzienniki aplikacji ServBay (zakładka "Logi" w GUI) i konsolę Node.js.

FAQ – Najczęstsze pytania

• Dlaczego używać reverse proxy w ServBay do obsługi Koa.js zamiast bezpośrednio przez localhost:PORT?

  Odpowiedź: Reverse proxy (przez Website w ServBay) daje wiele korzyści:

  1. Symulacja produkcji: Własna domena (np. .servbay.demo) wierniej odzwierciedla rzeczywisty serwis niż localhost:PORT.
  2. Wsparcie SSL: ServBay automatycznie konfiguruje SSL (własny CA lub Let's Encrypt), co pozwala testować HTTPS już w fazie developmentu.
  3. Centralne zarządzanie: Wszystkie lokalne projekty webowe dostępne i sterowane z poziomu jednej aplikacji.
  4. Ukrywanie portów: Browser i użytkownicy korzystają z portów 80/443, wewnętrznie ruch przekierowywany jest na wewnętrzne porty Node.js.

• Czy mogę po prostu używać localhost:PORT do developmentu, pomijając reverse proxy?

  Odpowiedź: Tak. Aplikacja Koa.js może nasłuchiwać na wybranym porcie (np. 3000) i wtedy możesz wejść na http://localhost:PORT w przeglądarce. Jednak nie skorzystasz wtedy z funkcji domen, automatycznego SSL, centralnych logów czy łatwego kopiowania warunków produkcyjnych. Reverse proxy w ServBay jest lepszym wyborem do symulacji rzeczywistej infrastruktury.

• Jakie są domyślne hasła do baz danych ServBay? Jak je zmienić?

  Odpowiedź: Domyślne dane logowania (np. root dla MariaDB czy user dla PostgreSQL) znajdziesz w zakładce Baza danych aplikacji ServBay – wystarczy kliknąć ikonę konfiguracji przy odpowiedniej bazie. Możesz je także w tym miejscu zmienić. Dla bezpieczeństwa zawsze zmieniaj domyślne hasła!

Podsumowanie

Dzięki temu przewodnikowi umiesz już skonfigurować środowisko Koa.js na macOS z użyciem ServBay. Stworzyliśmy podstawową aplikację Koa.js, skonfigurowaliśmy reverse proxy przez moduł Website, umożliwiając dostęp do lokalnego serwera z własną domeną i przez HTTPS, zarówno w wersji developerskiej, jak i produkcyjnej. Poznałeś także sposoby integracji z popularnymi bazami danych w ServBay.

ServBay daje deweloperom Node.js wydajne, zintegrowane, proste w zarządzaniu środowisko lokalne. Możesz dzięki temu skupić się na kodowaniu, a nie żmudnej konfiguracji stosu. Wykorzystując możliwości ServBay, znacznie zwiększysz swoją efektywność programistyczną.