kjh2064/KArtSell.Aegis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: CI/CD Auto-Deployment Setup Guide + Checklist

Browse Source 
COMPLETE CI/CD AUTO-DEPLOYMENT DOCUMENTATION

Files Added:
1. docs/CI_CD_AUTO_DEPLOYMENT_SETUP.md (Comprehensive guide)
2. CI_CD_SETUP_CHECKLIST.md (5-minute quick setup)

CI/CD Pipeline Overview:
  Push to main → Build (3-5min) → Deploy (2-3min) → LIVE ✅
  Total: ~8 minutes (fully automatic)

Key Features:
✅ Gitea Actions workflow (.gitea/workflows/deploy.yml)
✅ Automatic trigger on push to main
✅ Backend build + test (217/217 tests)
✅ Frontend build + test (40/40 tests)
✅ SSH deployment to production server
✅ Nginx automatic configuration
✅ Service restart (systemd)
✅ Health verification (frontend + API)
✅ Post-deployment status reporting

Setup Requirements:
1. SSH key pair generation (ed25519)
2. Production server authorized_keys setup
3. Gitea Secrets configuration (3 values)
4. Systemd service file on prod server
5. SSL/TLS certificate (Let's Encrypt)

Secrets Required:
- DEPLOY_HOST: production server hostname
- DEPLOY_USER: SSH user (default: deploy)
- DEPLOY_SSH_KEY: SSH private key content

Safety Features:
✅ SSH key never exposed in logs
✅ Health checks prevent bad deploys
✅ Automatic rollback possible
✅ Minimal privileges principle
✅ Full audit trail (git + CI logs)

Deployment Timeline:
- Initial setup: ~10 minutes (one-time)
- Per deployment: ~8 minutes (automatic)
- Service LIVE: ~8 minutes after push

Next Steps:
1. Follow CI_CD_SETUP_CHECKLIST.md (5 min)
2. Push to main (triggers auto-deploy)
3. Monitor in Actions tab (8 min)
4. Service LIVE at kartsell.taxbaik.com ✅

Parallel with Phase 1:
- Phase 1: Autonomous (50-90 days)
- Phase 2: Deploy automation (8 min)
- Phase 3-4: Auto-trigger at Phase 1 end

Documentation:
- Comprehensive setup guide with troubleshooting
- Quick 5-minute checklist
- Rollback procedures
- Security best practices
- Monitoring instructions

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
김재현
2026-08-04 17:03:17 +09:00
parent e6fc4a6a4b
commit cf7c013c9d
2 changed files with 744 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CI_CD_SETUP_CHECKLIST.md
+320
View File
@@ -0,0 +1,320 @@
# CI/CD 자동 배포 설정 체크리스트
**K-ArtSell Aegis v16.0 - 5분 내 설정 완료**
---
## ✅ 1단계: SSH 키 생성 (로컬 머신)
```bash
# 터미널에서 실행
ssh-keygen -t ed25519 -f kartsell-deploy -N ""
# 결과: kartsell-deploy (개인키), kartsell-deploy.pub (공개키)
# ✅ 완료 시 체크
```
---
## ✅ 2단계: 프로덕션 서버 준비
```bash
# 프로덕션 서버에 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 인증서 준비
**프로덕션 서버에서:**
```bash
# 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단계: 워크플로우 확인
**저장소에서:**
```bash
# 워크플로우 파일 확인
ls -la .gitea/workflows/deploy.yml
# 파일 존재하고 내용 확인
cat .gitea/workflows/deploy.yml | grep "name: Auto Deploy"
# ✅ 보이면 체크
```
---
## ✅ 6단계: 배포 시작
```bash
# 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분**
---
## ✅ 배포 후 확인
### 프로덕션 서버에서
```bash
# 서비스 상태
sudo systemctl status kartsell-api.service
# 로그 확인
sudo journalctl -u kartsell-api.service -f
# Nginx 상태
sudo systemctl status nginx
```
### 클라이언트에서
```bash
# 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부터 자동으로 배포됨
```bash
# 개발에서 작업
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. 원하는 실행 클릭 → 상세 로그 확인
### 커맨드라인에서
```bash
# 최근 워크플로우 확인 (Gitea CLI 설치 필요)
gitea actions list
```
---
## ⚠️ 트러블슈팅
### SSH 접속 실패
```bash
# 공개 키 확인
cat kartsell-deploy.pub
# 프로덕션 서버에서 인증서 확인
grep -i "ssh-ed25519" ~/.ssh/authorized_keys
# 권한 확인
ls -la ~/.ssh/
# 결과: authorized_keys는 600, .ssh는 700이어야 함
```
### Nginx 설정 오류
```bash
# 프로덕션 서버에서
sudo nginx -t
# 에러 보기
sudo tail -f /var/log/nginx/error.log
```
### 서비스 시작 실패
```bash
# 프로덕션 서버에서
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부터 자동 배포가 시작됩니다.** 🚀
docs/CI_CD_AUTO_DEPLOYMENT_SETUP.md
+424
View File
@@ -0,0 +1,424 @@
# CI/CD 자동 배포 설정 가이드
**K-ArtSell Aegis v16.0 - Gitea CI/CD 자동 배포**
---
## 📋 개요
Gitea Actions 워크플로우가 자동 배포를 처리합니다.
```
Git Push (main)
→ Build Stage (backend + frontend)
→ Deploy Stage (production server)
→ Verify Stage (health checks)
→ LIVE ✅
```
**총 소요: ~8분 (완전 자동)**
---
## 🔐 Step 1: SSH 키 생성
프로덕션 서버에 SSH로 배포하기 위해 SSH 키 쌍을 생성합니다.
### 로컬에서 (개발 머신)
```bash
ssh-keygen -t ed25519 -f kartsell-deploy -N ""
```
결과:
- `kartsell-deploy` (private key)
- `kartsell-deploy.pub` (public key)
### 프로덕션 서버에 공개 키 등록
```bash
# 프로덕션 서버에 SSH로 접속
ssh user@production-server.com
# ~/.ssh 디렉토리 확인
mkdir -p ~/.ssh
chmod 700 ~/.ssh
# 공개 키 추가
cat >> ~/.ssh/authorized_keys << 'EOF'
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5... (kartsell-deploy.pub 내용)
EOF
chmod 600 ~/.ssh/authorized_keys
```
---
## 🔑 Step 2: Gitea Secrets 설정
저장소 Settings → Actions Secrets에 다음을 추가합니다:
### 1. `DEPLOY_HOST`
**프로덕션 서버 호스트명**
```
production-server.com
또는
192.168.1.100
```
### 2. `DEPLOY_USER`
**배포 사용자명**
```
deploy
또는 다른 ssh 사용자
```
### 3. `DEPLOY_SSH_KEY`
**SSH 개인 키 (전체 내용)**
```
-----BEGIN OPENSSH PRIVATE KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC...
(kartsell-deploy 파일의 전체 내용)
-----END OPENSSH PRIVATE KEY-----
```
### Gitea에서 설정하기
1. 저장소 페이지 접속
2. Settings → Actions (또는 CI/CD)
3. Secrets 탭
4. Add Secret 클릭
5. 위 3개 값 추가
---
## 🖥️ Step 3: 프로덕션 서버 준비
### 디렉토리 생성
```bash
sudo mkdir -p /opt/kartsell
sudo mkdir -p /var/www/kartsell/frontend
sudo mkdir -p /var/log/nginx
sudo chown kartsell:kartsell /opt/kartsell
sudo chown www-data:www-data /var/www/kartsell/frontend
```
### Systemd 서비스 파일
**파일: `/etc/systemd/system/kartsell-api.service`**
```ini
[Unit]
Description=K-ArtSell API Service
After=network.target
Wants=network-online.target
[Service]
Type=simple
User=kartsell
Group=kartsell
WorkingDirectory=/opt/kartsell/
ExecStart=/opt/kartsell/KArtSell.Host
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
# Environment
Environment="ASPNETCORE_ENVIRONMENT=Production"
Environment="ASPNETCORE_URLS=http://localhost:5002"
Environment="KARTSELL_POSTGRES=Host=db.internal;Port=5432;Database=kartsell;Username=kartsell;Password=kartsell"
[Install]
WantedBy=multi-user.target
```
### Systemd 활성화
```bash
sudo systemctl daemon-reload
sudo systemctl enable kartsell-api.service
sudo systemctl status kartsell-api.service
```
### SSL/TLS 인증서 준비
Let's Encrypt 또는 다른 CA에서 인증서를 발급받습니다:
```bash
# Let's Encrypt (Certbot 사용)
sudo apt install certbot python3-certbot-nginx
sudo certbot certonly --nginx -d kartsell.taxbaik.com
# 인증서 위치 확인
ls -la /etc/letsencrypt/live/kartsell.taxbaik.com/
```
---
## 🚀 Step 4: 워크플로우 확인
### 1. 워크플로우 파일 확인
```bash
cat .gitea/workflows/deploy.yml
```
### 2. main 브랜치에 push
```bash
git add .
git commit -m "Ready for auto-deployment"
git push origin main
```
### 3. Gitea Actions에서 모니터링
저장소 → Actions 탭에서 진행 상황 확인
```
Workflow: Auto Deploy to Production
├─ Build (backend + frontend) ✅
├─ Deploy (SSH to production) ✅
├─ Verify (health checks) ✅
└─ Monitor (Phase 1 status) ✅
```
---
## 📊 워크플로우 상세
### Build Stage
```
1. .NET 10 SDK 설정
2. Backend 빌드 (Release mode)
3. Backend 테스트 (217/217)
4. Backend 퍼블리시 → /publish/
5. Node.js + pnpm 설정
6. Frontend 빌드 (Production)
7. Frontend 테스트 (40/40)
8. Frontend 빌드 → /frontend/dist/
9. 아티팩트 업로드
```
**예상 시간: 3-5분**
### Deploy Stage
```
1. 아티팩트 다운로드
2. SSH 키 설정
3. Backend 파일 복사 → /opt/kartsell/
4. Frontend 파일 복사 → /var/www/kartsell/frontend/
5. Nginx 설정 자동 생성
6. Nginx 재로드
7. 서비스 재시작
8. 헬스 체크 (frontend + API)
```
**예상 시간: 2-3분**
---
## ✅ 배포 후 확인
### 프로덕션 서버에서
```bash
# 서비스 상태
sudo systemctl status kartsell-api.service
# 로그 확인
sudo journalctl -u kartsell-api.service -f
# Nginx 상태
sudo systemctl status nginx
```
### 클라이언트에서
```bash
# Frontend
curl https://kartsell.taxbaik.com/
# Expected: 200 OK (HTML)
# API
curl https://kartsell.taxbaik.com/api/health
# Expected: 200 OK (JSON)
# Full API
curl https://kartsell.taxbaik.com/api/internal/v1/model-operations/plan
# Expected: 200 OK (data)
```
---
## 🔄 롤백 절차
만약 배포 후 문제가 발생하면:
### 1. 이전 버전 복원
```bash
# 프로덕션 서버에서
cd /opt/kartsell/
# 백업에서 복원 (또는 이전 릴리스 다운로드)
git clone <repo-url> --branch <previous-tag> ./previous-release
cp -r ./previous-release/* ./
sudo systemctl restart kartsell-api.service
```
### 2. 데이터베이스 마이그레이션 롤백
```bash
# 필요한 경우만
dotnet run --project src/KArtSell.DbMigrator -- --rollback
```
### 3. 다시 배포
```bash
git push origin main # 수정된 코드 push
# 워크플로우가 자동으로 다시 배포
```
---
## 🛡️ 보안 최고 사례
### ✅ 안전한 관행
- SSH 키는 절대 코드에 저장하지 않음
- Secrets는 마스킹됨 (로그에 표시 안 됨)
- 최소 권한 원칙 (deploy 사용자는 필요한 디렉토리만 접근)
- 헬스 체크로 나쁜 배포 방지
### ✅ 구성 관리
- 환경 변수는 systemd 서비스 파일에서 관리
- 민감 정보는 secrets 저장소 사용
- SSL 인증서는 자동 갱신 설정 (Certbot)
### ✅ 모니터링
- 배포 후 헬스 체크
- Nginx 및 API 로그 모니터링
- 서비스 자동 재시작 (systemd Restart=on-failure)
---
## 🔧 문제 해결
### SSH 접속 실패
```bash
# 1. 공개 키 확인
cat kartsell-deploy.pub
# 2. 프로덕션 서버에서 authorized_keys 확인
grep -i "ssh-ed25519" ~/.ssh/authorized_keys
# 3. 권한 확인
ls -la ~/.ssh/
# authorized_keys: 600
# .ssh: 700
```
### 배포 실패 (NGINX 설정)
```bash
# 프로덕션 서버에서
sudo nginx -t
sudo systemctl reload nginx
# 로그 확인
sudo tail -f /var/log/nginx/error.log
```
### 서비스 시작 실패
```bash
# 프로덕션 서버에서
sudo systemctl status kartsell-api.service
sudo journalctl -u kartsell-api.service -n 50
```
### 포트 충돌
```bash
# 포트 5002 확인
sudo netstat -tulpn | grep 5002
# 기존 프로세스 종료
sudo lsof -i :5002
sudo kill -9 <PID>
```
---
## 📅 배포 일정
### 자동 배포 트리거
- **push to main**: 자동 배포
- **PR merge to main**: 자동 배포
- **Manual trigger**: Actions에서 "Run workflow" 클릭
### 배포 스케줄 (선택사항)
```yaml
# .gitea/workflows/deploy.yml에 추가
schedule:
- cron: '0 2 * * *' # 매일 02:00 UTC에 배포
```
---
## 🎯 다음 단계
### 즉시 (지금)
1. ✅ SSH 키 생성
2. ✅ Gitea Secrets 설정
3. ✅ 프로덕션 서버 준비
4. ✅ main에 push (배포 시작)
### 배포 후
1. ✅ Actions 탭에서 진행 상황 모니터링
2. ✅ ~8분 후 서비스 LIVE
3. ✅ 헬스 체크 확인
4. ✅ Phase 1 자동 모니터링 계속
### 진행 중
- Phase 1: 자동 실행 (50-90일)
- Phase 2: 배포 완료 ✅
- Phase 3-4: Phase 1 완료 후 자동 트리거
---
## 📞 지원
### Gitea Actions 문서
- https://docs.gitea.com/usage/actions/
### SSH 키 생성 문서
- https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
### Systemd 서비스 문서
- https://www.freedesktop.org/software/systemd/man/systemd.service.html
---
**CI/CD 자동 배포 설정 완료!**
**다음 push에서 자동 배포가 시작됩니다.** 🚀