KArtSell.Aegis/CI_CD_SETUP_CHECKLIST.md

CI/CD 자동 배포 설정 체크리스트

K-ArtSell Aegis v16.0 - 5분 내 설정 완료

---

✅ 1단계: SSH 키 생성 (로컬 머신)

# 터미널에서 실행
ssh-keygen -t ed25519 -f kartsell-deploy -N ""

# 결과: kartsell-deploy (개인키), kartsell-deploy.pub (공개키)
# ✅ 완료 시 체크

---

✅ 2단계: 프로덕션 서버 준비

# 프로덕션 서버에 SSH로 접속
ssh user@production-server.com

# 필요한 명령 실행
mkdir -p ~/.ssh
chmod 700 ~/.ssh

# kartsell-deploy.pub 파일 내용을 복사해서 다음 명령 실행
cat >> ~/.ssh/authorized_keys << 'EOF'
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5... (공개키 전체 내용)
EOF

chmod 600 ~/.ssh/authorized_keys

# Systemd 서비스 파일 생성
sudo cat > /etc/systemd/system/kartsell-api.service << 'EOF'
[Unit]
Description=K-ArtSell API Service
After=network.target

[Service]
Type=simple
User=kartsell
WorkingDirectory=/opt/kartsell/
ExecStart=/opt/kartsell/KArtSell.Host
Restart=on-failure
RestartSec=10
Environment="ASPNETCORE_URLS=http://localhost:5002"

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable kartsell-api.service

# ✅ 완료 시 체크

---

✅ 3단계: Gitea Secrets 설정

위치: 저장소 → Settings → Actions → Secrets

Add Secret 1: DEPLOY_HOST

값: production-server.com (또는 IP)
설명: Production server hostname
✅ 완료 시 체크

Add Secret 2: DEPLOY_USER

값: deploy (또는 기타 ssh 사용자명)
설명: SSH user for deployment
✅ 완료 시 체크

Add Secret 3: DEPLOY_SSH_KEY

값: kartsell-deploy 파일의 전체 내용 (----BEGIN부터 ----END까지)
설명: SSH private key (ed25519)
✅ 완료 시 체크

---

✅ 4단계: SSL 인증서 준비

프로덕션 서버에서:

# Let's Encrypt 인증서 설치
sudo apt update
sudo apt install certbot python3-certbot-nginx
sudo certbot certonly --standalone -d kartsell.taxbaik.com

# 인증서 위치 확인
ls -la /etc/letsencrypt/live/kartsell.taxbaik.com/
# ✅ 인증서 있으면 체크

---

✅ 5단계: 워크플로우 확인

저장소에서:

# 워크플로우 파일 확인
ls -la .gitea/workflows/deploy.yml

# 파일 존재하고 내용 확인
cat .gitea/workflows/deploy.yml | grep "name: Auto Deploy"
# ✅ 보이면 체크

---

✅ 6단계: 배포 시작

# 1. 변경사항 커밋
git add .
git commit -m "CI/CD 자동 배포 설정 완료"

# 2. main에 push
git push origin main

# 3. Gitea Actions에서 모니터링
#    → 저장소 → Actions 탭
#    → "Auto Deploy to Production" 워크플로우 확인
#    → 진행 상황 모니터링

# ✅ 배포 완료 시 체크

---

📊 배포 진행 상황 모니터링

Gitea Actions 탭에서 확인

Workflow: Auto Deploy to Production
│
├─ build: ⏳ → ✅ (~3-5분)
│  ├─ Checkout
│  ├─ Setup .NET
│  ├─ Restore backend
│  ├─ Build backend (Release)
│  ├─ Test backend (217/217)
│  ├─ Publish backend
│  ├─ Setup Node
│  ├─ Install frontend deps
│  ├─ Typecheck frontend
│  ├─ Test frontend (40/40)
│  ├─ Build frontend
│  └─ Upload artifacts
│
├─ deploy: ⏳ → ✅ (~2-3분)
│  ├─ Download artifacts
│  ├─ Setup SSH
│  ├─ Deploy backend
│  ├─ Deploy frontend
│  ├─ Configure Nginx
│  ├─ Restart service
│  └─ Verify deployment ✅
│
└─ monitor: ⏳ → ✅ (~1분)
   └─ Phase 1 status check

총 소요: ~8분

---

✅ 배포 후 확인

프로덕션 서버에서

# 서비스 상태
sudo systemctl status kartsell-api.service

# 로그 확인
sudo journalctl -u kartsell-api.service -f

# Nginx 상태
sudo systemctl status nginx

클라이언트에서

# Frontend 확인
curl https://kartsell.taxbaik.com/
# Expected: 200 OK

# API 확인
curl https://kartsell.taxbaik.com/api/health
# Expected: 200 OK (JSON)

---

📝 최종 체크리스트

[ ] 1. SSH 키 생성 완료
[ ] 2. 프로덕션 서버 준비 완료
[ ] 3. Gitea Secrets 3개 추가 완료
[ ] 4. SSL 인증서 준비 완료
[ ] 5. 워크플로우 파일 확인 완료
[ ] 6. main에 push 시작
[ ] 7. Actions에서 build 성공 확인
[ ] 8. Actions에서 deploy 성공 확인
[ ] 9. Production 서비스 LIVE 확인
[ ] 10. 헬스 체크 통과 확인

모든 항목 체크 시: ✅ CI/CD 자동 배포 완성!

---

🚀 자동 배포 동작 확인

다음 push부터 자동으로 배포됨

# 개발에서 작업
vi src/SomeFeature.cs
git add .
git commit -m "feat: new feature"

# Push
git push origin main

# 자동으로:
# 1. Build 시작 (3-5분)
# 2. Build 성공 → Deploy 시작
# 3. Deploy 수행 (2-3분)
# 4. 서비스 LIVE ✅

---

🔄 배포 상태 확인 방법

Gitea UI에서

1. 저장소 페이지
2. "Actions" 탭 클릭
3. "Auto Deploy to Production" 워크플로우 확인
4. 원하는 실행 클릭 → 상세 로그 확인

커맨드라인에서

# 최근 워크플로우 확인 (Gitea CLI 설치 필요)
gitea actions list

---

⚠️ 트러블슈팅

SSH 접속 실패

# 공개 키 확인
cat kartsell-deploy.pub

# 프로덕션 서버에서 인증서 확인
grep -i "ssh-ed25519" ~/.ssh/authorized_keys

# 권한 확인
ls -la ~/.ssh/
# 결과: authorized_keys는 600, .ssh는 700이어야 함

Nginx 설정 오류

# 프로덕션 서버에서
sudo nginx -t

# 에러 보기
sudo tail -f /var/log/nginx/error.log

서비스 시작 실패

# 프로덕션 서버에서
sudo systemctl status kartsell-api.service
sudo journalctl -u kartsell-api.service -n 50

---

📞 필요한 경우 도움

이 설정 완료 후:

1. 처음 배포: 최대 8분 소요
2. 이후 배포: 자동 (push하면 자동 배포)
3. Phase 1: 계속 자동 실행 (50-90일)
4. Phase 3-4: Phase 1 완료 후 자동 트리거

---

5분 안에 CI/CD 자동 배포 설정 완료! ✅

다음 commit부터 자동 배포가 시작됩니다. 🚀