kt-event-marketing/deployment/uiux/README.md

# KT 이벤트 마케팅 프로토타입 배포 가이드

UI/UX 프로토타입을 Docker 컨테이너로 빌드하고 Kubernetes 클러스터에 배포하는 가이드입니다.

## 📋 목차

1. [사전 요구사항](#사전-요구사항)
2. [이미지 빌드](#이미지-빌드)
3. [로컬 테스트](#로컬-테스트)
4. [Kubernetes 배포](#kubernetes-배포)
5. [접속 및 확인](#접속-및-확인)
6. [문제 해결](#문제-해결)

---

## 🔧 사전 요구사항

### 필수 도구
- Docker (버전 20.10 이상)
- kubectl (버전 1.24 이상)
- Kubernetes 클러스터 (접근 권한 필요)

### 환경 변수 설정 (선택사항)

```bash
# Docker 레지스트리 설정
export DOCKER_REGISTRY=acrdigitalgarage01.azurecr.io  # Azure Container Registry
export IMAGE_TAG=v1.0.0                                # 기본값: latest

# Kubernetes 네임스페이스 설정
export KUBE_NAMESPACE=kt-event-marketing              # 기본값: kt-event-marketing
```

---

## 🔨 이미지 빌드

### 1. 빌드 스크립트 실행

프로젝트 루트에서 다음 명령어를 실행합니다:

```bash
./deployment/uiux/build.sh
```

### 2. 빌드 프로세스

스크립트는 다음 단계를 수행합니다:
1. Docker 이미지 빌드
2. 레지스트리 푸시 여부 확인
3. (선택시) 이미지를 레지스트리에 푸시

### 3. 수동 빌드 (선택사항)

스크립트를 사용하지 않고 수동으로 빌드할 수도 있습니다:

```bash
# 이미지 빌드
docker build -f deployment/uiux/Dockerfile \
  -t acrdigitalgarage01.azurecr.io/kt-event-prototype:latest .

# 레지스트리에 푸시
docker push acrdigitalgarage01.azurecr.io/kt-event-prototype:latest
```

---

## 🧪 로컬 테스트

Kubernetes에 배포하기 전에 로컬에서 테스트할 수 있습니다:

```bash
# 컨테이너 실행
docker run -d -p 8080:80 --name prototype \
  acrdigitalgarage01.azurecr.io/kt-event-prototype:latest

# 브라우저에서 접속
# http://localhost:8080

# 컨테이너 중지 및 제거
docker stop prototype
docker rm prototype
```

### 헬스체크 확인

```bash
curl http://localhost:8080/health
# 출력: OK
```

---

## ☸️ Kubernetes 배포

### 1. 배포 스크립트 실행

```bash
./deployment/uiux/deploy.sh
```

### 2. 배포 옵션 선택

스크립트 실행 시 다음 옵션을 선택할 수 있습니다:
- **1) 전체 배포**: Deployment + Service + Ingress 모두 배포
- **2) 업데이트**: Deployment 업데이트 (이미지 변경 시)
- **3) 삭제**: 모든 리소스 삭제

### 3. 수동 배포 (선택사항)

```bash
# 모든 리소스 배포
kubectl apply -f deployment/uiux/k8s/deployment.yaml
kubectl apply -f deployment/uiux/k8s/service.yaml
kubectl apply -f deployment/uiux/k8s/ingress.yaml

# 배포 상태 확인
kubectl rollout status deployment/kt-event-prototype
```

### 4. 이미지 업데이트

새 이미지로 업데이트하려면:

```bash
# 새 이미지로 태그 변경
kubectl set image deployment/kt-event-prototype \
  nginx=acrdigitalgarage01.azurecr.io/kt-event-prototype:v1.0.1 \
  -n kt-event-marketing

# 롤아웃 상태 확인
kubectl rollout status deployment/kt-event-prototype -n kt-event-marketing

# 롤백 (필요시)
kubectl rollout undo deployment/kt-event-prototype -n kt-event-marketing
```

---

## 🌐 접속 및 확인

### 1. Pod 상태 확인

```bash
kubectl get pods -l app=kt-event-prototype -n kt-event-marketing
```

정상 상태:
```
NAME                                   READY   STATUS    RESTARTS   AGE
kt-event-prototype-xxxxxxxxxx-xxxxx   1/1     Running   0          1m
```

### 2. Service 확인

```bash
kubectl get svc kt-event-prototype -n kt-event-marketing
```

### 3. Ingress 확인

```bash
kubectl get ingress kt-event-prototype -n kt-event-marketing
```

Ingress 호스트 주소: `prototype.kt-event.kubepia.com`

### 4. 브라우저에서 접속

```
http://prototype.kt-event.kubepia.com
```

> **참고**: 도메인이 외부 DNS에 등록되어 있지 않은 경우, `/etc/hosts` (또는 Windows: `C:\Windows\System32\drivers\etc\hosts`) 파일에 다음을 추가하여 로컬 테스트 가능:
> ```
> <INGRESS_CONTROLLER_IP> prototype.kt-event.kubepia.com
> ```
>
> Ingress Controller IP 확인:
> ```bash
> kubectl get svc -n ingress-nginx
> ```

### 6. 프로토타입 화면 목록

접속 후 다음 화면들을 확인할 수 있습니다:
- 01-로그인.html
- 02-회원가입.html
- 03-프로필.html
- 04-로그아웃확인.html
- 05-대시보드.html
- 06-이벤트목록.html
- 07-이벤트목적선택.html
- 08-AI이벤트추천.html
- 09-콘텐츠미리보기.html
- 10-콘텐츠편집.html
- 11-이벤트게시.html
- 12-내이벤트.html
- 13-이벤트상세.html
- 14-이벤트수정.html
- 15-이벤트삭제확인.html
- 16-통계대시보드.html
- 17-예산관리.html
- 18-공유하기.html
- 19-알림센터.html
- 20-도움말.html

---

## 🔍 문제 해결

### Pod가 시작하지 않을 때

```bash
# Pod 상세 정보 확인
kubectl describe pod -l app=kt-event-prototype -n kt-event-marketing

# Pod 로그 확인
kubectl logs -l app=kt-event-prototype -n kt-event-marketing

# 이벤트 확인
kubectl get events -n kt-event-marketing --sort-by='.lastTimestamp'
```

### 일반적인 문제

#### 1. ImagePullBackOff 에러
- **원인**: 이미지를 레지스트리에서 가져올 수 없음
- **해결**:
  ```bash
  # 이미지 이름 확인
  kubectl get deployment kt-event-prototype -n kt-event-marketing \
    -o jsonpath='{.spec.template.spec.containers[0].image}'

  # 수동으로 이미지 pull 테스트
  docker pull acrdigitalgarage01.azurecr.io/kt-event-prototype:latest
  ```

#### 2. CrashLoopBackOff 에러
- **원인**: 컨테이너가 시작 후 계속 종료됨
- **해결**:
  ```bash
  # 로그 확인
  kubectl logs -l app=kt-event-prototype -n kt-event-marketing --previous

  # 컨테이너 내부 확인
  kubectl exec -it <pod-name> -n kt-event-marketing -- sh
  ```

#### 3. Ingress 접속 안됨
- **원인**: Ingress Controller 미설치 또는 DNS 미설정
- **해결**:
  ```bash
  # Ingress Controller 확인
  kubectl get pods -n ingress-nginx

  # Ingress 상세 확인
  kubectl describe ingress kt-event-prototype -n kt-event-marketing
  ```

### 로그 확인 명령어

```bash
# 실시간 로그 확인
kubectl logs -f -l app=kt-event-prototype -n kt-event-marketing

# 최근 100줄 로그
kubectl logs --tail=100 -l app=kt-event-prototype -n kt-event-marketing

# 모든 Pod의 로그
kubectl logs -l app=kt-event-prototype -n kt-event-marketing --all-containers=true

# 이전 컨테이너 로그 (CrashLoopBackOff 시)
kubectl logs -l app=kt-event-prototype -n kt-event-marketing --previous
```

### 리소스 정리

```bash
# 모든 리소스 삭제
kubectl delete -f deployment/uiux/k8s/ -n kt-event-marketing

# 또는 개별 삭제
kubectl delete ingress kt-event-prototype -n kt-event-marketing
kubectl delete service kt-event-prototype -n kt-event-marketing
kubectl delete deployment kt-event-prototype -n kt-event-marketing
```

---

## 📊 리소스 사양

### Deployment
- **Replicas**: 2개 (고가용성)
- **Container Port**: 80
- **Resources**:
  - CPU: 100m (request), 200m (limit)
  - Memory: 128Mi (request), 256Mi (limit)

### Service
- **Type**: ClusterIP
- **Port**: 80

### Ingress
- **Host**: `prototype.kt-event.local` (변경 필요)
- **Path**: `/` (모든 경로)
- **Backend**: kt-event-prototype:80

---

## 🔐 보안 설정

- **runAsNonRoot**: true (root 사용자로 실행 안함)
- **readOnlyRootFilesystem**: false (nginx 로그 작성 허용)
- **allowPrivilegeEscalation**: false
- **Capabilities**: NET_BIND_SERVICE만 허용

---

## 📝 참고 사항

1. **도메인**: 현재 `prototype.kt-event.kubepia.com`으로 설정되어 있습니다. 변경이 필요한 경우 `k8s/ingress.yaml`에서 수정하세요.
2. **네임스페이스**: `kt-event-marketing` 네임스페이스를 사용합니다. 환경변수 `KUBE_NAMESPACE`로 변경 가능합니다.
3. **레지스트리**: Azure Container Registry(`acrdigitalgarage01.azurecr.io`)를 사용합니다.
4. **리소스 제한**: 프로덕션 환경에서는 리소스 요청/제한을 조정하세요.
5. **TLS**: HTTPS 사용 시 `ingress.yaml`에서 TLS 섹션을 활성화하세요.
6. **모니터링**: Prometheus/Grafana를 통한 모니터링 권장합니다.
7. **nginx 설정**: nginx 설정은 Docker 이미지에 포함되어 있습니다. 변경이 필요한 경우 `nginx.conf`를 수정하고 이미지를 재빌드하세요.

---

## 🤝 지원

문제가 발생하면 다음을 확인하세요:
1. Pod 로그
2. Ingress Controller 로그
3. Kubernetes 이벤트

추가 지원이 필요하면 개발팀에 문의하세요.