1.NestJS 배달 프로젝트 - Docker 환경에서 컨테이너 단위로 배포할 수 있도록 환경을 설정
1. 프로젝트 개요
NestJS 기반 배달 프로젝트는 여러 마이크로서비스로 구성되어 있습니다.
Auth Service: 인증 및 사용자 관리
Order Service: 주문 처리 및 상태 관리
Payment Service: 결제 처리 로직 담당
Gateway (API Gateway): 클라이언트 요청을 각 서비스로 라우팅
Database: 각 서비스별 독립적인 DB 운영 (PostgreSQL)
이제 이러한 서비스들을 Docker 환경에서 컨테이너 단위로 배포할 수 있도록 환경을 설정합니다.
2. Docker 환경 준비
(1) Docker 및 Docker Compose 설치
먼저 서버(또는 로컬 개발 환경)에 Docker와 Docker Compose를 설치합니다.
sudo apt update sudo apt install docker.io docker-compose -y
설치 확인:
docker -v docker-compose -v
(2) 프로젝트 디렉토리 구조
/배달프로젝트 ├── docker-compose.yml ├── gateway/ ├── auth-service/ ├── order-service/ ├── payment-service/ └── postgres/
각 서비스 폴더는 독립적인 NestJS 프로젝트로 구성되어 있으며, Dockerfile이 포함됩니다.
3. 각 서비스의 Dockerfile 작성
예시: Auth Service
# Auth Service Dockerfile FROM node:18-alpine WORKDIR /app COPY package*.json ./ RUN npm install --legacy-peer-deps COPY . . RUN npm run build EXPOSE 3001 CMD ["npm", "run", "start:prod"]
주요 포인트
Node 18 버전 사용 (경량 alpine 이미지)
NestJS 빌드 후 start:prod 명령으로 실행
포트 3001을 외부로 노출
4. docker-compose.prod.yml 구성
# ✅ 로컬 환경용 Docker buildx 빌드 및 푸시 명령어 # (GitHub Actions이 아닌 환경에서는 github.sha 변수를 제거해야 함) ```bash docker buildx build --platform linux/amd64,linux/arm64 \ -t DockerHubID/fc-nestjs-gateway:latest \ -f ./apps/gateway/Dockerfile \ --target production \ --push . docker buildx build --platform linux/amd64,linux/arm64 \ -t DockerHubID/fc-nestjs-notification:latest \ -f ./apps/notification/Dockerfile \ --target production \ --push . docker buildx build --platform linux/amd64,linux/arm64 \ -t DockerHubID/fc-nestjs-order:latest \ -f ./apps/order/Dockerfile \ --target production \ --push . docker buildx build --platform linux/amd64,linux/arm64 \ -t DockerHubID/fc-nestjs-payment:latest \ -f ./apps/payment/Dockerfile \ --target production \ --push . docker buildx build --platform linux/amd64,linux/arm64 \ -t DockerHubID/fc-nestjs-product:latest \ -f ./apps/product/Dockerfile \ --target production \ --push . docker buildx build --platform linux/amd64,linux/arm64 \ -t DockerHubID/fc-nestjs-user:latest \ -f ./apps/user/Dockerfile \ --target production \ --push . ```
모든 서비스를 컨테이너 단위로 묶어 관리하기 위해 docker-compose.prod.yml 을 작성합니다.
# docker-compose -f docker-compose.prod.yml build --no-cache
# docker-compose -f docker-compose.prod.yml up --build
services:
gateway:
build:
context: .
dockerfile: ./apps/gateway/Dockerfile
image: DockerHubID/fc-nestjs-gateway:latest
env_file:
- ./apps/gateway/.env.production
ports:
- "3000:3000"
user:
build:
context: .
dockerfile: ./apps/user/Dockerfile
image: DockerHubID/fc-nestjs-user:latest
env_file:
- ./apps/user/.env.production
product:
build:
context: .
dockerfile: ./apps/product/Dockerfile
image: DockerHubID/fc-nestjs-product:latest
env_file:
- ./apps/product/.env.production
order:
build:
context: .
dockerfile: ./apps/order/Dockerfile
image: DockerHubID/fc-nestjs-order:latest
env_file:
- ./apps/order/.env.production
payment:
build:
context: .
dockerfile: ./apps/payment/Dockerfile
image: DockerHubID/fc-nestjs-payment:latest
env_file:
- ./apps/payment/.env.production
notification:
build:
context: .
dockerfile: ./apps/notification/Dockerfile
image: DockerHubID/fc-nestjs-notification:latest
env_file:
- ./apps/notification/.env.production
5. 환경 변수 관리 (.env)
각 서비스 내부에서 DB 연결 및 API 키를 안전하게 관리하기 위해 .env 파일을 작성합니다.
DATABASE_URL=postgres://postgres:1234@postgres:5432/auth JWT_SECRET=mysecretkey
.gitignore에 .env 파일을 반드시 추가합니다.
6. 빌드 및 실행
모든 설정이 완료되면 아래 명령으로 컨테이너를 빌드 및 실행합니다.
```bash docker compose down -v docker compose build --no-cache docker compose up ``` ```bash docker-compose -f docker-compose.prod.yml up --build ```
정상적으로 실행되면 다음과 같은 로그를 확인할 수 있습니다.
✅ Auth Service running on port 3001 ✅ Order Service running on port 3002 ✅ Payment Service running on port 3003 ✅ Gateway running on port 3000 ✅ PostgreSQL started
7. 컨테이너 관리 명령어 요약
명령어설명
docker ps실행 중인 컨테이너 목록 확인
docker-compose down모든 컨테이너 중지 및 제거
docker logs [컨테이너명]로그 확인
docker exec -it [컨테이너명] /bin/sh컨테이너 내부 접속
2.NestJS 배달 프로젝트 - Docker Hub 이미지 기반 Database 연동 및 테스트하기
1. 개요
앞선 단계 에서는 마이크로서비스 구조를 Docker 환경에서 배포하기 위한 기본 환경을 구성했습니다.
이번 단계에서는 Docker Hub에서 이미 빌드된 이미지를 가져와 실행하고, Database 연결 테스트를 진행합니다.
???? 핵심 포인트
Docker Hub에서 이미지 pull
.env 환경 변수로 DB 연결 설정
PostgreSQL 연동 확인 및 API 테스트
2. Docker Hub에서 이미지 가져오기
먼저, 강의에서 제공한 Docker 이미지를 Docker Hub에서 가져옵니다.
docker pull username/auth-service:latest docker pull username/order-service:latest docker pull username/payment-service:latest docker pull username/gateway:latest
???? 실제 강의에서는 username 대신 본인의 Docker Hub 계정을 사용합니다.
모든 이미지가 정상적으로 내려받아졌는지 확인합니다.
docker images
3. docker-compose.prod.yml
이제 로컬 빌드가 아닌, Docker Hub에 업로드된 최신 버전 이미지를 바로 실행할 수 있습니다.
4. 환경 변수 설정 (.env)
각 서비스가 PostgreSQL과 정상적으로 통신할 수 있도록 .env 파일을 구성합니다.
DATABASE_URL=postgres://postgres:1234@postgres:5432/delivery NODE_ENV=production JWT_SECRET=mysecret
.env 파일은 각 서비스 내에서도 동일하게 사용되며, TypeORM 설정 시 자동으로 참조됩니다.
5. 컨테이너 실행
모든 준비가 완료되면, 다음 명령으로 컨테이너를 실행합니다.
docker-compose up -d
컨테이너 상태 확인:
docker ps
정상적으로 실행되면 아래와 유사한 로그가 출력됩니다.
auth_service running 0.0.0.0:3001 → 3001/tcp order_service running 0.0.0.0:3002 → 3002/tcp payment_service running 0.0.0.0:3003 → 3003/tcp gateway running 0.0.0.0:3000 → 3000/tcp postgres running 0.0.0.0:5432 → 5432/tcp
6. Database 연결 테스트
이제 실제로 데이터베이스 연동이 잘 이루어졌는지 확인합니다.
(1) DB 컨테이너 접속
docker exec -it delivery_db psql -U postgres
(2) 데이터베이스 확인
\l -- 데이터베이스 목록 확인 \c delivery -- 배달 프로젝트 DB 접속 \dt -- 테이블 목록 확인
(3) 데이터 삽입 및 조회 테스트
INSERT INTO users (name, email) VALUES ('홍길동', 'test@test.com');
SELECT * FROM users;
NestJS 서비스 로그에서 데이터베이스 연결 성공 메시지를 확인할 수 있습니다.
Database connected successfully ✅ Running migrations...
7. API 테스트
각 서비스가 정상적으로 DB와 연동되었는지 Postman 또는 curl로 테스트합니다.
예시: Auth Service 사용자 등록
curl -X POST http://localhost:3001/auth/register \
-H 'Content-Type: application/json' \
-d '{"email":"test@test.com","password":"1234"}'
정상 응답:
{
"message": "User registered successfully",
"user": {
"email": "test@test.com"
}
}
8. 문제 해결 체크리스트
문제원인해결 방법
DB 연결 오류DATABASE_URL 오타.env 파일 경로 및 철자 확인
컨테이너 종료됨포트 충돌 또는 환경 변수 누락docker logs [컨테이너명]으로 로그 확인
API 요청 시 500 에러DB 마이그레이션 미적용npm run migration:run 명령으로 해결
3. Docker 배포 환경 구성 및 Health Check URL 만들기
실제 Docker 배포 환경을 구축하고, 서비스 상태를 확인할 수 있는 Health Check API를 구현합니다. 이 과정은 배포 후 서버가 정상적으로 작동 중인지 확인하는 데 매우 중요한 부분입니다.
1. Health Check 모듈 생성
NestJS에서는 CLI 명령어를 통해 새로운 모듈을 쉽게 생성할 수 있습니다.
nest g module
✅ 실행 시 다음과 같은 선택지를 입력합니다:
Which project would you like to generate to? → gateway
What name would you like to use for the module? → health
Nest CLI는 아래와 같이 새로운 파일을 생성합니다:
CREATE apps/gateway/src/health/health.module.ts (83 bytes) UPDATE apps/gateway/src/app.module.ts
이제 gateway 프로젝트 안에 health 폴더가 추가되었으며, HealthModule이 자동으로 app.module.ts에 등록됩니다.
2. Health Controller 생성
다음으로 health.controller.ts 파일을 작성하여 /health 엔드포인트를 만들겠습니다.
import { Controller, Get } from '@nestjs/common';
@Controller('health')
export class HealthController {
@Get()
checkHealth() {
return true;
}
}
이 컨트롤러는 단순히 서버의 정상 작동 여부를 boolean 값(true) 로 반환합니다.
???? 실제 서비스에서는 데이터베이스 연결 여부, 마이크로서비스 간 통신 상태 등을 함께 검사하도록 확장할 수 있습니다.
3. Health Module 구성
이제 위에서 작성한 컨트롤러를 모듈에 등록합니다.
import { Module } from '@nestjs/common';
import { HealthController } from './health.controller';
@Module({
controllers: [HealthController],
})
export class HealthModule {}
controllers 배열에 HealthController를 등록하면 NestJS가 /health 경로를 자동으로 인식합니다.
4. 서버 실행 및 테스트
gateway 애플리케이션을 실행한 뒤, 브라우저나 Postman을 통해 아래 URL로 접근합니다.
GET http://localhost:3000/health
정상적으로 작동하면 다음과 같은 응답이 나타납니다:
true
???? 이 엔드포인트는 Docker, Kubernetes, AWS Load Balancer 등에서 헬스체크용 URL 로 활용될 수 있습니다.
5. Docker 환경에서의 활용
Docker나 클라우드 환경에서는 HEALTHCHECK 지시어를 이용하여 컨테이너의 상태를 감시할 수 있습니다.
예를 들어, Dockerfile에 다음을 추가합니다:
HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \ CMD curl -f http://localhost:3000/health || exit 1
이 설정은 30초마다 /health URL 을 호출하고, 실패 시 컨테이너를 비정상 상태(UNHEALTHY) 로 표시합니다.
⚙️ 이는 서비스 장애 감지 및 자동 재시작을 위한 핵심 설정입니다.
6. 정리
항목설명
모듈 생성nest g module health
컨트롤러 생성/health API 작성
응답 내용true (서버 정상 작동)
Docker 연동HEALTHCHECK 설정 추가
✅ 결과 요약
HealthModule과 HealthController를 통해 API 게이트웨이의 헬스체크 엔드포인트 구현 완료.
Docker 및 클라우드 배포 환경에서 자동 상태 감지 가능.
향후 DB 연결, Redis, gRPC 마이크로서비스 상태 점검 로직으로 확장 가능.
댓글 ( 0)
댓글 남기기