![[시리즈 5/5] Claude Code로 배포 시스템 구축하기](https://blog.flyerschal.com/uploads/posts/cicd-s5-cover.png)
[시리즈 5/5] Claude Code로 배포 시스템 구축하기
[시리즈 5/5] Claude Code로 배포 시스템 구축하기
이 글은 "Claude Code로 구축하는 무중단 자동 배포 시스템" 시리즈의 마지막 글입니다.
- 무중단 자동 배포 시스템이란?
- GitHub + Webhook: Git 푸시로 배포 트리거하기
- Docker + Blue/Green: 무중단 배포 구현하기
- 텔레그램 알림 + 로그 전략
- [현재] Claude Code로 배포 시스템 구축하기
이 글에서 다루는 것
지금까지 설명한 모든 시스템을 Claude Code에게 대화하듯이 지시하여 구축하는 방법을 다룹니다. 효과적인 프롬프트 전략, 단계별 구축 과정, 실전에서 겪는 문제와 해결, 운영 노하우까지.
Claude Code란?
Claude Code는 Anthropic의 터미널 기반 AI 코딩 어시스턴트입니다. 파일 읽기/쓰기, 명령어 실행, Git 작업 등을 직접 수행합니다.
배포 시스템 구축에 왜 Claude Code인가?
| 장점 | 설명 |
|---|---|
| 파일 직접 작성 | Dockerfile, deploy.sh, hooks.json을 직접 생성 |
| 명령어 실행 | docker build, nginx -t 등을 직접 실행하고 결과 확인 |
| 에러 자동 수정 | 빌드 에러 발생 시 즉시 분석하고 코드 수정 |
| 컨텍스트 유지 | 프로젝트 구조, 이전 대화 내용을 기억 |
| 텔레그램 연동 | 모바일에서 배포 지시 가능 |
프롬프트 전략: 좋은 지시 vs 나쁜 지시
원칙 1: 구체적으로
❌ "배포 시스템 만들어줘"
✅ "blog 프로젝트의 무중단 배포를 설정해줘.
현재 환경: Docker Compose + Nginx
요구사항: Blue/Green, 헬스체크, 텔레그램 알림"
Claude Code는 구체적인 요구사항이 있을수록 정확한 결과를 만듭니다.
원칙 2: 현재 상태를 알려줘
❌ "Nginx 설정해줘"
✅ "Nginx가 nginx_default 네트워크에서 실행 중이야.
blog-blue는 blog_blog-net에 있고 포트 14001.
blog-blue:3000으로 프록시 설정해줘."
현재 환경, 네트워크, 포트 등 맥락을 제공하면 시행착오가 줄어듭니다.
원칙 3: 단계별로 진행
한 번에 모든 걸 요청하지 마세요. 단계별로 진행하고 각 단계를 검증합니다.
1단계: "docker-compose.yml에 blog-blue, blog-green 서비스를 추가해줘"
→ 확인 → 문제 있으면 수정
2단계: "webhook 서버 설정을 만들어줘. hooks.json에 HMAC 검증 포함"
→ 확인 → 테스트
3단계: "deploy.sh를 작성해줘. Blue/Green 전환 + 헬스체크"
→ 확인 → 빈 커밋으로 테스트
4단계: "텔레그램 알림을 deploy.sh에 추가해줘"
→ 확인 → 전체 테스트
원칙 4: 테스트를 요청해
"빈 커밋으로 배포 테스트해줘.
webhook 호출이 성공하는지,
컨테이너가 시작되는지,
nginx 전환이 되는지 단계별로 확인해줘."
Claude Code가 직접 테스트를 실행하고 결과를 보고합니다.
단계별 구축 실전 가이드
Phase 1: 기본 인프라
프롬프트:
"~/Documents/services/blog/ 디렉토리에 배포 인프라를 만들어줘.
필요한 파일:
1. docker-compose.yml — blog-blue(14001), blog-green(15001), webhook(9000)
2. webhook/Dockerfile — adnanh/webhook 기반, docker-cli 포함
3. webhook/hooks.json — HMAC-SHA256 검증, main 브랜치만 반응
4. .env.production — GITHUB_TOKEN, WEBHOOK_SECRET, TELEGRAM_* 변수
blog-blue, blog-green은 fc-blog:latest 이미지 사용.
네트워크 이름은 blog-net."
Claude Code가 수행하는 작업:
- 각 파일 생성
- 디렉토리 구조 확인
- docker-compose 문법 검증
Phase 2: 배포 스크립트
프롬프트:
"deploy.sh를 만들어줘.
실행 순서:
1. 현재 활성 환경 확인 (active_blog_green 파일 존재 여부)
2. GitHub에서 소스 clone (--depth 1)
3. npm install && npm run build
4. Docker 이미지 빌드 (fc-blog:latest)
5. 비활성 환경에 새 컨테이너 시작
6. nginx_default 네트워크에도 연결
7. 헬스체크 (60초 타임아웃)
8. Nginx upstream 전환 (active flag + reload)
9. 이전 컨테이너 정지
10. Docker 이미지 정리
실패 시:
- 새 컨테이너 정지
- 이전 환경 유지
- 텔레그램 알림
모든 단계에 타임스탬프 로그 남기기."
Phase 3: Nginx 설정
프롬프트:
"Nginx에 blog.flyerschal.com 설정을 추가해줘.
요구사항:
- SSL (Let's Encrypt)
- Blue/Green 전환 ($backend 변수 + active_blog_green 파일)
- resolver 127.0.0.11 (Docker DNS)
- /webhook → blog-webhook:9000 프록시
- /health → 현재 활성 환경 반환"
Phase 4: 테스트 & 디버깅
프롬프트:
"전체 파이프라인을 테스트해줘.
1. docker-compose up -d로 서비스 시작
2. 빈 커밋 + 푸시로 webhook 트리거
3. deploy.sh가 실행되는지 확인
4. 헬스체크 통과하는지 확인
5. Nginx 전환이 되는지 확인
6. 텔레그램 알림이 오는지 확인
각 단계에서 문제가 있으면 바로 수정해줘."
실전에서 겪는 문제와 해결
문제 1: Docker 네트워크 분리
증상: Nginx가 blog-blue에 접근 못함 (502 Bad Gateway)
원인: Nginx는 nginx_default 네트워크, blog-blue는 blog_blog-net에 있음
해결:
# deploy.sh에서 컨테이너 시작 후 추가
docker network connect nginx_default "$CONTAINER" 2>/dev/null || true
Claude Code에게 요청하는 방법:
"blog-blue가 502 에러야.
nginx는 nginx_default 네트워크, blog-blue는 blog_blog-net에 있어.
네트워크 연결 문제인 것 같은데 확인하고 수정해줘."
문제 2: 디스크 부족
증상: Docker 데몬 무응답, 빌드 실패
원인: Docker 이미지가 쌓여서 디스크 가득 참
해결:
# deploy.sh 마지막에 추가
docker image prune -f --filter "until=72h"
# 긴급 상황
docker system prune -af # 모든 미사용 리소스 삭제
예방: 배포 스크립트에 디스크 체크 추가
AVAIL=$(df / | tail -1 | awk '{print $4}')
if [ "$AVAIL" -lt 2000000 ]; then # 2GB 미만
notify "⚠️ 디스크 부족 (${AVAIL}KB). 배포 중단"
exit 1
fi
문제 3: Prisma 엔진 누락
증상: 앱 시작 시 PrismaClientInitializationError
원인: Docker 이미지에 Prisma 네이티브 바이너리가 포함되지 않음
해결: Dockerfile에서 Prisma 설치 + generate
COPY prisma ./prisma
COPY src/generated/prisma ./src/generated/prisma
RUN npm install prisma @prisma/client --save-prod
RUN npx prisma generate
문제 4: .next/cache 권한 오류
증상: EACCES: permission denied, mkdir '/app/.next/cache'
원인: nextjs 사용자로 실행하는데 .next/cache 디렉토리가 없거나 권한 없음
해결: Dockerfile에서 디렉토리 생성
RUN mkdir -p /app/.next/cache && chown nextjs:nodejs /app/.next/cache
문제 5: Webhook이 트리거되지 않음
증상: git push 후 아무 반응 없음
확인 순서:
- GitHub → Webhooks → Recent Deliveries 확인
docker logs blog-webhook확인- Secret 일치 여부 확인
- 브랜치 필터 확인 (main만 반응)
운영 체크리스트
일간
- 텔레그램 알림 수신 확인
- 서비스 정상 동작 확인 (헬스체크 URL)
주간
- Docker 디스크 사용량 확인 (
docker system df) - 배포 로그에서 경고 패턴 확인
- SSL 인증서 만료일 확인
월간
- GitHub PAT 만료일 확인
- Docker 이미지 대청소 (
docker system prune -af) - deploy.sh 개선사항 검토
- Nginx 설정 백업
Claude Code + 텔레그램 = 모바일 DevOps
Claude Code에 텔레그램 채널을 연동하면, 모바일에서도 배포를 관리할 수 있습니다.
가능한 작업
👤 블로그 빈 커밋 푸시해줘
🤖 완료! (abc1234) — webhook 트리거됨
👤 배포 로그 확인해줘
🤖 [로그 요약: 빌드 45초, 총 소요 87초, 성공]
👤 현재 활성 환경이 뭐야?
🤖 blog-green이 활성 (port:15001)
👤 nginx 설정 확인해줘
🤖 blog.flyerschal.com → blog-green:3000, 정상
👤 디스크 상태 확인해줘
🤖 33GB / 460GB 사용 가능, 정상
설정 방법
텔레그램 채널 설정은 이 시리즈의 별도 가이드를 참고하세요: 👉 Claude Code 텔레그램 채널 설정 완벽 가이드
시리즈 요약
5개의 글을 통해 완성한 시스템:
| 글 | 구축한 것 |
|---|---|
| 1편 | 전체 아키텍처 이해 |
| 2편 | GitHub Webhook으로 자동 트리거 |
| 3편 | Docker Blue/Green 무중단 배포 |
| 4편 | 텔레그램 알림 + 로그 전략 |
| 5편 | Claude Code 활용 + 운영 노하우 |
최종 결과
git push → 자동 빌드 → 무중단 배포 → 텔레그램 알림
1초 ~1분 다운타임 0 즉시
이 시스템의 비용
| 항목 | 비용 |
|---|---|
| GitHub Private 저장소 | 무료 |
| adnanh/webhook | 무료 (오픈소스) |
| Docker | 무료 (CE) |
| Let's Encrypt SSL | 무료 |
| 텔레그램 Bot API | 무료 |
| 총 비용 | 서버 비용만 |
마치며
자동 배포 시스템은 한 번 구축하면 매 배포마다 시간을 절약합니다. 하루 5번 배포한다면, 수동 배포 대비 매일 30분 이상을 아낄 수 있습니다.
Claude Code를 활용하면 이 시스템을 대화 몇 번으로 구축할 수 있습니다. 코드를 직접 작성하지 않아도, 원하는 구조를 설명하면 Claude Code가 파일을 만들고, 테스트하고, 디버깅합니다.
문제가 생기면 로그를 전달하세요. Claude Code가 분석하고, 스크립트를 개선하고, 다시 배포합니다. 이 피드백 루프가 시스템을 점점 더 안정적으로 만들어줍니다.
1인 개발자에게 자동 배포는 선택이 아닌 필수입니다. 지금 바로 시작하세요.
