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

ServBay는 macOS 전용 로컬 웹 개발 환경으로, Node.js 런타임과 다양한 데이터베이스 등, 개발자들이 자주 사용하는 여러 소프트웨어 패키지를 통합 제공합니다. 이 문서에서는 ServBay의 편리한 개발 환경을 활용해 Koa.js 프로젝트를 신속하게 생성하고, 실행 및 관리하는 방법을 안내합니다.

Koa.js란?

Koa.js는 Express.js 팀이 개발한 Node.js 기반의 차세대 웹 프레임워크입니다. Koa.js는 간결하면서도 표현력이 뛰어난 코드와 강력한 기능들로 유명하며, 웹 애플리케이션과 API를 구축하는 데 이상적인 선택지입니다. 특히 async/await 문법 등 최신 JavaScript 특징을 적극 활용해, 비동기 처리와 미들웨어 작성을 크게 단순화하며 코드를 더욱 명확하고 유지보수하기 쉽게 만듭니다.

Koa.js의 주요 특징

async/await 기반: 핵심 설계가 async/await에 맞춰져 있어, 비동기 흐름 제어가 직관적입니다.
경량화된 코어: Koa의 코어 라이브러리는 매우 작고 기본 기능만 포함하며, 확장 기능은 모듈화된 미들웨어로 제공됩니다.
강력한 미들웨어: 계단식(cascading) 미들웨어 구조를 채택해, 요청 처리 흐름이 명확하고 유연합니다.
웹에 집중: 웹 앱 및 API 개발에 집중하여, 불필요한 추가 기능은 제공하지 않습니다.

Koa.js를 사용하면 개발자는 고성능·유지보수가 쉬운 웹 서비스를 효율적으로 구축할 수 있습니다.

ServBay로 Koa.js 개발 환경 구축

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

사전 준비 사항

시작하기 전에 아래 준비를 완료해 주세요.

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

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

애플리케이션 진입 파일(app.js) 생성

프로젝트 루트(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}`);
});

이 코드는 두 개의 미들웨어로 구성된 Koa 기본 애플리케이션을 만듭니다. 첫 번째는 요청 시간과 경로를 기록하고, 두 번째는 루트 URL(/) 요청에 "Hello from ServBay Koa.js App!" 메시지로 답변합니다. 서버는 환경변수 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와 비슷한 메시지가 출력됩니다. 이 창을 열어둬야 서버가 계속 실행됩니다.
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 Address(아이피 주소): 127.0.0.1 (로컬 Node.js 프로세스)
  - Port(포트): 8585 (Koa.js 앱이 리스닝하는 포트)
  - Document Root(문서 루트): 리버스 프록시 유형에서는 중요하지 않으므로 비워두거나 프로젝트 경로(/Applications/ServBay/www/servbay-koa-app)를 입력해도 됩니다.
- 저장을 클릭하세요.
- 변경 사항 적용 메시지가 뜨면, 적용(Apply)을 클릭하면 됩니다.
설정이 완료되면, 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의 리버스 프록시 구성이 유용합니다.

운영 서버 실행(모의)
또 다른 터미널에서 이전 개발 서버를 중단한 뒤, 운영 환경을 시뮬레이션하기 위해 별도의 포트(예: 8586)과 환경 변수(NODE_ENV)를 지정해 실행합니다:
bash
```
cd /Applications/ServBay/www/servbay-koa-app
PORT=8586 NODE_ENV=production node app.js
```
1
2
이제 포트 8586에서 운영 환경 상태로 Koa.js 인스턴스가 실행됩니다.
ServBay Website(웹사이트) 리버스 프록시 설정(운영 시뮬레이션)
유사하게, 운영 환경을 시뮬레이션할 새 웹사이트도 ServBay에 추가합니다:
- ServBay 앱에서 Website(웹사이트) 메뉴로 이동합니다.
- 좌측 하단 + 버튼 클릭, 새 웹사이트 추가.
- 웹사이트 설정 입력:
  - Name(이름): ServBay Koa.js Prod Site
  - Domain(도메인): servbay-koa-prod.servbay.demo (직접 보유한 도메인 사용 시 ServBay의 ACME/Let's Encrypt로 무료 인증서 발급 가능)
  - Type(유형): Reverse Proxy(리버스 프록시)
  - 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로 웹사이트 보호하기 문서를 참고하세요.
Koa.js 운영(프로덕션) 웹사이트 접속(모의)
브라우저에서 https://servbay-koa-prod.servbay.demo로 접속하세요.
개발 환경과 동일한 화면이 보이지만, 이번에는 요청이 ServBay 리버스 프록시를 통해 포트 8586의 Node.js 프로세스로 전달되어 처리됩니다.

데이터베이스 연결

ServBay는 MongoDB, Redis, MariaDB(=MySQL 호환), PostgreSQL 등 다양한 주요 데이터베이스 시스템을 통합 제공합니다. Koa.js 프로젝트에서 이들 데이터베이스에 연결하는 방법도 매우 간단한데, 모두 로컬에서 실행되므로 localhost 기준으로 접근하면 됩니다(포트 및 초기 비밀번호 등은 ServBay GUI에서 확인).

아래는 ServBay에서 제공하는 데이터베이스들을 Node.js 드라이버로 연결하는 예시 코드들을 정리한 것입니다. 먼저 ServBay Packages(패키지) 화면에서 해당 데이터베이스가 설치되고 실행 중인지 확인하세요.

MongoDB 연결

우선, 프로젝트 디렉터리에서 Node.js용 MongoDB 드라이버(예: 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는 인증 불필요, 데이터베이스명은 자유 지정
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 연결

Redis Node.js 클라이언트 라이브러리 설치:

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()로 성공 시점 제어 필요

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의 기본 root 사용자 비밀번호는 '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로 연결:

javascript

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

// ServBay의 기본 root 비밀번호는 '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 비밀번호 및 기타 정보는 ServBay GUI의 DB 설정에서 확인·변경 가능
// 실제 프로젝트에서는 환경 변수 등으로 비밀번호 관리 권장

MariaDB는 기본적으로 3306 포트에서 실행됩니다. root 비밀번호 등 세부 정보는 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', // ServBay 기본 사용자
  host: 'localhost',
  database: 'servbay_koa_app', // 데이터베이스 생성 필요
  password: 'password', // ServBay 기본 비밀번호
  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 GUI의 DB 설정에서 확인 및 변경 가능
// 실제 프로젝트에서는 비밀번호 하드코딩 대신 환경 변수 사용 권장

ServBay에서 제공하는 PostgreSQL은 기본적으로 5432 포트에서 구동되며, 사용자명/비밀번호 등은 ServBay GUI에서 확인할 수 있습니다. 마찬가지로, 필요한 데이터베이스는 직접 생성해야 할 수 있습니다.

ServBay 데이터베이스 관리

코드에서 연결할 뿐만 아니라, 다양한 GUI 클라이언트 툴로도 ServBay의 데이터베이스 관리가 가능합니다. 기본적으로 데이터베이스는 127.0.0.1 또는 localhost에서 구동되며, ServBay GUI에 나타난 포트 및 초기 ID/비밀번호로 접속하면 됩니다.

기본 비밀번호 보기/변경: ServBay 앱의 해당 데이터베이스 패키지 오른쪽 톱니바퀴(설정) 아이콘을 눌러 기본 사용자(root 등)의 비밀번호를 확인/수정할 수 있습니다.
DB/사용자 생성: TablePlus, DBeaver, pgAdmin, MongoDB Compass 등 GUI 클라이언트로 ServBay DB에 접속해, SQL이나 GUI로 새 DB·사용자·테이블 등을 쉽게 만들 수 있습니다.

참고 및 주의사항

포트 충돌: Koa.js 앱 포트(예: 8585, 8586)가 시스템 내 다른 앱에서 이미 사용 중이지 않은지 확인하세요.
ServBay 상태: ServBay 앱 자체 및 필요한 Node.js/DB 패키지들이 실행 중인지 확인하세요.
hosts 파일: ServBay가 /etc/hosts 파일을 자동 관리하지만, 도메인 연결 문제가 있으면 해당 파일에 올바른 레코드가 있는지 확인하세요.
방화벽: macOS 내장 방화벽 또는 기타 써드파티 방화벽 설정이 ServBay나 Node.js 프로세스의 네트워크 접근을 차단하지 않는지 확인하세요.
로그 확인: 문제 발생 시 ServBay 앱 내 로그 탭과 Node.js 프로세스의 터미널 출력 로그를 참고하면 문제 해결에 도움이 됩니다.

자주 묻는 질문 (FAQ)

Q: 왜 ServBay의 리버스 프록시로 Koa.js 프로젝트에 접속해야 하나요?
A: 리버스 프록시(ServBay의 웹사이트 기능) 사용에는 다음과 같은 장점이 있습니다:
1. 운영 환경 시뮬레이션: localhost:PORT 대신 .servbay.demo나 본인 도메인 등의 맞춤 도메인 사용으로 실제 서비스 환경과 유사하게 접근할 수 있습니다.
2. SSL 지원: ServBay는 로컬 웹사이트에도 SSL 인증서를 자동 적용해, 개발 단계에서도 HTTPS 테스트가 가능합니다.
3. 집중 관리: 모든 개발 웹사이트를 ServBay에서 일괄 관리할 수 있어 편리합니다.
4. 포트 은폐: 외부 접속자 혹은 브라우저는 표준 포트(80/443)만 접속하면 되고, 내부적으로만 고포트로 프록시 처리되어 보안·편의성이 높습니다.
Q: 리버스 프록시 없이 그냥 localhost:PORT로 직접 접근해도 되나요?
A: 네, 가능합니다. Koa.js 앱이 특정 포트에서 직접 리스닝한다면, 브라우저를 통해 해당 주소로 접근해도 개발·테스트가 가능합니다. 다만 이 경우, ServBay의 맞춤 도메인, 자동 SSL 적용, 로그 관리 등 웹사이트 기능을 활용할 수 없습니다. 현실적인 운영 환경과 유사한 개발 환경을 원한다면 ServBay의 리버스 프록시 기능 사용을 권장합니다.
Q: ServBay 기본 DB 비밀번호는 무엇이고, 어떻게 변경하나요?
A: ServBay의 기본 데이터베이스 패스워드는 ServBay 앱 Database(데이터베이스) 화면에서 확인할 수 있습니다. 해당 DB 패키지의 설정 아이콘을 누르면 정보 창에서 초기 유저/비번을 확인하거나 변경할 수 있습니다. 보안 상 반드시 기본 비밀번호를 변경해 사용하는 것을 권장합니다.

정리

이 문서를 통해 macOS에서 ServBay로 Koa.js 개발 환경을 손쉽게 구축하는 방법을 익혀보았습니다. 기본 Koa.js 앱을 만들고, ServBay의 웹사이트 기능을 활용해 리버스 프록시 및 맞춤 도메인/HTTPS로 로컬 앱에 접근하는 방법, 다양한 데이터베이스 연결법까지 살펴보았습니다.

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)

정리