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:

1. Zainstaluj ServBay: Pobierz najnowszą wersję z oficjalnej strony ServBay i zainstaluj ją.
2. 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".
3. 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.

1. 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:

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

   Polecenie npm init -y szybko utworzy domyślny plik package.json.

2. Instalacja Koa.js

   W głównym katalogu servbay-koa-app, zainstaluj Koa.js oraz – jeśli korzystasz z TypeScript – jego definicje typów:

   npm install koa
   # Jeśli korzystasz z TypeScript, zainstaluj definicje typów
   # npm install @types/koa --save-dev

3. Tworzenie pliku wejściowego aplikacji

   Utwórz plik app.js w katalogu projektu i wstaw poniższy przykładowy kod Koa.js:

   const 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}`);
   });

   Ten 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 na 3000.

Tryb deweloperski

W trakcie developmentu aplikację Koa.js uruchamiamy jako lokalny proces Node.js i odwiedzamy ją poprzez funkcję Witryny (Website) ServBay.

1. Uruchamianie serwera Koa.js

   Otwórz terminal, przejdź do katalogu servbay-koa-app i uruchom plik app.js za pomocą polecenia node. By uniknąć konfliktu portów/desygnowania portu w ServBay, zaleca się użyć np. portu 8585:

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

   W 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.

2. 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.
   • 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 na 127.0.0.1. Wbudowany serwer Caddy lub Nginx przekieruje żądania na port 8585. 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).

3. 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.

1. 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:

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

   Tak uruchomiony serwer nasłuchuje na porcie 8586 i symuluje środowisko produkcyjne.

2. 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.
   • 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.

3. 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.

1. Połącz z MongoDB

   Najpierw zainstaluj sterownik MongoDB dla Node.js (np. mongoose lub mongodb):

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

   Dodaj kod połączenia w pliku app.js lub odpowiednim module:

   // 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ą.

   MongoDB w ServBay nasłuchuje na porcie 27017 i domyślnie pozwala łączyć się bez autoryzacji.

2. Połącz z Redis

   Zainstaluj bibliotekę Redis dla Node.js:

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

   Połącz z Redis:

   // 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.

   Redis w ServBay nasłuchuje na porcie 6379 i zwykle nie wymaga hasła.

3. 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:

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

   Przykład z mariadb:

   // 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

   Przykład z mysql2 (polecane):

   // 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.

   MariaDB 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.

4. Połącz z PostgreSQL

   Zainstaluj bibliotekę pg dla Node.js:

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

   Połącz z PostgreSQL:

   // 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.

   Postgres 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:

  1. Symulację produkcji: Użycie domeny (np. .servbay.demo lub własnej) jest bliższe prawdziwej wdrożonej stronie niż localhost:PORT.
  2. SSL: Automatyczny certyfikat SSL (User CA ServBay lub Let's Encrypt) pozwala na testowanie HTTPS już podczas developmentu.
  3. Centralne zarządzanie: Łatwa administracja wszystkich lokalnych witryn w ServBay.
  4. Ukrycie portów: Dostęp przez standardowe porty 80/443, same żądania trafiają do Node.js na wyższych portach.

• 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.