블로그로 돌아가기

☁️ NestJS + Next.js ERP 시스템 개발일지 #6: Amazon Lightsail을 활용한 클라우드 배포 완전 가이드

🎯 프로젝트 개요

NestJS + Next.js로 구성된 ERP 시스템을 Amazon Lightsail 클라우드 서버에 배포하는 과정에서 발생한 다양한 문제들과 해결 과정을 정리했습니다. 특히 Docker 컨테이너화, Nginx 리버스 프록시 설정, SSL 인증서 적용, CORS 설정 등 실제 프로덕션 환경에서 마주치는 문제들을 단계별로 해결해나갔습니다.

📊 프로젝트 개요

이번 프로젝트에서는 NestJS + Next.js로 구성된 ERP 시스템을 Amazon Lightsail 클라우드 서버에 배포하는 과정에서 발생한 다양한 문제들과 해결 과정을 정리했습니다. 특히 Docker 컨테이너화, Nginx 리버스 프록시 설정, SSL 인증서 적용, CORS 설정 등 실제 프로덕션 환경에서 마주치는 문제들을 단계별로 해결해나갔습니다.

11
해결한 주요 문제들
3
자동화 스크립트
5
Docker 컨테이너

💡 중요한 점

기능 구현이 완벽하지 않은 상태에서도 클라우드 배포 환경을 먼저 구축해놓는 것이 개발 효율성과 지속적인 배포(CI/CD) 측면에서 매우 유용합니다.

🏗️ 프로젝트 구조

백엔드: NestJS + TypeORM + PostgreSQL + Redis
프론트엔드: Next.js + React + Shadcn UI
인프라: Docker + Docker Compose + Nginx + Let's Encrypt SSL
클라우드: Amazon Lightsail (Ubuntu 22.04 LTS)

🚀 초기 환경 설정 및 문제

1.1 Amazon Lightsail 서버 설정

Amazon Lightsail에서 Ubuntu 22.04 LTS 인스턴스를 생성한 후, Bitnami 스택이 기본적으로 설치되어 있는 환경에서 작업을 시작했습니다.

서버 접속

# 서버 접속
ssh -i your-key.pem bitnami@your-server-ip

1.2 Git 클론 및 브랜치 설정

프로젝트 클론

# 프로젝트 클론
git clone https://github.com/username/intu_erp.git
cd intu_erp

# 클라우드 배포용 브랜치 생성
git checkout -b test

🐳 Docker 환경 구축 과정

2.1 Docker 권한 문제 해결

문제 상황

  • PermissionError: [Errno 13] Permission denied 오류 발생
  • Docker 명령어 실행 시 권한 부족

원인 분석

  • Bitnami 환경에서 Docker 소켓 권한 문제
  • 현재 사용자가 docker 그룹에 속하지 않음

해결 방법 - fix-docker-permissions.sh

#!/bin/bash
echo "🔧 Docker 권한 문제 해결 스크립트 시작..."

# 현재 사용자를 docker 그룹에 추가
sudo usermod -aG docker $USER

# Docker 서비스 시작 및 활성화
sudo systemctl start docker
sudo systemctl enable docker

# Docker 소켓 권한 수정
sudo chmod 666 /var/run/docker.sock

echo "✅ Docker 권한 설정 완료."
echo "⚠️  변경사항을 적용하려면 새 터미널 세션을 시작하거나 'newgrp docker' 명령어를 실행해야 합니다."
결과: Docker 권한 문제 해결 및 정상 실행 가능

2.2 포트 충돌 문제 해결

문제 상황

  • Redis, PostgreSQL, Nginx 등이 이미 사용 중인 포트로 인한 충돌
  • Docker 컨테이너 실행 시 포트 바인딩 실패

원인 분석

  • Bitnami 스택의 기본 서비스들이 80, 443, 5432, 6379 포트 사용
  • 기존 서비스와 Docker 컨테이너 간의 포트 충돌

해결 방법 - force-fix-ports.sh

#!/bin/bash
echo "🚨 강력한 포트 충돌 해결 스크립트 시작..."

# 주요 서비스 중지
sudo systemctl stop redis postgresql mysql apache2 httpd nginx

# 모든 Docker 컨테이너 중지 및 제거
docker-compose down --volumes --remove-orphans
docker rm -f $(docker ps -aq)
docker system prune -a -f --volumes

# 특정 포트 사용 프로세스 강제 종료
PORTS=(80 443 3000 3001 5432 6379)
for PORT in "${PORTS[@]}"; do
    PIDS=$(sudo fuser -n tcp $PORT 2>/dev/null)
    if [ -n "$PIDS" ]; then
        sudo kill -9 $PIDS 2>/dev/null || true
    fi
done

echo "🎉 강력한 포트 충돌 해결 완료!"
결과: 모든 포트 충돌 해결 및 Docker 컨테이너 정상 실행

⚙️ Dockerfile 최적화 과정

3.1 백엔드 Dockerfile 문제

문제 상황

  • sh: nest: not found 오류 발생
  • Error: Cannot find module '/app/dist/main' 오류

원인 분석

  • 개발 의존성 누락으로 인한 빌드 실패
  • 프로덕션 모드 실행 시 빌드 파일 경로 문제

해결 과정

# 초기 Dockerfile (문제 있음)
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production  # 개발 의존성 누락
COPY . .
RUN npm run build  # nest CLI 없어서 실패
CMD ["npm", "run", "start:prod"]

# 최종 Dockerfile (해결됨)
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci  # 모든 의존성 설치
COPY . .
RUN npm run build
RUN ls -la dist/  # 빌드 확인
EXPOSE 3001
CMD ["npm", "run", "start:prod"]
결과: 백엔드 컨테이너 정상 빌드 및 실행

3.2 프론트엔드 Dockerfile 문제

문제 상황

  • Could not find a production build in the '.next' directory 오류
  • Next.js 프로덕션 빌드 실패

원인 분석

  • Next.js 프로덕션 빌드가 제대로 생성되지 않음
  • 빌드 과정에서 오류 발생

해결 방법

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
RUN ls -la .next/  # 빌드 확인
EXPOSE 3000
CMD ["npm", "start"]
결과: 프론트엔드 컨테이너 정상 빌드 및 실행

🗄️ 데이터베이스 연결 문제

4.1 PostgreSQL 비밀번호 불일치

문제 상황

  • password authentication failed for user "postgres" 오류
  • 데이터베이스 연결 실패

원인 분석

  • PostgreSQL 컨테이너: POSTGRES_PASSWORD=password
  • 백엔드 컨테이너: DB_PASSWORD=your_secure_password

해결 방법

# .env 파일 통일
cat > .env << 'EOF'
DATABASE_URL="postgresql://postgres:password@postgres:5432/intu_erp"
POSTGRES_PASSWORD=password
DB_PASSWORD=password
# ... 기타 설정
EOF
결과: 데이터베이스 연결 성공

4.2 데이터베이스 스키마 동기화 문제

문제 상황

  • TypeORM의 synchronize 옵션이 Docker 환경에서 제대로 작동하지 않음
  • 새로운 컬럼들이 데이터베이스에 추가되지 않음

원인 분석

  • Docker 환경에서 TypeORM 설정 문제
  • 데이터베이스 마이그레이션이 자동으로 실행되지 않음

해결 방법

-- 수동으로 스키마 업데이트
ALTER TABLE applications ADD COLUMN "isPaymentReceived" boolean DEFAULT false;
ALTER TABLE applications ADD COLUMN "paymentReceivedAt" timestamp;
ALTER TABLE programs ADD COLUMN revenue integer DEFAULT 0;
ALTER TABLE users ADD COLUMN "isBlocked" boolean DEFAULT false;
ALTER TABLE users ADD COLUMN "blockReason" text;
결과: 모든 필요한 컬럼이 데이터베이스에 추가됨

🌐 Nginx 리버스 프록시 설정

5.1 포트 80 충돌 문제

문제 상황

  • bind() to 0.0.0.0:80 failed (98: Address already in use) 오류
  • Nginx 시작 실패

원인 분석

  • Bitnami의 Apache(httpd) 서비스가 포트 80 사용
  • 기존 웹 서버와 Nginx 간의 포트 충돌

해결 과정

# 1. 포트 80 사용 프로세스 확인
sudo netstat -tulpn | grep :80
sudo fuser -n tcp 80

# 2. Apache 서비스 중지
sudo systemctl stop apache2 httpd
sudo systemctl disable apache2 httpd

# 3. Nginx 시작
sudo systemctl start nginx
결과: Nginx 정상 시작 및 포트 80 사용 가능

5.2 SSL 인증서 설정

문제 상황

  • cannot load certificate "/etc/letsencrypt/live/nuvio.kr/fullchain.pem" 오류
  • SSL 인증서 파일을 찾을 수 없음

원인 분석

  • SSL 인증서가 발급되기 전에 Nginx 설정에서 인증서 파일을 참조
  • Let's Encrypt 인증서 발급 과정에서 문제 발생

해결 과정

# 1. 기본 HTTP 설정으로 Nginx 시작
sudo tee /etc/nginx/sites-available/nuvio.kr > /dev/null << 'EOF'
server {
    listen 80;
    server_name nuvio.kr www.nuvio.kr;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    location /api {
        proxy_pass http://localhost:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
EOF

# 2. 사이트 활성화
sudo ln -sf /etc/nginx/sites-available/nuvio.kr /etc/nginx/sites-enabled/
sudo systemctl restart nginx

# 3. SSL 인증서 발급
sudo certbot --nginx -d nuvio.kr
결과: SSL 인증서 정상 발급 및 HTTPS 접속 가능

🔒 CORS 설정 문제

6.1 CORS 정책 위반

문제 상황

  • Access-Control-Allow-Origin header has a value 'http://localhost:3000' that is not equal to the supplied origin 'https://nuvio.kr' 오류
  • 프론트엔드에서 백엔드 API 호출 실패

원인 분석

  • 프론트엔드: https://nuvio.kr (HTTPS)
  • 백엔드 CORS 설정: http://localhost:3000 (HTTP)

해결 방법

# .env 파일에 올바른 CORS 설정
echo "CORS_ORIGIN=https://nuvio.kr" >> .env
echo "FRONTEND_URL=https://nuvio.kr" >> .env

# docker-compose.yml에서 환경 변수 사용
environment:
  CORS_ORIGIN: ${CORS_ORIGIN:-https://nuvio.kr}
  NEXT_PUBLIC_API_URL: ${FRONTEND_API_URL:-https://nuvio.kr/api}
결과: CORS 정책 위반 해결 및 API 호출 성공

🤖 자동화 스크립트 개발

7.1 클라우드 배포 스크립트

run-nuvio.sh - nuvio.kr 도메인용 실행 스크립트

#!/bin/bash
echo "🚀 nuvio.kr용 ERP 시스템 시작..."

# Docker 권한 확인
if ! docker ps >/dev/null 2>&1; then
    echo "❌ Docker 권한 문제가 감지되었습니다."
    ./fix-docker-permissions.sh
    exit 1
fi

# 환경 변수 파일 설정
if [ ! -f .env ]; then
    cp env.cloud .env
fi

# 포트 충돌 해결
if lsof -i :3000 >/dev/null 2>&1 || lsof -i :3001 >/dev/null 2>&1; then
    ./force-fix-ports.sh
fi

# ERP 시스템 실행
docker-compose down
docker-compose up --build -d

echo "🎉 ERP 시스템이 성공적으로 시작되었습니다!"
echo "📱 접속 정보:"
echo "   프론트엔드: https://nuvio.kr"
echo "   백엔드 API: https://nuvio.kr/api"

7.2 환경별 설정 파일

env.cloud - 클라우드 환경용 설정

DATABASE_URL="postgresql://postgres:password@postgres:5432/intu_erp"
POSTGRES_PASSWORD=password
DB_PASSWORD=password
CORS_ORIGIN="https://nuvio.kr"
FRONTEND_URL="https://nuvio.kr"
NEXT_PUBLIC_API_URL="https://nuvio.kr/api"

🔐 Git 인증 문제 해결

8.1 GitHub Personal Access Token 설정

문제 상황

  • Password authentication is not supported for Git operations 오류
  • Git push 실패

원인 분석

  • GitHub에서 비밀번호 인증 지원 중단
  • Personal Access Token 필요

해결 방법

# Git 사용자 정보 설정
git config --global user.name "Mingjaam"
git config --global user.email "kimminje0627@naver.com"

# 자격 증명 저장소 설정
git config --global credential.helper store

# Personal Access Token 사용하여 푸시
git push origin test
결과: Git 인증 성공 및 코드 푸시 가능

✅ 배포 완료 및 검증

9.1 서비스 상태 확인

배포 상태 확인 명령어

# Docker 컨테이너 상태
docker-compose ps

# Nginx 상태
sudo systemctl status nginx

# SSL 인증서 확인
sudo certbot certificates

# API 접속 테스트
curl -I https://nuvio.kr/api

9.2 최종 접속 정보

🌐 웹 서비스

  • 프론트엔드: https://nuvio.kr
  • 백엔드 API: https://nuvio.kr/api

🗄️ 데이터베이스

  • PostgreSQL: localhost:5432 (내부 네트워크)
  • Redis: localhost:6379 (내부 네트워크)

📈 개발 효율성 향상 포인트

10.1 기능 구현 전 클라우드 배포 환경 구축의 장점

  • 지속적인 배포: 코드 변경사항을 즉시 클라우드에서 테스트 가능
  • 실제 환경 테스트: 로컬과 다른 환경에서의 문제점 조기 발견
  • 팀 협업: 다른 개발자들이 실제 배포된 환경에서 테스트 가능
  • 사용자 피드백: 실제 사용자에게 배포된 환경에서 피드백 수집 가능

10.2 자동화 스크립트의 중요성

  • 일관된 배포: 매번 동일한 과정으로 배포
  • 오류 방지: 수동 작업으로 인한 실수 방지
  • 시간 절약: 복잡한 배포 과정을 자동화
  • 문서화: 스크립트 자체가 배포 과정의 문서 역할

🔮 향후 개선 사항

11.1 CI/CD 파이프라인 구축

.github/workflows/deploy.yml 예시

name: Deploy to Lightsail
on:
  push:
    branches: [test]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Deploy to server
        run: |
          ssh -i ${{ secrets.SSH_KEY }} bitnami@${{ secrets.SERVER_IP }} 'cd /home/bitnami/intu_erp && git pull && ./run-nuvio.sh'

11.2 모니터링 및 로깅

  • 로그 관리: ELK Stack 또는 CloudWatch 로그
  • 모니터링: Prometheus + Grafana
  • 알림: Slack 또는 이메일 알림 설정

🎯 결론

이번 프로젝트를 통해 기능 구현이 완료되기 전에 클라우드 배포 환경을 구축하는 것이 얼마나 중요한지 깨달았습니다. 특히 Docker 컨테이너화, 자동화 스크립트, 환경별 설정 분리 등을 통해 개발 효율성을 크게 향상시킬 수 있었습니다.

Amazon Lightsail을 사용한 클라우드 배포는 비용 효율적이면서도 충분한 성능을 제공하며, 특히 소규모 프로젝트나 프로토타입 개발에 매우 적합합니다. 앞으로도 지속적인 배포와 모니터링을 통해 더욱 안정적인 서비스를 구축해나갈 예정입니다.

💡 핵심 교훈

기능 구현이 완벽하지 않은 상태에서도 클라우드 배포 환경을 먼저 구축해놓는 것이 개발 효율성과 지속적인 배포(CI/CD) 측면에서 매우 유용합니다.