Tạo và chạy dự án Koa.js với ServBay

ServBay là một môi trường phát triển web cục bộ được thiết kế dành riêng cho macOS, tích hợp nhiều gói phần mềm phổ biến cho lập trình viên, bao gồm cả môi trường chạy Node.js và các cơ sở dữ liệu khác nhau. Bài viết này sẽ hướng dẫn bạn tận dụng môi trường thuận tiện do ServBay cung cấp để nhanh chóng tạo, vận hành và quản lý dự án Koa.js của mình.

Koa.js là gì?

Koa.js là một framework web thế hệ mới dựa trên Node.js, được phát triển bởi đội ngũ đứng sau Express.js. Koa nổi bật với kiến trúc tối giản, diễn đạt mạnh mẽ và bộ tính năng phong phú, là lựa chọn lý tưởng để xây dựng web app và API. Koa.js khai thác tối đa tính năng hiện đại của JavaScript, đặc biệt là cú pháp async/await, giúp việc xử lý bất đồng bộ cũng như xây dựng middleware trở nên rõ ràng, dễ đọc, dễ bảo trì hơn rất nhiều.

Các đặc điểm nổi bật của Koa.js

• Hỗ trợ async/await trực quan: Thiết kế xoay quanh async/await, kiểm soát luồng bất đồng bộ trở nên tự nhiên.
• Nhân gọn nhẹ: Thư viện lõi Koa nhỏ gọn, chỉ chứa những thành phần cơ bản; các tính năng mở rộng được tích hợp thông qua middleware dạng module.
• Hệ thống middleware mạnh mẽ: Cơ chế middleware chuỗi (cascading) giúp xử lý request rõ ràng, linh hoạt.
• Tập trung cho web: Koa hướng đến xây dựng ứng dụng web và API, không đem theo các chức năng dư thừa không cần thiết.

Nhờ đó, lập trình viên có thể nhanh chóng xây dựng những dịch vụ web hiệu suất cao mà vẫn dễ dàng duy trì, mở rộng.

Thiết lập môi trường phát triển Koa.js với ServBay

ServBay cung cấp cho lập trình viên Node.js một môi trường sẵn sàng sử dụng, tích hợp sẵn runtime Node.js cũng như các dịch vụ database cần thiết. Kết hợp với tính năng Website của ServBay, bạn có thể dễ dàng truy cập dự án Koa.js thông qua domain tùy chỉnh, kể cả được cấp phát SSL certificate an toàn.

Yêu cầu trước khi bắt đầu

Trước khi tiến hành, hãy đảm bảo bạn đã chuẩn bị:

1. Cài đặt ServBay: Truy cập trang chủ ServBay để tải về và cài đặt phiên bản mới nhất của ServBay.
2. Cài đặt gói Node.js: Mở ứng dụng ServBay, chuyển đến giao diện Packages (Gói phần mềm), đảm bảo bạn đã cài đặt phiên bản Node.js cần thiết. Nếu chưa, chọn và cài đặt.
3. Hiểu các thao tác cơ bản của ServBay: Biết cách khởi động/dừng dịch vụ và quản lý website trong ServBay.

Khởi tạo dự án Koa.js

Ta sẽ lưu trữ mã nguồn dự án tại thư mục gốc website ServBay là /Applications/ServBay/www.

1. Khởi tạo thư mục dự án

   Mở ứng dụng Terminal, chuyển vào thư mục gốc của website ServBay, tạo một thư mục mới cho dự án (ví dụ servbay-koa-app). Sau đó vào thư mục này và khởi tạo dự án Node.js mới:

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

   Lệnh npm init -y sẽ tạo file package.json với cấu hình mặc định.

2. Cài đặt Koa.js

   Trong thư mục servbay-koa-app, dùng npm để cài Koa.js và những định nghĩa kiểu dữ liệu nếu dùng TypeScript:

   npm install koa
   # Nếu dùng TypeScript, có thể cài đặt định nghĩa type
   # npm install @types/koa --save-dev

3. Tạo file khởi động ứng dụng

   Trong thư mục gốc dự án, tạo file app.js với nội dung sau:

   const Koa = require('koa');
   const app = new Koa();
   
   // Middleware: Ghi log thông tin request
   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: Xử lý request đến trang gốc
   app.use(async ctx => {
     ctx.body = 'Hello from ServBay Koa.js App!';
   });
   
   // Đặt port ưu tiên từ biến môi trường PORT
   const port = process.env.PORT || 3000;
   
   // Khởi động server HTTP
   app.listen(port, () => {
     console.log(`Koa.js server running on http://localhost:${port}`);
     console.log(`Project path: ${__dirname}`);
   });

   Đoạn mã này tạo một ứng dụng Koa.js cơ bản với hai middleware: một để log thời gian và đường dẫn request, một để trả về chuỗi "Hello from ServBay Koa.js App!" khi truy cập /. Ứng dụng sẽ lắng nghe ở port do biến môi trường PORT hoặc mặc định là 3000.

Chạy dự án ở chế độ phát triển

Trong giai đoạn phát triển, bạn sẽ thường chạy một tiến trình Node.js cục bộ để kiểm thử dự án Koa.js, đồng thời truy cập qua tính năng Website của ServBay.

1. Chạy server phát triển Koa.js

   Mở Terminal, chuyển vào thư mục dự án servbay-koa-app và khởi chạy file app.js bằng lệnh node. Để tránh trùng port hoặc dễ cấu hình ServBay, hãy chọn một port khác, ví dụ 8585:

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

   Terminal sẽ hiện thông báo đại loại như Koa.js server running on http://localhost:8585, nghĩa là server đã chạy và lắng nghe ở port 8585. Giữ cửa sổ này mở để server liên tục hoạt động.

2. Cấu hình reverse proxy cho Website trên ServBay

   Để truy cập ứng dụng Koa.js chạy ở localhost:8585 qua domain tùy chỉnh, ta cần cấu hình một Website mới trên ServBay với loại reverse proxy.

   • Mở ứng dụng ServBay.
   • Vào mục Website.
   • Nhấn nút + ở góc trái để thêm website mới.
   • Điền thông tin cấu hình:
     • Tên (Name): ServBay Koa.js Dev Site
     • Tên miền (Domain): servbay-koa-dev.servbay.demo (nên dùng đuôi .servbay.demo, ServBay sẽ tự động phát certificate SSL)
     • Loại (Type): Chọn Reverse Proxy
     • Địa chỉ IP (IP Address): 127.0.0.1 (trỏ về Node.js chạy cục bộ)
     • Cổng (Port): 8585 (trùng với app Koa.js để lắng nghe)
     • Root (Document Root): Vì là reverse proxy nên phần này có thể để trống hoặc điền đường dẫn dự án /Applications/ServBay/www/servbay-koa-app.
   • Lưu lại các thay đổi.
   • Nếu ServBay yêu cầu áp dụng thay đổi, hãy xác nhận và tiếp tục.

   Sau khi cấu hình, ServBay sẽ tự động cập nhật file hosts trên máy, trỏ domain servbay-koa-dev.servbay.demo về 127.0.0.1, đồng thời sử dụng dịch vụ Caddy hoặc Nginx tích hợp để proxy request đến port 8585. Đặc biệt, với domain .servbay.demo, ServBay sẽ tự phát và tin cậy certificate SSL giúp bạn truy cập qua HTTPS an toàn.

   Nếu cần hướng dẫn chi tiết hơn, xem thêm tài liệu ServBay về thêm website Node.js phát triển (lưu ý chọn bản tiếng Anh).

3. Truy cập website Koa.js vừa phát triển

   Mở trình duyệt và truy cập https://servbay-koa-dev.servbay.demo.

   Nếu mọi thứ cấu hình đúng, bạn sẽ thấy trang hiện thông điệp "Hello from ServBay Koa.js App!". Tức là bạn đã thành công truy cập Koa.js chạy cục bộ thông qua website cấu hình trên ServBay. Sau mỗi lần sửa đổi file app.js và khởi động lại Node.js, chỉ cần refresh trình duyệt là thấy kết quả.

Mô phỏng triển khai phiên bản production

Để mô phỏng môi trường production (lưu trữ thực tế), bạn nên chạy app Koa.js với port, biến môi trường và cách khởi động khác. Cách cấu hình reverse proxy trên ServBay vẫn giống như ở môi trường phát triển.

1. Chạy server production Koa.js (mô phỏng)

   Trong một cửa sổ terminal khác, tắt server dev trước (nếu còn), rồi chạy app với cấu hình mô phỏng môi trường production, ví dụ dùng port 8586 và đặt biến môi trường NODE_ENV:

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

   Ứng dụng sẽ chạy ở port 8586, đóng vai trò như production server thực thụ.

2. Cấu hình website reverse proxy trên ServBay (mô phỏng production)

   Thực hiện tương tự, cấu hình thêm một website mới trên ServBay:

   • Mở ứng dụng ServBay và truy cập Website.
   • Nhấn nút + để tạo website.
   • Điền như sau:
     • Tên (Name): ServBay Koa.js Prod Site
     • Tên miền (Domain): servbay-koa-prod.servbay.demo (hoặc nếu có domain riêng, có thể dùng và xin SSL qua Let's Encrypt)
     • Loại (Type): Chọn Reverse Proxy
     • IP: 127.0.0.1
     • Port: 8586 (trùng với port app production Koa.js)
     • Root: Để trống hoặc điền đường dẫn dự án.
   • Lưu và áp dụng thay đổi.

   Với domain .servbay.demo, bạn tiếp tục được cấp chứng chỉ ServBay User CA. Nếu dùng domain riêng, ServBay hỗ trợ tự động xin/cập nhật SSL certificate miễn phí qua ACME/Let's Encrypt, giúp môi trường test sát thực tế. Xem thêm hướng dẫn sử dụng SSL bảo vệ website.

3. Truy cập website Koa.js production (mô phỏng)

   Mở trình duyệt và vào https://servbay-koa-prod.servbay.demo.

   Bạn sẽ nhận được kết quả giống môi trường dev, nhưng request lúc này được gửi đến tiến trình Node.js đang lắng nghe ở port 8586 qua reverse proxy.

Kết nối cơ sở dữ liệu

ServBay tích hợp nhiều hệ quản trị cơ sở dữ liệu phổ biến: MongoDB, Redis, MariaDB (tương thích MySQL) và PostgreSQL. Dự án Koa.js của bạn có thể kết nối dễ dàng với chúng vì tất cả đều chạy cục bộ (localhost), mặc định truy cập qua localhost.

Dưới đây là các ví dụ kết nối database điền hình. Nhớ rằng bạn cần cài và chạy dịch vụ database tương ứng trong mục Packages của ServBay trước.

1. Kết nối MongoDB

   Đầu tiên, cài đặt driver Node.js cho MongoDB (ví dụ mongoose hoặc mongodb):

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mongoose # hoặc npm install mongodb

   Thêm đoạn mã kết nối vào app.js hoặc module khác:

   // Kết nối MongoDB sử dụng Mongoose
   const mongoose = require('mongoose');
   
   // MongoDB trên ServBay không bắt buộc auth, tên DB tự chọn
   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));
   
   // Ghi chú: trong ứng dụng thực tế, nên thực hiện connect khi khởi động app
   // và chỉ bắt đầu lắng nghe cổng sau khi connect thành công.

   MongoDB ServBay thường lắng nghe cổng 27017, không cần user/password mặc định. Tên database tự động tạo khi kết nối nếu chưa có.

2. Kết nối Redis

   Cài đặt thư viện client Node.js cho Redis:

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

   Kết nối đến Redis server:

   // Kết nối Redis với client redis
   const redis = require('redis');
   
   // Tạo client kết nối đến localhost:6379 (port chuẩn Redis trên ServBay)
   const client = redis.createClient({
     url: 'redis://localhost:6379'
   });
   
   client.on('connect', () => {
     console.log('Connected to Redis');
   });
   
   client.on('error', (err) => {
     console.error('Redis connection error:', err);
   });
   
   // Thực hiện kết nối Redis
   client.connect();
   
   // Ghi chú: nên đợi kết nối thành công rồi mới thao tác dữ liệu,
   // ví dụ với async/await kết hợp client.connect()

   Redis trên ServBay mặc định chạy port 6379, không cần password.

3. Kết nối MariaDB (hoặc MySQL)

   MariaDB là nhánh tương thích cao của MySQL. ServBay có sẵn MariaDB, bạn có thể sử dụng như MySQL.

   Cài đặt driver Node.js cho MariaDB/MySQL:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mariadb # hoặc npm install mysql2 (cực kỳ tương thích, khuyên dùng)

   Sử dụng driver mariadb để kết nối:

   // Kết nối MariaDB với client mariadb
   const mariadb = require('mariadb');
   
   // Mặc định user root có mật khẩu 'password' trên ServBay
   const pool = mariadb.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // đảm bảo database đã tồn tại hoặc chỉnh lại
     connectionLimit: 5
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Connected to MariaDB");
       conn.release(); // trả lại connection cho pool
     })
     .catch(err => {
       console.error("MariaDB connection error:", err);
     });
   
   // Chú ý: việc lấy connection từ pool là bất đồng bộ

   Sử dụng driver mysql2 (khuyến nghị):

   // Kết nối MariaDB/MySQL sử dụng mysql2/promise
   const mysql = require('mysql2/promise');
   
   // Mặc định user root có mật khẩu 'password' trên ServBay
   const pool = mysql.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // đảm bảo database đã tạo
     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);
     });
   
   // Chú ý: có thể xem/mặc định hoặc sửa password user root tại ServBay GUI.
   // Nên quản lý password bằng biến môi trường thay vì viết cứng mã nguồn.

   MariaDB mặc định trên ServBay lắng nghe ở port 3306. Thông tin password user root có thể xem/mặc định và thay đổi trong giao diện quản lý ServBay. Cần tự tạo database servbay_koa_app trong MariaDB bằng ServBay hoặc các công cụ như TablePlus, DBeaver...

4. Kết nối PostgreSQL

   Cài đặt driver Node.js cho PostgreSQL:

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

   Kết nối PostgreSQL:

   // Kết nối PostgreSQL dùng client pg
   const { Pool } = require('pg');
   
   // Mặc định user là 'user', password là 'password' trên ServBay
   const pool = new Pool({
     user: 'user', // user mặc định ServBay
     host: 'localhost',
     database: 'servbay_koa_app', // cần tạo sẵn database
     password: 'password', // mật khẩu mặc định ServBay
     port: 5432, // port mặc định PostgreSQL trên ServBay
   });
   
   pool.connect((err, client, done) => {
     if (err) {
       console.error('PostgreSQL connection error:', err);
       return;
     }
     console.log('Connected to PostgreSQL');
     client.release();
   });
   
   // Chú ý: có thể xem/cập nhật thông tin user và password qua ServBay GUI.
   // Nên quản lý password bằng biến môi trường.

   PostgreSQL trên ServBay mặc định chạy port 5432. Thông tin tài khoản và mật khẩu có thể xem/cập nhật trong phần quản lý database của ServBay. Cần tự tạo database servbay_koa_app trước khi kết nối.

Quản lý cơ sở dữ liệu trong ServBay

Ngoài việc kết nối qua mã nguồn, bạn có thể dùng các tool giao diện như TablePlus, DBeaver, pgAdmin, MongoDB Compass... để kết nối và quản lý database của ServBay. Các database mặc định lắng nghe trên 127.0.0.1 hoặc localhost, sử dụng port và thông tin user/pass hiển thị trong giao diện ServBay.

• Xem/sửa mật khẩu mặc định: Mở ứng dụng ServBay, chọn database cần xem, nhấn biểu tượng chỉnh sửa để xem hoặc đổi mật khẩu mặc định cho user root (MariaDB) hoặc user (PostgreSQL).
• Tạo database/user: Dùng các ứng dụng như TablePlus, DBeaver, pgAdmin..., đăng nhập database, sau đó tạo database, user, bảng... qua giao diện trực quan hoặc lệnh SQL.

Lưu ý quan trọng

• Trùng port: Đảm bảo port bạn chọn cho Koa.js (như 8585, 8586) chưa bị chương trình nào khác chiếm dụng trên hệ thống.
• Trạng thái ServBay: Đảm bảo ServBay và các gói Node.js, database bạn cần đều đang chạy.
• File hosts: ServBay tự động cập nhật file hosts, nếu gặp lỗi tên miền thì kiểm tra file /etc/hosts có đúng bản ghi chưa.
• Tường lửa: Kiểm tra tường lửa của macOS hoặc ứng dụng bảo mật bên thứ ba không chặn ServBay hay tiến trình Node.js.
• Kiểm tra log: Khi gặp sự cố, hãy tra cứu log của ServBay (tab Log trong giao diện ServBay) và console của Node.js để xác định nguyên nhân.

Câu hỏi thường gặp (FAQ)

• Hỏi: Tại sao nên dùng reverse proxy của ServBay để truy cập dự án Koa.js?

  Trả lời: Sử dụng reverse proxy (qua Website ServBay) mang lại nhiều lợi ích:

  1. Mô phỏng môi trường thật: Truy cập qua domain tùy chỉnh như .servbay.demo hay domain cá nhân thay vì localhost:PORT giúp trải nghiệm sát với cách deploy ngoài thực tế.
  2. Hỗ trợ SSL: ServBay tự động cấp/tin cậy chứng chỉ SSL cho website (dùng ServBay User CA hoặc Let's Encrypt), giúp bạn kiểm thử HTTPS ngay trên máy.
  3. Quản lý tập trung: Tất cả website phát triển được quản lý tập trung trong ServBay.
  4. Ẩn port: Trình duyệt/truy cập sử dụng port chuẩn 80/443, còn request thực chuyển tiếp tới Node.js ở port riêng, bảo mật và tiện lợi hơn.

• Hỏi: Có bắt buộc dùng reverse proxy không, có thể truy cập trực tiếp localhost:PORT không?

  Trả lời: Có thể. Nếu app Koa.js của bạn lắng nghe ở port nào thì truy cập trực tiếp qua trình duyệt là được. Tuy nhiên, bạn sẽ bỏ lỡ các tính năng domain tùy chỉnh, SSL tự động, quản lý log, và môi trường phát triển sát thực tế do ServBay cung cấp. Để dễ dàng deploy hoặc kiểm thử chuẩn nhất, nên dùng reverse proxy của ServBay.

• Hỏi: Mật khẩu database mặc định của ServBay là gì, đổi ở đâu?

  Trả lời: Mật khẩu mặc định của các database có thể xem trong tab Database của ứng dụng ServBay. Nhấn nút cài đặt cạnh tên database (như MariaDB hay PostgreSQL), xem thông tin user/password mặc định và đổi tại đây nếu muốn. Vì lý do bảo mật, bạn nên đổi mật khẩu mặc định.

Tổng kết

Qua bài hướng dẫn này, bạn đã biết cách sử dụng ServBay để thiết lập môi trường phát triển Koa.js trên macOS. Ta đã tạo ứng dụng Koa.js cơ bản, cấu hình reverse proxy website qua ServBay để truy cập bằng domain riêng với hỗ trợ HTTPS. Đồng thời, bạn cũng nắm được cách kết nối tới các database nội bộ do ServBay tích hợp.

ServBay cung cấp một môi trường phát triển Node.js tích hợp, quản lý dễ dàng giúp bạn tập trung tối đa vào phát triển chương trình thay vì mất thời gian cấu hình. Hãy tận dụng mọi tính năng mạnh mẽ của ServBay để nâng cao hiệu suất lập trình của bạn!