# Guide-UI 배포 가이드 (docs.cryptoments.cc)

## 개요

| 항목 | 값 |
|------|-----|
| **도메인** | `docs.cryptoments.cc` |
| **서버** | widget (`103.213.248.135`), user: `root` |
| **경유** | bastion (`13.113.128.166`), user: `ubuntu` |
| **앱 경로** | `/opt/cryptoments/guide-ui` |
| **런타임** | Node.js 20 (fnm) + Express (port 8889) |
| **프로세스** | PM2 (`guide-ui`) |
| **웹서버** | Nginx → reverse proxy → localhost:8889 |
| **SSL** | Let's Encrypt (certbot) |
| **CI/CD** | GitLab → `guide-ui/**/*` 변경 시 자동 배포 |

## 아키텍처

```
Client → docs.cryptoments.cc
       → Nginx (443/SSL) → reverse proxy
       → Express server.js (localhost:8889)
       → api.html / widget.html / webhook.html / partner-guide.html
```

## 1단계: 서버 초기 세팅

bastion 경유하여 widget 서버에 접속 후 세팅 스크립트 실행.

```bash
# 로컬에서 bastion 접속
ssh -i aws_ssh_server.pem ubuntu@13.113.128.166

# bastion → widget 접속
ssh widget    # 또는 ssh root@103.213.248.135

# 서버 세팅 스크립트 실행 (최초 1회)
# 아래 내용을 widget 서버에서 직접 실행하거나,
# scripts/setup-server.sh 파일을 업로드 후 실행
```

스크립트가 설치하는 것:
- Nginx
- Node.js 20 (fnm) + PM2
- Certbot (Let's Encrypt)
- UFW 80/443 허용
- `/opt/cryptoments/guide-ui` 디렉토리 생성

## 2단계: 최초 수동 배포 (SCP)

CI/CD 구성 전에 먼저 수동으로 올려서 동작 확인.

```bash
# 로컬 (cryptoments-admin/guide-ui 디렉토리에서 실행)
cd guide-ui
bash scripts/deploy.sh
```

또는 수동으로 단계별:

```bash
# (1) 파일 업로드
rsync -azv --delete \
  --exclude='node_modules' \
  --exclude='scripts' \
  -e "ssh -o ProxyJump=ubuntu@13.113.128.166" \
  ./ root@103.213.248.135:/opt/cryptoments/guide-ui/

# (2) widget 서버에서 npm install + PM2 시작
ssh -o ProxyJump=ubuntu@13.113.128.166 root@103.213.248.135

cd /opt/cryptoments/guide-ui
npm install --production
pm2 start server.js --name guide-ui
pm2 save
```

## 3단계: Nginx 설정 + SSL

```bash
# widget 서버에서 실행

# (1) Nginx 설정 복사 (HTTP only 먼저)
cat > /etc/nginx/sites-available/docs.cryptoments.cc.conf << 'EOF'
server {
    listen 80;
    server_name docs.cryptoments.cc;

    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    location / {
        proxy_pass http://127.0.0.1:8889;
        proxy_http_version 1.1;
        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) 심볼릭 링크 + Nginx 리로드
ln -sf /etc/nginx/sites-available/docs.cryptoments.cc.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

# (3) DNS 확인 (docs.cryptoments.cc → 103.213.248.135 A 레코드 필수)
# DNS 전파 확인 후 SSL 발급

# (4) Let's Encrypt SSL 발급
mkdir -p /var/www/certbot
certbot --nginx -d docs.cryptoments.cc --non-interactive --agree-tos -m gdudgh@gmail.com

# certbot이 자동으로 Nginx 설정에 SSL 블록 추가
# 이후 guide-ui/nginx/docs.cryptoments.cc.conf 의 전체 버전으로 교체 가능

# (5) 자동 갱신 확인
certbot renew --dry-run
```

## 4단계: GitLab CI/CD

`.gitlab-ci.yml`에 guide-ui 배포 job이 추가됨.

### 필요한 GitLab CI/CD Variables

기존 변수에 추가:

| Variable | 값 | Type |
|----------|-----|------|
| `WIDGET_HOST` | `103.213.248.135` | Variable |

기존 변수 (이미 설정되어 있어야 함):
- `SSH_PRIVATE_KEY` — deploy key (Type: File)
- `BASTION_KEY` — bastion PEM key (Type: File)
- `BASTION_HOST` — `13.113.128.166`
- `DEPLOY_USER` — `ubuntu`

### 트리거 조건

`main` 브랜치에 `guide-ui/**/*` 파일이 변경되면 자동 배포:
1. rsync로 파일 동기화 (node_modules, scripts 제외)
2. `npm install --production`
3. `pm2 reload guide-ui`
4. 헬스 체크 (`curl localhost:8889`)

## 파일 구조

```
guide-ui/
├── server.js              Express 서버 (port 8889)
├── package.json
├── spec-bundle.json       API 스펙 (Generator 생성)
├── api.html               Open API 가이드
├── widget.html            Widget API 가이드
├── webhook.html           Webhook 가이드
├── partner-guide.html     파트너 가이드
├── demo.html              데모 페이지
├── css/                   스타일시트
├── images/                이미지 리소스
├── nginx/                 Nginx 설정 파일
│   └── docs.cryptoments.cc.conf
└── scripts/
    ├── setup-server.sh    서버 초기 세팅 (최초 1회)
    └── deploy.sh          수동 배포 스크립트
```

## 운영

### PM2 명령어

```bash
pm2 status              # 프로세스 상태
pm2 logs guide-ui       # 로그 확인
pm2 restart guide-ui    # 재시작
pm2 reload guide-ui     # 무중단 재시작
```

### Nginx 명령어

```bash
nginx -t                    # 설정 검증
systemctl reload nginx      # 설정 리로드
tail -f /var/log/nginx/docs.cryptoments.cc.access.log
tail -f /var/log/nginx/docs.cryptoments.cc.error.log
```

### SSL 갱신

certbot이 systemd timer로 자동 갱신. 수동 확인:

```bash
certbot renew --dry-run
certbot certificates        # 인증서 만료일 확인
```

## DNS 설정

도메인 DNS에 A 레코드 추가 필요:

```
docs.cryptoments.cc  →  A  103.213.248.135
```

※ SSL 발급 전에 DNS 전파가 완료되어야 함.