☁️ 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 설정 등 실제 프로덕션 환경에서 마주치는 문제들을 단계별로 해결해나갔습니다.
💡 중요한 점
기능 구현이 완벽하지 않은 상태에서도 클라우드 배포 환경을 먼저 구축해놓는 것이 개발 효율성과 지속적인 배포(CI/CD) 측면에서 매우 유용합니다.
🏗️ 프로젝트 구조
🚀 초기 환경 설정 및 문제
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' 명령어를 실행해야 합니다."
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 "🎉 강력한 포트 충돌 해결 완료!"
⚙️ 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
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
🔒 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}
🤖 자동화 스크립트 개발
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
✅ 배포 완료 및 검증
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) 측면에서 매우 유용합니다.