macOS에서 ServBay로 NestJS 프로젝트 생성 및 실행하기

NestJS는 효율적이고 확장성이 뛰어난 Node.js 서버 사이드 애플리케이션을 구축하기 위한 점진적(Node.js) 프레임워크입니다. TypeScript로 작성되었으며, Angular에서 영감을 받아 모듈 기반 아키텍처와 의존성 주입(DI) 패턴을 채택했습니다. NestJS는 개발자가 유지보수와 테스트가 용이하며, 높은 결합도를 피하는 복잡한 애플리케이션을 쉽게 개발할 수 있도록 강력한 도구와 기능을 제공합니다.

NestJS의 주요 특징과 장점

• 모듈형 아키텍처: 코드를 모듈별로 구성하여 애플리케이션의 구조화, 가독성, 유지보수를 탁월하게 지원합니다.
• 의존성 주입(DI): 간편하면서도 강력한 DI 시스템으로 코드의 테스트 용이성과 유지보수성을 크게 향상시킵니다.
• TypeScript 활용: TypeScript의 정적 타입 검사, 인터페이스, 최신 JavaScript 기능을 최대한 활용해 개발 효율성과 코드 품질, 런타임 오류를 최소화합니다.
• 풍부한 데코레이터: 데코레이터(Decorators)를 사용하여 컨트롤러, 서비스, 모듈 등을 선언적으로 정의해 코드가 간결하고 명확해집니다.
• 활발한 생태계: 많은 커뮤니티 사용자, 다양한 서드파티 모듈과 플러그인 지원으로 TypeORM, Mongoose, GraphQL, WebSockets, 캐시, 유효성 검사 등과 손쉽게 연동할 수 있습니다.
• 표준 기반: Express 또는 Fastify 등 검증된 HTTP 서버 프레임워크 위에서 구축되어 뛰어난 호환성과 성능을 제공합니다.

NestJS를 사용하면 개발자는 SOLID 원칙, 디자인 패턴 등 백엔드 개발의 베스트 프랙티스를 적용하여 고성능·기업형 웹앱, API 서비스, 마이크로서비스 등을 빠르게 구축할 수 있습니다.

ServBay로 NestJS 프로젝트 생성 및 실행

ServBay는 macOS 환경에서 다양한 버전의 Node.js와 주요 데이터베이스, 웹 서버를 내장한 강력한 로컬 웹 개발 통합 플랫폼입니다. 이 가이드에서는 ServBay의 Node.js 환경과 ‘웹사이트’ 기능을 이용해 NestJS 프로젝트를 만들고, 실행하며, 리버스 프록시 도메인 연결까지 설정합니다.

사전 준비

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

1. ServBay 설치: macOS에 ServBay를 정상 설치 완료했는지 확인합니다.
2. Node.js 패키지 활성화: ServBay 컨트롤 패널 ‘패키지’(Packages) 탭에서 원하는 Node.js 버전을 선택해 설치 및 활성화하세요. Node.js 미설정 시 ServBay Node.js 사용 가이드를 참고하세요.

NestJS 프로젝트 생성

1. NestJS CLI 전역 설치

   터미널을 열고, npm(보통 Node.js에 기본 포함)으로 NestJS CLI를 전역 설치합니다. NestJS CLI는 프로젝트 초기화·개발·유지관리를 위한 강력한 도구입니다.

   npm install -g @nestjs/cli

2. 프로젝트 초기화

   ServBay의 기본 사이트 루트 디렉토리인 /Applications/ServBay/www로 이동하세요. 이 디렉토리에 프로젝트를 생성하면 이후 사이트 설정이 수월합니다. 그리고 NestJS CLI로 새 프로젝트를 만드세요:

   cd /Applications/ServBay/www
   nest new servbay-nest-app

   명령 실행 후 CLI 안내에 따라 프로젝트 생성 및 패키지 매니저를 선택합니다(npm, yarn 또는 pnpm). 일관성을 위해 npm 권장. /Applications/ServBay/www/servbay-nest-app 폴더에 프로젝트가 생성됩니다.

3. 프로젝트 의존성 설치

   새 프로젝트 폴더 servbay-nest-app로 이동하여 의존 패키지를 설치하세요:

   cd servbay-nest-app
   npm install

   nest new가 이미 npm install을 실행했지만, 의존성 최신화 차원에서 한 번 더 실행해주는 것이 안전합니다.

NestJS 프로젝트 응답 커스터마이즈 (선택 사항)

NestJS 프로젝트가 정상 구동되고 ServBay로 접근 가능한지 테스트해보기 위해, 기본 루트 라우트의 응답을 변경해봅니다.

1. src/app.controller.ts 파일 수정

   선호하는 에디터로 src/app.controller.ts 파일을 열고, 아래처럼 내용을 수정해 / 경로 접근 시 "Hello ServBay!"가 반환되도록 합니다:

   import { Controller, Get } from '@nestjs/common';
   import { AppService } from './app.service'; // AppService가 있는 경우
   
   @Controller()
   export class AppController {
     constructor(private readonly appService: AppService) {} // AppService를 사용하는 경우
   
     @Get()
     getHello(): string {
       // return this.appService.getHello(); // AppService 사용시
       return 'Hello ServBay!'; // 문자열 직접 반환
     }
   }

   이 코드는 HTTP GET 요청에 대해 루트 경로(/)에서 "Hello ServBay!"라는 문자열을 반환하는 간단한 컨트롤러를 정의합니다.

개발 모드에서 NestJS 실행 및 ServBay로 접근

NestJS 앱은 개발모드에서 내장 서버로 실행되어 특정 포트를 리스닝합니다. ServBay의 ‘웹사이트’ 기능은 리버스 프록시를 통해 커스텀 도메인을 해당 NestJS 프로세스 포트로 연결할 수 있습니다.

1. 개발 서버 실행

   프로젝트 루트 /Applications/ServBay/www/servbay-nest-app에서 다음 명령어로 NestJS 개발 서버를 실행합니다. 예시로 8585 포트를 사용합니다.

   cd /Applications/ServBay/www/servbay-nest-app
   PORT=8585 npm run start:dev

   npm run start:dev는 NestJS의 TypeScript 코드를 ts-node로 실행 및 파일 감지를 통해 코드 수정 시 자동 재시작을 합니다. 서버가 localhost:8585에서 구동됩니다.

2. ServBay 웹사이트 리버스 프록시 설정

   ServBay 컨트롤 패널에서 ‘웹사이트’(Websites) 탭으로 이동, 추가 버튼(+ 등)을 클릭해 새 사이트를 생성합니다:

   • 이름(Name): 예) My first NestJS dev site
   • 도메인(Domains): 예) servbay-nest-test.dev (ServBay는 .dev 도메인 등을 자동으로 로컬로 연결하므로 hosts 파일 편집 필요 없음)
   • 유형(Type): 리버스 프록시(Reverse Proxy) 선택
   • IP 주소(IP Address): 일반적으로 127.0.0.1
   • 포트(Port): NestJS가 리스닝하는 8585 입력

   설정 후 저장하면 ServBay가 자동으로 웹 서버(Caddy 또는 Nginx) 설정을 갱신합니다. 자세한 사이트 설정은 ServBay 웹사이트 추가 가이드를 참고하세요.

3. 개발용 사이트 접속

   웹 브라우저에서 https://servbay-nest-test.dev로 접속하세요.

   참고:

   • ServBay는 로컬 사이트에 무료 SSL 인증서(ServBay User CA 서명)를 기본 제공하므로 https로 안전하게 접속할 수 있습니다. 인증서 경고가 나오면 ServBay User CA 인증서를 신뢰해야 할 수 있습니다. 자세한 내용은 SSL로 웹사이트 보호 가이드를 참고하세요.
   • NestJS 개발 서버(PORT=8585 npm run start:dev)가 실행 중이어야 하며, 중단되면 도메인 접근이 불가합니다.

배포(프로덕션) 모드로 빌드 및 ServBay로 접근

NestJS 앱을 실제 운영환경(혹은 운영 환경 시뮬레이션)으로 배포하기 전에는 대부분 빌드 과정을 거치게 됩니다.

1. 프로덕션 빌드

   프로젝트 루트 /Applications/ServBay/www/servbay-nest-app에서 다음 명령어로 빌드합니다:

   cd /Applications/ServBay/www/servbay-nest-app
   npm run build

   npm run build는 TypeScript 코드를 dist 폴더에 자바스크립트로 컴파일합니다.

2. 프로덕션 서버 실행

   빌드 완료 후, 다음 명령어로 빌드된 NestJS 앱을 구동합니다. 예시로 포트는 8586 사용, 환경변수로 NODE_ENV=production 지정:

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

   운영 모드에서는 핫리로드, 파일 감지 등이 비활성화됩니다.

3. ServBay 웹사이트 리버스 프록시 설정

   다시 ServBay ‘웹사이트’ 탭으로 이동, 운영용 사이트를 새로 추가 또는 수정합니다:

   • 이름(Name): 예) My first NestJS production site
   • 도메인(Domains): 예) servbay-nest-test.prod
   • 유형(Type): 리버스 프록시(Reverse Proxy)
   • IP 주소(IP Address): 127.0.0.1
   • 포트(Port): 8586 (프로덕션 서버와 동일)

   설정 저장.

4. 운영용 사이트 접속

   브라우저에서 https://servbay-nest-test.prod로 접속하여 운영 모드 NestJS 앱을 확인하세요. 이때도 SSL 암호화로 접속됩니다.

ServBay 내장 데이터베이스 연결

ServBay는 MariaDB(MySQL 호환), PostgreSQL, MongoDB, Redis 등 여러 DB를 내장 지원합니다. NestJS 개발 시 손쉽게 이 DB들로 연결할 수 있습니다.

중요: DB 연결 전 ServBay 컨트롤 패널 ‘패키지’(Packages) 탭에서 해당 DB 패키지가 활성화되어 있는지 반드시 확인하세요. DB의 기본 포트, 사용자명, 비밀번호는 ServBay 패널 또는 문서에서 확인 가능하며, 운영 환경에서는 기본 비밀번호 변경 및 전용 사용자 생성이 강력히 권장됩니다.

다음은 NestJS에서 ServBay 데이터베이스와 주로 사용되는 ORM/라이브러리의 코드 샘플입니다. 보통 앱의 루트 모듈(AppModule) 또는 별도 DB 모듈에 구성합니다.

1. MongoDB 연결

   @nestjs/mongoose 모듈로 MongoDB에 연결합니다. 먼저 패키지를 설치하세요:

   npm install @nestjs/mongoose mongoose

   그리고 NestJS 모듈에 MongooseModule을 설정합니다:

   import { Module } from '@nestjs/common';
   import { MongooseModule } from '@nestjs/mongoose';
   // ... 기타 import
   
   @Module({
     imports: [
       MongooseModule.forRoot('mongodb://localhost:27017/servbay-nest-app'), // 기본 포트 27017
       // ... 기타 모듈
     ],
     controllers: [], // ...
     providers: [], // ...
   })
   export class AppModule {}

   ServBay 기본 MongoDB 접속 문자열은 mongodb://localhost:27017/입니다. 필요시 MongoDB Compass 또는 mongosh 등 클라이언트로 localhost:27017에 접속해 servbay-nest-app 데이터베이스를 생성하세요.

2. Redis 연결

   @nestjs/redis 모듈로 Redis에 연결합니다. 먼저 패키지 설치:

   npm install @nestjs/redis redis @types/redis

   NestJS 모듈에 RedisModule 설정:

   import { Module } from '@nestjs/common';
   import { RedisModule } from '@nestjs/redis';
   // ... 기타 import
   
   @Module({
     imports: [
       RedisModule.forRoot({
         url: 'redis://localhost:6379', // 기본 포트 6379
       }),
       // ... 기타 모듈
     ],
     controllers: [], // ...
     providers: [], // ...
   })
   export class AppModule {}

   ServBay 기본 Redis 서버 주소는 localhost:6379입니다.

3. MariaDB(MySQL 호환) 연결

   @nestjs/typeorm 모듈로 MariaDB에 연결합니다. ServBay는 MariaDB, MySQL 패키지를 동시에 지원하며, 둘 다 MySQL 프로토콜을 사용하므로 mysql 또는 mariadb 타입 모두 연결 가능합니다. 우선 패키지 설치:

   npm install @nestjs/typeorm mysql2 typeorm

   NestJS 모듈에 TypeOrmModule 구성:

   import { Module } from '@nestjs/common';
   import { TypeOrmModule } from '@nestjs/typeorm';
   // ... 기타 import
   
   @Module({
     imports: [
       TypeOrmModule.forRoot({
         type: 'mariadb', // 또는 'mysql'
         host: 'localhost',
         port: 3306, // 기본 포트 3306
         username: 'root', // ServBay MariaDB/MySQL 기본 사용자
         password: 'password', // ServBay MariaDB/MySQL 기본 비번
         database: 'servbay_nest_app', // 데이터베이스 사전 생성 필요
         entities: [], // 엔티티 클래스 배열
         synchronize: true, // 개발 환경만 true, 운영 환경 주의
       }),
       // ... 기타 모듈
     ],
     controllers: [], // ...
     providers: [], // ...
   })
   export class AppModule {}

   참고: ServBay MariaDB/MySQL의 기본 root 비밀번호는 password입니다. TablePlus, DBeaver, MySQL CLI 등 DB 클라이언트로 localhost:3306에 접속해 root/password로 로그인, servbay_nest_app 데이터베이스를 생성해 주세요. 운영환경에서는 꼭 root 비밀번호 변경, 최소권한의 별도 사용자 생성이 요구됩니다.

4. PostgreSQL 연결

   @nestjs/typeorm으로 PostgreSQL 연결. 필요 패키지 설치:

   npm install @nestjs/typeorm pg typeorm

   모듈에 TypeOrmModule 구성:

   import { Module } from '@nestjs/common';
   import { TypeOrmModule } from '@nestjs/typeorm';
   // ... 기타 import
   
   @Module({
     imports: [
       TypeOrmModule.forRoot({
         type: 'postgres',
         host: 'localhost',
         port: 5432, // 기본 포트 5432
         username: 'servbay', // ServBay PostgreSQL 기본 계정(확인 필요)
         password: 'password', // ServBay PostgreSQL 기본 비번(확인 필요)
         database: 'servbay_nest_app', // 데이터베이스 사전 생성 필요
         entities: [], // 엔티티 클래스 배열
         synchronize: true, // 개발 환경만 true, 운영 환경 주의
       }),
       // ... 기타 모듈
     ],
     controllers: [], // ...
     providers: [], // ...
   })
   export class AppModule {}

   참고: 버전별로 ServBay PostgreSQL의 기본 사용자명/비밀번호가 다를 수 있습니다. 보통 servbay 또는 postgres일 수 있으니 ServBay 컨트롤 패널이나 문서에서 비밀번호와 사용자명을 확인하세요. PostgreSQL 클라이언트로 localhost:5432에 접속, 데이터베이스 및 필요시 전용 계정을 생성하세요. 운영환경에서는 반드시 기본 계정 비밀번호를 변경하세요.

마치며

이 가이드에서는 macOS에서 ServBay를 활용해 NestJS 프로젝트를 손쉽게 생성, 실행, 접근하는 방법을 알아보았습니다. ServBay의 Node.js 통합환경, 간편한 사이트/리버스 프록시 관리, 그리고 내장 DB 연결은 NestJS의 로컬 개발 및 테스트를 매우 간소화해줍니다. 개발·운영 모드 전환, 커스텀 도메인·HTTPS 지원, 강력한 데이터베이스 연동까지, ServBay로 안전하고 효과적인 NestJS 개발을 시작해보세요.