Створення та запуск проекту Koa.js із ServBay

ServBay — це локальне середовище розробки для macOS і Windows, яке інтегрує популярні інструменти для розробників, зокрема runtime Node.js та бази даних. У цій статті ви дізнаєтеся, як швидко створити, запустити та адмініструвати свій проект на Koa.js за допомогою зручного інтерфейсу ServBay.

Що таке Koa.js?

Koa.js — це сучасний веб-фреймворк на основі Node.js, створений командою Express.js. Він вирізняється мінімалізмом, гнучкістю і потужною системою middleware, що робить Koa ідеальним вибором для створення веб-додатків і API. Koa.js використовує всі переваги сучасного JavaScript, особливо синтаксис async/await, що суттєво спрощує роботу з асинхронними операціями і middleware, роблячи код зрозумілим і легким для підтримки.

Основні переваги Koa.js

• Синхронізований async/await: Дизайн фреймворку базується на async/await, що дозволяє інтуїтивно організовувати асинхронну обробку запитів.
• Легкість ядра: Koa має компактне ядро, яке містить лише базові функції. Більшість можливостей додаються через модульні middleware.
• Потужна система middleware: Використовується каскадна модель побудови обробників, що забезпечує гнучкий і зрозумілий потік обробки запитів.
• Орієнтація на WEB: Koa зосереджений виключно на розробці веб-додатків і API, без зайвої функціональності.

Використання Koa.js дозволяє розробникам ефективно створювати високопродуктивні та підтримувані веб-сервіси.

Налаштування середовища розробки Koa.js із ServBay

ServBay пропонує Node.js-розробникам готове до використання середовище, інтегроване з популярними базами даних та інструментами. Використовуючи функцію Website ServBay, ви можете легко запускати проекти локально з власним доменом і SSL-сертифікатом.

Необхідні умови

Перед початком переконайтеся, що виконані такі кроки:

1. Встановіть ServBay: Перейдіть на офіційний сайт ServBay і скачайте найновішу версію.
2. Встановіть Node.js: Відкрийте додаток ServBay, перейдіть у розділ Packages, і переконайтеся, що потрібна версія Node.js встановлена. У разі потреби, виберіть її та натисніть кнопку встановлення.
3. Ознайомтеся з основами ServBay: Дізнайтеся, як запускати/зупиняти сервіси та керувати сайтами (Website) у ServBay.

Створення проекту Koa.js

Використовуйте рекомендовану ServBay кореневу папку сайтів — /Applications/ServBay/www.

1. Ініціалізуйте робочу директорію

   Відкрийте застосунок Terminal, перейдіть у кореневу папку сайтів ServBay і створіть нову папку для проекту (наприклад, servbay-koa-app). Перейдіть у цю папку і ініціалізуйте новий Node.js-проект:

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

   Команда npm init -y швидко створить базовий файл package.json.

2. Встановіть Koa.js

   У корені проекту servbay-koa-app встановіть Koa.js і, якщо потрібно, типи для TypeScript:

   npm install koa
   # Якщо використовуєте TypeScript, можна встановити типи
   # npm install @types/koa --save-dev

3. Створіть вхідний файл застосунку

   У папці servbay-koa-app створіть файл app.js із простим кодом Koa.js:

   const Koa = require('koa');
   const app = new Koa();
   
   // Middleware: логування запитів
   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: обробка головного маршруту
   app.use(async ctx => {
     ctx.body = 'Hello from ServBay Koa.js App!';
   });
   
   // Визначення порту, пріоритет — змінна середовища PORT
   const port = process.env.PORT || 3000;
   
   // Запускаємо HTTP сервер
   app.listen(port, () => {
     console.log(`Koa.js server running on http://localhost:${port}`);
     console.log(`Project path: ${__dirname}`);
   });

   Цей код створює базовий застосунок Koa з двома middleware: один для логування часу та шляху запиту, другий — для відповіді на запити на головний маршрут /. Застосунок слухає порт, вказаний у змінній PORT, або за замовчуванням 3000.

Перехід у режим розробки

Під час розробки запускається локальний процес Node.js для Koa.js, а для зручності можна відкрити проект через домен у ServBay за допомогою функції Website.

1. Запустіть сервер розробки Koa.js

   Відкрийте Terminal, перейдіть у папку проекту, і запустіть файл app.js. Для уникнення конфліктів або для зручнішої інтеграції з ServBay можна використовувати порт 8585:

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

   У вікні терміналу з’явиться повідомлення, наприклад Koa.js server running on http://localhost:8585, що підтверджує запуск сервера. Залиште це вікно відкритим для роботи сервера.

2. Налаштуйте реверсивний проксі у ServBay Website

   Щоб відкривати Koa.js через власний домен, потрібно у ServBay налаштувати сайт із використанням реверсивного проксі.

   • Відкрийте додаток ServBay.
   • Перейдіть у розділ Website.
   • Натисніть кнопку + для додавання нового сайту.
   • Заповніть конфігурацію:
     • Name: ServBay Koa.js Dev Site
     • Domain: servbay-koa-dev.servbay.demo (рекомендується використовувати домени з .servbay.demo, адже ServBay автоматично випускає SSL-сертифікати)
     • Type: виберіть Reverse Proxy
     • IP Address: 127.0.0.1 (локальний процес Node.js)
     • Port: 8585 (порт, який слухає ваш Koa.js додаток)
     • Document Root: для проксі неважливо, можна залишити порожнім або зазначити шлях проекту /Applications/ServBay/www/servbay-koa-app.
   • Натисніть зберегти.
   • Можливо, необхідно застосувати зміни — натискайте відповідну кнопку.

   Після налаштування ServBay автоматично допише запис у локальний файл hosts для вашого домену та налаштує проксі через Caddy або Nginx. Якщо використовується домен з .servbay.demo, ServBay User CA автоматично підпише та довіриться SSL-сертифікату, тому сайт доступний через HTTPS.

   Докладний покроковий опис ви знайдете у документації ServBay щодо додавання Node.js сайту (англійською).

3. Відкрийте сайт Koa.js для розробки

   Відкрийте браузер і перейдіть на https://servbay-koa-dev.servbay.demo.

   Якщо все налаштовано коректно, ви побачите на сторінці текст "Hello from ServBay Koa.js App!". Це означає, що ви успішно підключилися до локального сервера Koa.js через сервіс Website ServBay. Змінивши файл app.js та перезапустивши процес Node.js, оновіть сторінку, щоб побачити результат.

Імітація продакшн-деплою

Для моделювання продакшн-оточення використовуйте інший порт, змінні середовища або режим запуску. Реверсивний проксі ServBay працює аналогічним чином.

1. Запуск продакшн-сервера Koa.js (моделювання)

   У новому терміналі зупиніть сервер розробки й запустіть додаток у умовно продакшн-режимі, наприклад:

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

   Так додаток слухає порт 8586 й працює в режимі prod.

2. Встановіть новий реверсивний проксі для продакшн-симуляції

   Додайте ще один сайт у ServBay:

   • Відкрийте додаток ServBay та розділ Website.
   • Натисніть + для створення нового сайту.
   • Заповніть конфігурацію:
     • Name: ServBay Koa.js Prod Site
     • Domain: servbay-koa-prod.servbay.demo (або власний домен — ServBay підтримує безкоштовні SSL, наприклад, через Let's Encrypt)
     • Type: Reverse Proxy
     • IP Address: 127.0.0.1
     • Port: 8586 (порт Koa.js у prod-режимі)
     • Document Root: залиште порожнім або вкажіть шлях до проекту.
   • Збережіть та застосуйте зміни.

   Для домену .servbay.demo використовується сертифікат ServBay User CA. Якщо використовується публічний домен, ServBay підтримує автоматичну заявку та оновлення SSL/TLS через Let's Encrypt. Детальніше читайте у документації ServBay щодо захисту SSL.

3. Відкрийте "продакшн"-сайт Koa.js

   В браузері введіть https://servbay-koa-prod.servbay.demo.

   Сторінка буде аналогічна розробницькій, але запит буде проксійовано на процес Node.js на порту 8586.

Підключення до баз даних

ServBay містить популярні бази даних — MongoDB, Redis, MariaDB (MySQL-сумісний) та PostgreSQL. Підключатися до них із вашого проекту Koa.js дуже просто: всі бази працюють локально, стандартним налаштуванням є localhost.

Нижче — приклади підключення до баз даних через Node.js. Переконайтеся, що відповідні пакети та служби встановлені й запущені у розділі Packages ServBay.

1. Підключення до MongoDB

   Встановіть драйвер для Node.js (наприклад, mongoose чи mongodb):

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mongoose # або npm install mongodb

   Додайте код підключення у app.js чи окремий модуль:

   // Підключення до MongoDB через Mongoose
   const mongoose = require('mongoose');
   
   // У стандартній конфігурації ServBay MongoDB не вимагає автентифікації, назву БД можна задавати довільно
   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));
   
   // Зазвичай підключення до бази здійснюється у логіці запуску додатку,
   // і прослуховування порту починається лише після успішного підключення.

   За замовчуванням MongoDB у ServBay слухає порт 27017, автентифікація вимкнена.

2. Підключення до Redis

   Встановіть клієнт для Redis:

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

   Код підключення:

   // Підключення до Redis
   const redis = require('redis');
   
   // Клієнт Redis, стандартний порт — localhost:6379
   const client = redis.createClient({
     url: 'redis://localhost:6379' // порт ServBay за замовчуванням
   });
   
   client.on('connect', () => {
     console.log('Connected to Redis');
   });
   
   client.on('error', (err) => {
     console.error('Redis connection error:', err);
   });
   
   // Встановлення з'єднання
   client.connect();
   
   // В реальних проектах використовуйте async/await і client.connect() для коректної роботи з асинхронними командами

   Redis у ServBay працює на порту 6379 і не вимагає пароля.

3. Підключення до MariaDB (MySQL)

   MariaDB — це форк MySQL з сумісними API. ServBay містить пакет MariaDB, який можна використовувати як MySQL.

   Встановіть драйвер Node.js:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mariadb # або npm install mysql2 (краще для сумісності)

   Підключення через mariadb:

   // Підключення до MariaDB
   const mariadb = require('mariadb');
   
   // Стандартний пароль користувача root у ServBay — 'password'
   const pool = mariadb.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // переконайтеся, що база створена
     connectionLimit: 5
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Connected to MariaDB");
       conn.release(); // повертаємо з'єднання у пул
     })
     .catch(err => {
       console.error("MariaDB connection error:", err);
     });
   
   // Отримання з'єднання з пулу — асинхронна операція

   Через mysql2 (рекомендується):

   // Підключення до MariaDB/MySQL через mysql2
   const mysql = require('mysql2/promise'); // promise-версія
   
   // root-пароль у ServBay — 'password'
   const pool = mysql.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // база має бути створена
     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);
     });
   
   // root-пароль завжди можна переглянути чи змінити у GUI ServBay в налаштуваннях бази.
   // Для безпеки не зберігайте паролі у коді, використовуйте змінні середовища.

   MariaDB у ServBay слухає порт 3306. root-пароль можна переглянути/змінити в розділі налаштувань бази даних ServBay. Саму базу треба створити вручну через інтерфейс ServBay чи будь-який клієнт (TablePlus, DBeaver тощо).

4. Підключення до PostgreSQL

   Встановіть драйвер:

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

   Приклад підключення:

   // Підключення до PostgreSQL через pg
   const { Pool } = require('pg');
   
   // Стандартний користувач ServBay — 'user', пароль — 'password'
   const pool = new Pool({
     user: 'user', // стандартний користувач
     host: 'localhost',
     database: 'servbay_koa_app', // база має бути створена
     password: 'password',
     port: 5432, // стандартний порт PostgreSQL у ServBay
   });
   
   pool.connect((err, client, done) => {
     if (err) {
       console.error('PostgreSQL connection error:', err);
       return;
     }
     console.log('Connected to PostgreSQL');
     client.release(); // повернути з'єднання у пул
   });
   
   // Дані для підключення та зміну пароля дивіться у GUI ServBay в налаштуваннях бази.
   // Не зберігайте паролі у коді — використовуйте змінні середовища!

   PostgreSQL у ServBay працює на порту 5432. Дані для підключення та пароль можна переглянути у GUI ServBay. Базу, як і у випадку з MariaDB, потрібно створити вручну.

Адміністрування баз даних у ServBay

Окрім підключень через код, ви можете керувати базами даних за допомогою графічних інструментів. Бази слухають на localhost, використовуйте порт, логін і пароль із GUI ServBay або документації.

• Перегляд/зміна пароля: В GUI ServBay поруч із кожною базою є іконка налаштувань — там вказані чи змінюються стандартні паролі та логіни (root для MariaDB, user для PostgreSQL).
• Створення баз, користувачів: Використовуйте TablePlus, DBeaver, pgAdmin, MongoDB Compass чи інший клієнт, підключайтесь через локальні порти та керуйте об'єктами через SQL або графічний інтерфейс.

Важливі зауваження

• Конфлікти портів: Переконайтеся, що порти (наприклад 8585, 8586), на яких працює ваш Koa.js, не зайняті іншими програмами.
• Стан ServBay: Перевірте, що додаток ServBay і необхідні пакети Node.js та бази даних — запущені.
• Файл hosts: ServBay керує hosts автоматично, але для вирішення доменних проблем перевірте /etc/hosts.
• Фаєрвол: Переконайтеся, що macOS Firewall чи сторонній фаєрвол не блокує ServBay або Node.js.
• Логування: У випадку помилок перевіряйте логи (у вкладці логів ServBay і консоль Node.js), це допоможе діагностувати проблеми.

Часті питання (FAQ)

• Чому для доступу до проекту Koa.js варто використовувати реверсивний проксі ServBay?

  Відповідь: Використання реверсивного проксі (через сервіс Website) корисне з багатьох причин:

  1. Імітація продакшн-оточення: Власний домен (наприклад, .servbay.demo або офіційний) більш подібний до реального сайту, ніж localhost:PORT.
  2. SSL-підтримка: ServBay автоматично налаштовує SSL (сертифікати ServBay User CA або Let's Encrypt), тому можна тестувати HTTPS прямо під час розробки.
  3. Централізоване управління: Легко керувати всіма локальними сайтами в одному місці.
  4. Сховати порт: Зовнішній доступ або браузер використовують стандартні порти 80/443, а запит проксіюється на Node.js, який працює на внутрішньому порту.

• Чи можна просто користуватись localhost:PORT, не налаштовуючи проксі?

  Відповідь: Можна. Якщо ваш додаток Koa.js слухає певний порт (наприклад 3000), можна просто відкривати http://localhost:PORT. Але так ви не отримаєте переваг домену, SSL, зручної системи логів. Для максимально реалістичного локального деплойменту рекомендується використовувати проксі ServBay.

• Який стандартний пароль для баз даних у ServBay та як його змінити?

  Відповідь: Стандартний пароль вказано у GUI ServBay в розділі Database — натисніть на потрібну базу й іконку налаштувань, там будуть дані для доступу і можливість змінити пароль. Для безпеки радимо змінити дефолтний пароль!

Висновок

Після виконання цих інструкцій ви навчитеся використовувати ServBay для локального розгортання середовища розробки Koa.js на macOS. Ви створите базовий застосунок, налаштуєте домен, HTTPS і реверсивний проксі через сервіс Website, а також підключитеся до популярних баз даних, які пропонує ServBay.

ServBay забезпечує Node.js-розробникам інтегроване, просте у керуванні середовище, дозволяючи більше часу присвячувати програмуванню, а не налаштуванню інфраструктури. Використовуйте можливості ServBay для підвищення ефективності вашої розробки!