sundol/docs/operation-manual.md

# Sundol 운영 매뉴얼

## 프로세스 구성

pm2로 3개 프로세스를 관리한다.

| id | name | 설명 |
|----|------|------|
| 0 | pdf-ocr | PDF OCR 서비스 |
| 1 | sundol-backend | Spring Boot 백엔드 |
| 2 | sundol-frontend | Next.js 프론트엔드 |

## pm2 기본 명령어

```bash
# 프로세스 목록 확인
pm2 list

# 로그 확인
pm2 logs sundol-backend
pm2 logs sundol-frontend
pm2 logs pdf-ocr

# 특정 프로세스 재시작
pm2 restart sundol-backend
pm2 restart sundol-frontend
pm2 restart pdf-ocr

# 전체 재시작
pm2 restart all

# 프로세스 중지
pm2 stop sundol-backend

# 프로세스 삭제
pm2 delete sundol-backend
```

## 백엔드 시작 스크립트

파일: `start-backend.sh`

```bash
#!/bin/bash
set -a
source /home/opc/sundol/.env
set +a

JAVA_HOME=${JAVA_HOME:-/usr/lib/jvm/java-21}
export JAVA_HOME

# Playwright 브라우저 경로
export PLAYWRIGHT_BROWSERS_PATH=/home/opc/.cache/ms-playwright
export PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1

# Playwright head 모드용 디스플레이
# :99 = Xvfb 가상 디스플레이 (브라우저 안 보임)
# :1  = VNC 디스플레이 (VNC에서 브라우저 보임)
export DISPLAY=:99

# Xvfb 가상 디스플레이 시작 (DISPLAY=:99일 때만 필요)
if ! pgrep -x Xvfb > /dev/null; then
    Xvfb :99 -screen 0 1280x720x24 -nolisten tcp &
    sleep 1
fi

BACKEND_DIR=/home/opc/sundol/sundol-backend
exec $JAVA_HOME/bin/java -cp "$BACKEND_DIR/target/classes:$BACKEND_DIR/target/dependency/*" com.sundol.SundolApplication
```

### DISPLAY 설정 가이드

| DISPLAY 값 | 용도 |
|-------------|------|
| `:99` | Xvfb 가상 디스플레이. 브라우저가 백그라운드에서 동작 (기본값) |
| `:1` | VNC 디스플레이. VNC 접속 시 Playwright 브라우저가 화면에 보임 (디버깅용) |

VNC에서 Playwright 브라우저를 직접 보려면:
1. `start-backend.sh`에서 `export DISPLAY=:1`로 변경
2. `pm2 restart sundol-backend`

## 백엔드 빌드

```bash
cd /home/opc/sundol/sundol-backend
export JAVA_HOME=/usr/lib/jvm/java-21
set -a && source /home/opc/sundol/.env && set +a
mvn package -q -DskipTests
```

> 컴파일만: `mvn compile` (위 환경변수 동일)

## 프론트엔드 빌드/배포

```bash
cd /home/opc/sundol/sundol-frontend
bash build.sh
```

> `.env`에 `NEXT_PUBLIC_GOOGLE_CLIENT_ID`, `NEXT_PUBLIC_API_URL` 필수.

## 배포 절차

1. 코드 변경 및 빌드
2. `pm2 restart sundol-backend` (또는 sundol-frontend)
3. `pm2 logs sundol-backend` 로 정상 기동 확인
4. `git push origin main`

## DB 접속 (Oracle Autonomous DB)

```bash
set -a && source /home/opc/sundol/.env && set +a
/home/opc/sqlcl/bin/sql ${ORACLE_USERNAME}/${ORACLE_PASSWORD}@${ORACLE_TNS_NAME}?TNS_ADMIN=${ORACLE_WALLET_PATH}
```

## Playwright 관련

- 브라우저 경로: `/home/opc/.cache/ms-playwright`
- WebCrawlerService: Playwright head 모드 (`setHeadless(false)`)
- YouTubeTranscriptService: Playwright head 모드 (`setHeadless(false)`)
- head 모드 사용 시 DISPLAY 환경변수 필수

## Playwright 의존 라이브러리

Playwright Chromium 실행에 필요한 시스템 라이브러리:

```bash
sudo dnf install -y libicu woff2 harfbuzz-icu libjpeg-turbo libwebp enchant2 hyphen libffi
```

> `libx264`는 WebKit 전용이므로 Chromium만 사용할 경우 불필요.
> 로그에 `validateDependenciesLinux` 에러가 나오면 위 패키지 설치 확인.

### Xvfb vs VNC 디스플레이

| 모드 | DISPLAY | 설명 |
|------|---------|------|
| Xvfb (운영) | `:99` | 가상 프레임버퍼. 화면 없이 백그라운드 동작 |
| VNC (디버깅) | `:1` | VNC 접속 시 브라우저가 화면에 보임 |

Xvfb 모드로 되돌리려면 `start-backend.sh`에서:
```bash
export DISPLAY=:99
if ! pgrep -x Xvfb > /dev/null; then
    Xvfb :99 -screen 0 1280x720x24 -nolisten tcp &
    sleep 1
fi
```

## 트러블슈팅

### 백엔드가 안 뜰 때

```bash
pm2 logs sundol-backend --lines 50
```

### Playwright 브라우저가 안 열릴 때

```bash
# DISPLAY 확인
echo $DISPLAY

# Xvfb 실행 여부 확인
pgrep -x Xvfb

# VNC 실행 여부 확인
vncserver -list

# Playwright 브라우저 설치 확인
ls /home/opc/.cache/ms-playwright/
```

### pm2 프로세스가 계속 재시작될 때

```bash
# 재시작 횟수 확인 (↺ 컬럼)
pm2 list

# 에러 로그 확인
pm2 logs sundol-backend --err --lines 100
```