ServBay로 Koa.js 프로젝트 생성 및 실행하기

ServBay는 macOS와 Windows를 모두 지원하는 로컬 웹 개발 환경으로, Node.js 런타임과 다양한 데이터베이스 등 개발자들이 자주 사용하는 소프트웨어 패키지가 통합되어 있습니다. 이 문서는 ServBay가 제공하는 편리한 환경을 활용하여 Koa.js 프로젝트를 빠르게 생성, 실행 그리고 관리하는 방법을 안내합니다.

Koa.js란 무엇인가요?

Koa.js는 Express.js 팀이 개발한, Node.js 기반의 차세대 웹 프레임워크입니다. 간결하면서도 강력한 기능을 갖추고 있어 웹 애플리케이션과 API 구축에 최적화된 선택지입니다. 현대 JavaScript의 async/await 문법을 적극적으로 활용하여 비동기 작업 및 미들웨어 작성이 매우 쉬워졌고, 코드의 가독성과 유지보수성이 크게 향상됩니다.

Koa.js의 주요 특징

async/await 기반: 코어 설계가 async/await에 맞춰져 있어 비동기 흐름 제어가 직관적입니다.
경량 코어: Koa의 핵심 라이브러리는 매우 작으며, 필수 기능만 포함합니다. 필요한 기능은 미들웨어로 확장 가능합니다.
강력한 미들웨어 시스템: 계단식(cascading) 미들웨어 구조를 채택해 요청 처리 흐름이 유연하고 명확합니다.
웹 특화: 웹 애플리케이션과 API 개발에 집중되어 불필요한 기능 없이 깔끔하게 설계되었습니다.

Koa.js를 사용하면 개발자들은 더 효율적이고 유지보수가 용이한 고성능 웹 서비스를 구축할 수 있습니다.

ServBay를 활용한 Koa.js 개발 환경 구축

ServBay는 Node.js 개발자를 위한 즉시 사용 가능한 환경을 제공합니다. Node.js 런타임과 데이터베이스 서비스가 내장되어 있으며, ServBay의 웹사이트(Website) 기능을 통해 로컬 프로젝트를 맞춤 도메인과 SSL 인증서로 쉽게 접근할 수 있습니다.

사전 준비

시작하기 전에 다음을 준비하세요:

ServBay 설치: ServBay 공식 웹사이트에서 최신 버전의 ServBay를 다운로드 및 설치하세요.
Node.js 패키지 설치: ServBay 앱을 열고, 패키지(Packages) 관리 화면에서 필요한 Node.js 버전을 설치했는지 확인하세요. 설치되지 않았다면 선택 후 설치를 진행하세요.
ServBay 기본 사용법 익히기: ServBay에서 서비스 시작/중지 및 웹사이트(Website) 관리 방식을 미리 숙지하세요.

Koa.js 프로젝트 생성

ServBay의 추천 웹사이트 루트 디렉토리 /Applications/ServBay/www에 프로젝트 파일을 저장합니다.

프로젝트 디렉토리 초기화
Terminal(터미널) 앱을 열고 ServBay 웹사이트 루트로 이동한 후, 새 프로젝트 폴더(예: servbay-koa-app)를 만들고 해당 폴더에서 Node.js 프로젝트를 초기화합니다:
bash
```
cd /Applications/ServBay/www
mkdir servbay-koa-app
cd servbay-koa-app
npm init -y
```
1
2
3
4
npm init -y 명령은 기본 package.json 파일을 빠르게 생성합니다.
Koa.js 설치
프로젝트 루트(servbay-koa-app)에서 npm으로 Koa.js와 타입 정의 파일(TypeScript 사용 시)을 설치합니다:
bash
```
npm install koa
# TypeScript를 사용할 경우 타입 정의 파일 설치
# npm install @types/koa --save-dev
```
1
2
3

앱 진입 파일 생성

프로젝트 루트인 servbay-koa-app 폴더에 app.js 파일을 만들고 아래와 같이 간단한 Koa.js 애플리케이션 코드를 작성합니다:

javascript

const Koa = require('koa');
const app = new Koa();

// 미들웨어: 요청 정보를 기록
app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
});

// 미들웨어: 루트 경로 요청 처리
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}`);
});

이 코드는 요청 시간 및 경로를 기록하는 미들웨어와, 루트(/) 요청에 "Hello from ServBay Koa.js App!"을 반환하는 미들웨어를 포함한 기본 Koa 애플리케이션을 생성합니다. 애플리케이션은 환경변수 PORT값 또는 3000포트에서 요청을 수신합니다.

개발 모드 진입

개발 중에는 로컬 Node.js 프로세스로 Koa.js 앱을 실행하고, ServBay의 웹사이트(Website) 기능을 통해 접근합니다.

Koa.js 개발 서버 실행
터미널에서 프로젝트 디렉토리(servbay-koa-app)로 이동한 후, node 명령어로 app.js 파일을 실행합니다. 포트 충돌을 방지하거나 ServBay 설정에 맞추기 위해 특정 포트(예: 8585)를 지정할 수 있습니다:
bash
```
cd /Applications/ServBay/www/servbay-koa-app
PORT=8585 node app.js
```
1
2
터미널에는 Koa.js server running on http://localhost:8585와 같은 메시지가 출력되면 정상적으로 8585 포트에서 서버가 실행 중임을 의미합니다. 이 터미널 창은 서버가 계속 동작하도록 열어둡니다.
ServBay 웹사이트(Website) 리버스 프록시 설정
localhost:8585에서 동작하는 Koa.js 앱을 맞춤 도메인으로 접근하려면 ServBay에 **웹사이트(Website)**를 리버스 프록시로 설정해야 합니다.
- ServBay 앱을 엽니다.
- 웹사이트(Website) 화면으로 이동합니다.
- 좌측 하단 + 버튼을 클릭해 새 사이트를 추가합니다.
- 다음과 같이 사이트를 설정합니다:
  - 이름(Name): ServBay Koa.js Dev Site
  - 도메인(Domain): servbay-koa-dev.servbay.demo (도메인은 .servbay.demo로 끝나면 ServBay가 자동으로 SSL 인증서를 발급/설정)
  - 타입(Type): 리버스 프록시(Reverse Proxy) 선택
  - IP 주소(IP Address): 127.0.0.1 (로컬 Node.js 프로세스에 연결)
  - 포트(Port): 8585 (Koa.js 애플리케이션 리스닝 포트)
  - 루트 디렉토리(Document Root): 리버스 프록시 타입에서는 필수가 아니므로 빈칸으로 두거나 프로젝트 경로(/Applications/ServBay/www/servbay-koa-app)로 설정
- 저장을 클릭합니다.
- 설정 적용 안내가 뜨면 적용을 누릅니다.
이후 ServBay는 로컬 hosts 파일을 자동으로 수정해 servbay-koa-dev.servbay.demo 도메인을 127.0.0.1로 연결합니다. 내장 Caddy 혹은 Nginx 서버가 해당 도메인으로 오는 요청을 localhost:8585로 리버스 프록시합니다. 또한 .servbay.demo 도메인을 사용하면 ServBay User CA가 SSL 인증서를 자동으로 발급/신뢰해 HTTPS로 안전하게 접근할 수 있습니다.
더 자세한 단계는 ServBay 공식 문서의 Node.js 개발 웹사이트 추가하기 (영문 문서 참고) 섹션을 참조하세요.
Koa.js 개발 웹사이트 접근
웹 브라우저에서 https://servbay-koa-dev.servbay.demo로 접속합니다.
올바르게 설정했다면 "Hello from ServBay Koa.js App!" 메시지를 확인하실 수 있습니다. 즉, ServBay 웹사이트 기능을 통해 로컬에서 동작하는 Koa.js 개발 서버에 성공적으로 접근한 셈입니다. app.js 파일 수정 후 Node.js 프로세스를 재시작하면 브라우저를 새로고침하여 변경 사항을 바로 확인할 수 있습니다.

프로덕션 버전(모의) 배포

실제 프로덕션 환경을 모의로 구축할 때에는 포트, 환경변수, 실행 방식 등이 달라질 수 있습니다. ServBay의 리버스 프록시 설정은 동일하게 적용됩니다.

Koa.js 프로덕션 서버 실행(모의)
별도의 터미널에서 기존 개발 서버를 중지한 뒤, 프로덕션 모드로 (예: 8586 포트, NODE_ENV=production 지정) 앱을 실행합니다:
bash
```
cd /Applications/ServBay/www/servbay-koa-app
PORT=8586 NODE_ENV=production node app.js
```
1
2
이렇게 하면 8586 포트에서 프로덕션 환경 Koa.js 인스턴스가 구동됩니다.
ServBay 웹사이트(Website) 리버스 프록시 설정(프로덕션 모의)
프로덕션 모의 환경용 새 사이트도 아래와 같이 추가합니다:
- ServBay 앱을 열고, 웹사이트(Website) 화면으로 이동
- 좌측 하단 + 버튼으로 새 사이트 추가
- 설정:
  - 이름(Name): ServBay Koa.js Prod Site
  - 도메인(Domain): servbay-koa-prod.servbay.demo (혹은 소유한 커스텀 도메인, Let's Encrypt 등 무료 SSL 발급 가능)
  - 타입(Type): 리버스 프록시(Reverse Proxy) 선택
  - IP 주소(IP Address): 127.0.0.1
  - 포트(Port): 8586 (Koa.js 프로덕션 포트)
  - 루트 디렉토리(Document Root): 빈칸 또는 프로젝트 경로
- 저장 및 변경 적용
.servbay.demo 도메인은 ServBay User CA 인증서를 계속 사용합니다. 커스텀 도메인 사용 시 ServBay의 ACME(예: Let's Encrypt) 기능으로 무료 SSL/TLS 인증서를 발급해 실제 프로덕션 환경까지 모의할 수 있습니다. 자세한 내용은 SSL로 사이트 보호하기 ServBay 문서를 참조하세요.
Koa.js 프로덕션 웹사이트 접근(모의)
브라우저에서 https://servbay-koa-prod.servbay.demo로 접속하면, 개발환경과 동일한 페이지가 출력되지만 이번에는 리버스 프록시를 통해 8586 포트로 전달된 Node.js 프로세스가 요청을 처리합니다.

데이터베이스 연결 방법

ServBay에는 MongoDB, Redis, MariaDB(MySQL 호환), PostgreSQL 등 주요 데이터베이스가 내장되어 있습니다. Koa.js 프로젝트에서 이들 데이터베이스를 연결하기 매우 쉽고, 모두 로컬(localhost)에서 동작하므로 기본값을 그대로 사용할 수 있습니다.

아래는 Node.js 드라이버로 ServBay의 데이터베이스에 접속하는 코드 예시입니다. ServBay **패키지(Packages)**에서 필요한 데이터베이스가 설치되고, 실행 중인지 확인하세요.

MongoDB 연결

프로젝트 디렉토리에서 MongoDB용 Node.js 드라이버(mongoose 또는 mongodb 등) 설치:

bash

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

그리고 app.js 또는 원하는 모듈에 아래 코드 추가:

javascript

// Mongoose로 MongoDB에 연결
const mongoose = require('mongoose');

// ServBay 기본 MongoDB는 인증 필요 없음, DB명은 자유롭게 지정 가능
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));

// 참고: 실제 앱에선 연결 코드를 초기화 로직에 넣고
// 연결 성공 후에 포트 리스닝을 시작하는 것이 일반적입니다.

ServBay MongoDB는 기본적으로 27017 포트에서 인증 없이 연결 가능합니다. 데이터베이스 이름은 직접 지정하고 존재하지 않으면 자동 생성됩니다.

Redis 연결

Node.js용 Redis 클라이언트 설치:

bash

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

Redis 서버 연결:

javascript

// redis 클라이언트로 Redis에 연결
const redis = require('redis');

// 기본적으로 localhost:6379에 연결
const client = redis.createClient({
  url: 'redis://localhost:6379' // ServBay 기본 Redis 포트는 6379
});

client.on('connect', () => {
  console.log('Connected to Redis');
});

client.on('error', (err) => {
  console.error('Redis connection error:', err);
});

// Redis 서버에 연결
client.connect();

// 참고: 실제 앱에서는 async/await로 client.connect() 완료 후에 Redis 작업을 합니다.

ServBay Redis는 기본 6379 포트에서 인증/비밀번호 없이 사용 가능합니다.

MariaDB(또는 MySQL) 연결

MariaDB는 MySQL 파생 프로젝트이므로 API가 거의 동일합니다. ServBay MariaDB 패키지를 MySQL처럼 사용할 수 있습니다.

Node.js MariaDB 드라이버 설치:

bash

cd /Applications/ServBay/www/servbay-koa-app
npm install mariadb # 또는 호환성이 더 뛰어난 mysql2 추천

mariadb 드라이버로 연결:

javascript

// mariadb 클라이언트로 MariaDB에 연결
const mariadb = require('mariadb');

// ServBay 기본 MariaDB root 비밀번호는 'password'
const pool = mariadb.createPool({
  host: 'localhost',
  user: 'root',
  password: 'password',
  database: 'servbay_koa_app', // DB 생성 여부 확인 및 명칭 조정
  connectionLimit: 5
});

pool.getConnection()
  .then(conn => {
    console.log("Connected to MariaDB");
    conn.release(); // 연결 해제(풀에 반환)
  })
  .catch(err => {
    console.error("MariaDB connection error:", err);
  });

// 참고: 연결 풀이 비동기 방식으로 동작합니다.

추천하는 mysql2 드라이버로 연결:

javascript

// mysql2 클라이언트로 MariaDB/MySQL에 연결 (프로미스 버전)
const mysql = require('mysql2/promise');

// ServBay 기본 MariaDB root 비밀번호는 'password'
const pool = mysql.createPool({
  host: 'localhost',
  user: 'root',
  password: 'password',
  database: 'servbay_koa_app', // DB 생성 필요
  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);
  });

// 참고: ServBay 기본 root 비밀번호는 ServBay GUI - DB 설정에서 확인/변경 가능합니다.
// 실제 프로젝트에서는 비밀번호를 코드에 직접 넣는 대신 환경 변수 사용을 권장합니다.

ServBay MariaDB는 기본적으로 3306 포트에서 실행됩니다. 기본 root 비밀번호는 ServBay DB 관리 화면을 통해 확인/변경 가능합니다. DB(servbay_koa_app)는 ServBay 혹은 DB관리 툴(TablePlus, DBeaver 등)로 수동 생성해야 할 수도 있습니다.

PostgreSQL 연결

Node.js용 PostgreSQL 드라이버 설치:

bash

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

PostgreSQL 서버 연결:

javascript

// pg 클라이언트로 PostgreSQL에 연결
const { Pool } = require('pg');

// ServBay 기본 PostgreSQL 사용자 'user' 비밀번호 'password'
const pool = new Pool({
  user: 'user',
  host: 'localhost',
  database: 'servbay_koa_app', // DB 생성 여부 확인
  password: 'password', // 기본 비밀번호
  port: 5432, // 기본 PostgreSQL 포트
});

pool.connect((err, client, done) => {
  if (err) {
    console.error('PostgreSQL connection error:', err);
    return;
  }
  console.log('Connected to PostgreSQL');
  client.release(); // 연결 해제(풀에 반환)
});

// 참고: 기본 사용자/비밀번호는 ServBay DB 설정에서 확인/수정 가능합니다.
// 실제 앱에서는 비밀번호 코딩 대신 환경 변수 사용을 권장합니다.

ServBay PostgreSQL은 기본적으로 5432 포트에서 동작하며, 기본 사용자/비밀번호는 ServBay DB 관리 화면을 통해 확인 가능합니다. 역시 DB(servbay_koa_app)는 수동 생성이 필요할 수 있습니다.

ServBay 데이터베이스 관리

직접 코드로 연결하는 것 외에도, 그래픽 기반 관리 툴에서 ServBay DB에 접근하여 관리할 수 있습니다. ServBay DB는 기본적으로 127.0.0.1 혹은 localhost에서 동작하므로, ServBay GUI에 표기된 포트와 기본 사용자/비밀번호로 쉽게 연결할 수 있습니다.

기본 비밀번호 확인/변경: ServBay 앱에서 데이터베이스 패키지 옆의 설정 아이콘을 클릭하여, 기본 사용자(root/MariaDB, user/PostgreSQL) 비밀번호를 확인/변경할 수 있습니다.
DB/사용자 생성: TablePlus, DBeaver, pgAdmin, MongoDB Compass 등 외부 클라이언트 툴로 ServBay DB에 접속해 SQL 등의 명령어나 그래픽UI로 새 DB, 사용자, 테이블을 관리할 수 있습니다.

주의 사항

포트 충돌: Koa.js 앱용 포트(예: 8585, 8586)가 OS의 다른 프로그램에서 사용 중이지 않은지 반드시 확인하세요.
ServBay 실행 상태: ServBay 앱과 Node.js 및 필요한 데이터베이스 패키지가 모두 실행 중이어야 합니다.
hosts 파일: ServBay가 hosts 파일을 자동 관리하지만, 도메인 문제 발생 시 /etc/hosts에 기록이 올바른지 점검하세요.
방화벽 설정: macOS 기본 방화벽이나 서드파티 방화벽이 ServBay 또는 Node.js 프로세스의 네트워크 연결을 막고 있지 않은지 확인하세요.
로그 확인: 문제 발생 시 ServBay 앱(log 탭)과 Node.js 프로세스(터미널)의 출력 로그를 체크해서 원인 진단에 활용하세요.

자주 묻는 질문 (FAQ)

Q: 왜 ServBay의 리버스 프록시로 Koa.js 프로젝트에 접근해야 하나요?
A: 리버스 프록시(ServBay 웹사이트 기능) 사용 시 여러 장점이 있습니다:
1. 생산 환경 모의: 커스텀 도메인(예: .servbay.demo 또는 자체 도메인) 사용으로 실제 웹사이트 접근 방식을 그대로 재현합니다.
2. SSL 지원: ServBay가 SSL 인증서(ServBay User CA 또는 Let's Encrypt)를 자동 발급/설정하여 개발 단계부터 HTTPS 테스트가 가능합니다.
3. 통합 관리: ServBay에서 모든 로컬 개발 사이트를 한 번에 관리 가능합니다.
4. 포트 숨김: 외부 브라우저는 80/443 등 표준 포트만 사용하고, 내부적으로 Node.js 고포트로 트래픽 전달 가능합니다.
Q: 리버스 프록시 없이 localhost:PORT로 직접 접근해도 되나요?
A: 네, 가능합니다. Koa.js 앱이 직접 한 포트(3000 등)에서 리스닝 중이라면 브라우저에서 http://localhost:PORT로 바로 접속해 개발/테스트 가능합니다. 다만, 이 방식은 커스텀 도메인, 자동 SSL, 웹사이트별 로그 관리 등 ServBay의 유용한 기능을 활용하지 못합니다. 실제 배포 환경에 더 가까운 개발을 원할 땐 ServBay 리버스 프록시 사용을 추천합니다.
Q: ServBay 기본 데이터베이스 비밀번호는 어디서 확인/변경하나요?
A: ServBay 앱의 데이터베이스 화면에서 각 DB 패키지 우측 설정(톱니바퀴) 아이콘을 클릭하면, 기본 사용자와 비밀번호 정보를 볼 수 있습니다. 그 자리에서 비밀번호 변경도 가능합니다. 보안상 가급적 기본 비밀번호는 교체하는 것이 좋습니다.

요약

이 문서의 안내대로 하면 macOS에서 ServBay를 활용해 Koa.js 개발 환경을 쉽게 구축할 수 있습니다. 기본적인 Koa.js 앱을 생성하고, ServBay의 웹사이트 기능으로 리버스 프록시 및 커스텀 도메인, HTTPS 접근을 설정 및 모의 배포까지 실습했습니다. 또한 ServBay 내장 데이터베이스(MongoDB, Redis, MariaDB, PostgreSQL) 연결 방법도 살펴보았습니다.

ServBay는 Node.js 개발자를 위한 통합적이고 관리가 편리한 로컬 개발 환경을 제공하므로, 환경 설정 부담 없이 개발에 집중할 수 있습니다. ServBay의 강력한 기능을 잘 활용하면 개발 효율성이 눈에 띄게 향상됩니다.

ServBay로 Koa.js 프로젝트 생성 및 실행하기 ​

Koa.js란 무엇인가요? ​

Koa.js의 주요 특징 ​

ServBay를 활용한 Koa.js 개발 환경 구축 ​

사전 준비 ​

Koa.js 프로젝트 생성 ​

개발 모드 진입 ​

프로덕션 버전(모의) 배포 ​

데이터베이스 연결 방법 ​

ServBay 데이터베이스 관리 ​

주의 사항 ​

자주 묻는 질문 (FAQ) ​

요약 ​

ServBay로 Koa.js 프로젝트 생성 및 실행하기

Koa.js란 무엇인가요?

Koa.js의 주요 특징

ServBay를 활용한 Koa.js 개발 환경 구축

사전 준비

Koa.js 프로젝트 생성

개발 모드 진입

프로덕션 버전(모의) 배포

데이터베이스 연결 방법

ServBay 데이터베이스 관리

주의 사항

자주 묻는 질문 (FAQ)

요약