DEPLOYMENT_GUIDE.md

# DigitalOcean 배포 가이드

## 목차
1. [사전 준비사항](#사전-준비사항)
2. [Droplet 생성](#droplet-생성)
3. [서버 초기 설정](#서버-초기-설정)
4. [Ollama 설치 및 설정](#ollama-설치-및-설정)
5. [프로젝트 배포](#프로젝트-배포)
6. [Nginx 설정](#nginx-설정)
7. [SSL 인증서 설정](#ssl-인증서-설정)
8. [systemd 서비스 설정](#systemd-서비스-설정)
9. [백업 설정](#백업-설정)
10. [모니터링 설정](#모니터링-설정)
11. [문제 해결](#문제-해결)

---

## 사전 준비사항

### 필요한 것들:
- DigitalOcean 계정 (https://www.digitalocean.com/)
- 도메인 (선택사항, 있으면 좋음)
- GitHub/GitLab 저장소 (또는 프로젝트 파일)
- Gemini API 키 (사용하는 경우)

### 예상 비용:
- Droplet (8GB RAM): $48/월
- 도메인: $10-15/년 (선택사항)
- 총: 약 $48-50/월

---

## Droplet 생성

### 1. DigitalOcean 로그인 및 Droplet 생성

1. https://www.digitalocean.com/ 접속 및 로그인
2. "Create" → "Droplets" 클릭
3. 다음 설정 선택:

**이미지:**
- Ubuntu 22.04 (LTS) x64

**플랜:**
- Regular (일반)
- 8GB RAM / 4 vCPUs / 160GB SSD ($48/월) **추천**
- 또는 4GB RAM / 2 vCPUs / 80GB SSD ($24/월) - 최소 사양

**데이터센터 지역:**
- Singapore (싱가포르) - 한국에서 가장 가까움
- 또는 Seoul (서울) - 가능한 경우

**인증:**
- SSH 키 추가 (권장)
- 또는 비밀번호 설정

**추가 옵션:**
- Monitoring 활성화
- Backups 활성화 (선택사항, 추가 비용)

4. "Create Droplet" 클릭

### 2. 서버 접속 정보 확인

생성 완료 후 이메일로 IP 주소와 접속 정보를 받게 됩니다.
- IP 주소: 예) `123.45.67.89`
- Root 비밀번호 (비밀번호 방식인 경우)

---

## 서버 초기 설정

### 1. SSH로 서버 접속

**Windows (PowerShell):**
```powershell
ssh root@YOUR_SERVER_IP
```

**Mac/Linux:**
```bash
ssh root@YOUR_SERVER_IP
```

### 2. 시스템 업데이트

```bash
# 시스템 업데이트
apt update && apt upgrade -y

# 필수 패키지 설치
apt install -y \
    python3 \
    python3-pip \
    python3-venv \
    git \
    curl \
    wget \
    nginx \
    certbot \
    python3-certbot-nginx \
    supervisor \
    ufw \
    htop \
    nano \
    build-essential \
    libssl-dev \
    libffi-dev \
    python3-dev
```

### 3. 방화벽 설정

```bash
# UFW 방화벽 활성화
ufw allow OpenSSH
ufw allow 'Nginx Full'
ufw allow 11434/tcp  # Ollama 포트
ufw enable
ufw status
```

### 4. 사용자 생성 (선택사항, 보안을 위해 권장)

```bash
# 새 사용자 생성
adduser deploy
usermod -aG sudo deploy

# SSH 키 복사 (로컬에서)
# Windows: type C:\Users\YourName\.ssh\id_rsa.pub | ssh root@YOUR_SERVER_IP "cat >> /home/deploy/.ssh/authorized_keys"
# Mac/Linux: ssh-copy-id deploy@YOUR_SERVER_IP

# deploy 사용자로 전환
su - deploy
```

---

## Ollama 설치 및 설정

### 1. Ollama 설치

```bash
# Ollama 설치 스크립트 실행
curl -fsSL https://ollama.com/install.sh | sh

# Ollama 서비스 확인
systemctl status ollama

# Ollama 자동 시작 설정
systemctl enable ollama
```

### 2. Ollama 모델 다운로드

```bash
# 사용할 모델 다운로드 (예: llama2)
ollama pull llama2

# 또는 다른 모델
# ollama pull mistral
# ollama pull qwen

# 설치된 모델 확인
ollama list
```

### 3. Ollama 서비스 확인

```bash
# Ollama가 정상 작동하는지 확인
curl http://localhost:11434/api/tags

# 서비스 재시작
systemctl restart ollama
```

---

## 프로젝트 배포

### 1. 프로젝트 디렉토리 생성

```bash
# 홈 디렉토리로 이동
cd ~

# 프로젝트 디렉토리 생성
mkdir -p /var/www
cd /var/www

# 소유권 설정 (deploy 사용자 사용 시)
# chown -R deploy:deploy /var/www
```

### 2. 프로젝트 파일 업로드

**방법 1: Git 사용 (권장)**

```bash
# Git 저장소 클론
git clone YOUR_REPOSITORY_URL "soy-nv-ai"
cd soy-nv-ai

# 또는 직접 파일 업로드
# scp -r "D:\SOY NV AI\*" deploy@YOUR_SERVER_IP:/var/www/soy-nv-ai/
```

**방법 2: SCP로 파일 전송 (Windows PowerShell)**

```powershell
# 프로젝트 폴더 전체 업로드
scp -r "D:\SOY NV AI\*" deploy@YOUR_SERVER_IP:/var/www/soy-nv-ai/
```

### 3. 가상환경 설정

```bash
cd /var/www/soy-nv-ai

# 가상환경 생성
python3 -m venv venv

# 가상환경 활성화
source venv/bin/activate

# pip 업그레이드
pip install --upgrade pip

# 의존성 설치
pip install -r requirements.txt

# 설치 확인
python --version
pip list
```

### 4. 환경 변수 설정

```bash
# .env 파일 생성
nano .env
```

**.env 파일 내용:**
```env
# Flask 설정
SECRET_KEY=your-super-secret-key-change-this-in-production
FLASK_ENV=production
FLASK_DEBUG=False

# 데이터베이스
DATABASE_URL=sqlite:///var/www/soy-nv-ai/instance/finance_analysis.db

# Ollama 설정
OLLAMA_BASE_URL=http://localhost:11434

# Gemini API (사용하는 경우)
GEMINI_API_KEY=your-gemini-api-key-here

# 업로드 폴더
UPLOAD_FOLDER=/var/www/soy-nv-ai/uploads
VECTOR_DB_PATH=/var/www/soy-nv-ai/vector_db
KNOWLEDGE_GRAPH_PATH=/var/www/soy-nv-ai/knowledge_graphs

# 임베딩 모델
EMBEDDING_MODEL_NAME=sentence-transformers/all-MiniLM-L6-v2
RERANKER_MODEL_NAME=BAAI/bge-reranker-base
```

**SECRET_KEY 생성 방법:**
```bash
python3 -c "import secrets; print(secrets.token_hex(32))"
```

### 5. 디렉토리 권한 설정

```bash
# 필요한 디렉토리 생성
mkdir -p instance uploads vector_db knowledge_graphs logs

# 권한 설정
chmod -R 755 /var/www/soy-nv-ai
chown -R deploy:deploy /var/www/soy-nv-ai  # deploy 사용자 사용 시

# 업로드 폴더 쓰기 권한
chmod -R 775 uploads
chmod -R 775 instance
chmod -R 775 vector_db
```

### 6. 애플리케이션 테스트

```bash
# 가상환경 활성화
source venv/bin/activate

# 데이터베이스 초기화
python -c "from app import create_app; app = create_app(); app.app_context().push(); from app.database import db; db.create_all()"

# 서버 테스트 실행
python run.py
```

**다른 터미널에서 테스트:**
```bash
curl http://localhost:5001
```

정상 작동하면 `Ctrl+C`로 중지합니다.

---

## Nginx 설정

### 1. Nginx 설정 파일 생성

```bash
sudo nano /etc/nginx/sites-available/soy-nv-ai
```

**설정 파일 내용:**
```nginx
server {
    listen 80;
    server_name YOUR_DOMAIN.com www.YOUR_DOMAIN.com;
    # 또는 IP 주소만 사용: server_name YOUR_SERVER_IP;

    # 로그 설정
    access_log /var/log/nginx/soy-nv-ai-access.log;
    error_log /var/log/nginx/soy-nv-ai-error.log;

    # 클라이언트 최대 업로드 크기 (100MB)
    client_max_body_size 100M;

    # 프록시 설정
    location / {
        proxy_pass http://127.0.0.1:5001;
        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;
        
        # WebSocket 지원 (필요한 경우)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        # 타임아웃 설정 (AI 응답이 오래 걸릴 수 있음)
        proxy_connect_timeout 600s;
        proxy_send_timeout 600s;
        proxy_read_timeout 600s;
    }

    # 정적 파일 직접 제공 (선택사항)
    location /static {
        alias /var/www/soy-nv-ai/static;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}
```

### 2. 설정 파일 활성화

```bash
# 심볼릭 링크 생성
sudo ln -s /etc/nginx/sites-available/soy-nv-ai /etc/nginx/sites-enabled/

# 기본 설정 비활성화 (선택사항)
sudo rm /etc/nginx/sites-enabled/default

# Nginx 설정 테스트
sudo nginx -t

# Nginx 재시작
sudo systemctl restart nginx
sudo systemctl enable nginx
```

### 3. 방화벽 확인

```bash
# Nginx 포트 확인
sudo ufw status
```

---

## SSL 인증서 설정

### 1. Let's Encrypt SSL 인증서 설치

**도메인이 있는 경우:**

```bash
# Certbot으로 SSL 인증서 발급
sudo certbot --nginx -d YOUR_DOMAIN.com -d www.YOUR_DOMAIN.com

# 자동 갱신 테스트
sudo certbot renew --dry-run
```

**도메인이 없는 경우 (IP만 사용):**
- SSL 인증서는 발급할 수 없습니다
- HTTP로만 접속 가능 (보안상 권장하지 않음)
- 내부 네트워크나 VPN 사용 고려

### 2. 자동 갱신 설정

```bash
# Certbot 자동 갱신은 이미 systemd 타이머로 설정됨
sudo systemctl status certbot.timer
```

---

## systemd 서비스 설정

### 1. 서비스 파일 생성

```bash
sudo nano /etc/systemd/system/soy-nv-ai.service
```

**서비스 파일 내용:**
```ini
[Unit]
Description=SOY NV AI Flask Application
After=network.target ollama.service

[Service]
Type=simple
User=deploy
Group=deploy
WorkingDirectory=/var/www/soy-nv-ai
Environment="PATH=/var/www/soy-nv-ai/venv/bin"
Environment="FLASK_ENV=production"
ExecStart=/var/www/soy-nv-ai/venv/bin/python /var/www/soy-nv-ai/run.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=soy-nv-ai

# 리소스 제한 (선택사항)
LimitNOFILE=65535
MemoryLimit=6G

[Install]
WantedBy=multi-user.target
```

### 2. 서비스 활성화 및 시작

```bash
# systemd 재로드
sudo systemctl daemon-reload

# 서비스 활성화 (부팅 시 자동 시작)
sudo systemctl enable soy-nv-ai

# 서비스 시작
sudo systemctl start soy-nv-ai

# 서비스 상태 확인
sudo systemctl status soy-nv-ai

# 로그 확인
sudo journalctl -u soy-nv-ai -f
```

### 3. 서비스 관리 명령어

```bash
# 서비스 시작
sudo systemctl start soy-nv-ai

# 서비스 중지
sudo systemctl stop soy-nv-ai

# 서비스 재시작
sudo systemctl restart soy-nv-ai

# 서비스 상태 확인
sudo systemctl status soy-nv-ai

# 로그 확인
sudo journalctl -u soy-nv-ai -n 50
sudo journalctl -u soy-nv-ai -f  # 실시간 로그
```

---

## 백업 설정

### 1. 백업 스크립트 생성

```bash
nano /var/www/soy-nv-ai/backup.sh
```

**백업 스크립트 내용:**
```bash
#!/bin/bash

# 백업 디렉토리
BACKUP_DIR="/var/backups/soy-nv-ai"
DATE=$(date +%Y%m%d_%H%M%S)

# 백업 디렉토리 생성
mkdir -p $BACKUP_DIR

# 데이터베이스 백업
cp /var/www/soy-nv-ai/instance/finance_analysis.db $BACKUP_DIR/db_$DATE.db

# 업로드 파일 백업
tar -czf $BACKUP_DIR/uploads_$DATE.tar.gz /var/www/soy-nv-ai/uploads

# 벡터 DB 백업
tar -czf $BACKUP_DIR/vector_db_$DATE.tar.gz /var/www/soy-nv-ai/vector_db

# 오래된 백업 삭제 (30일 이상)
find $BACKUP_DIR -type f -mtime +30 -delete

echo "Backup completed: $DATE"
```

### 2. 백업 스크립트 실행 권한 부여

```bash
chmod +x /var/www/soy-nv-ai/backup.sh
```

### 3. Cron으로 자동 백업 설정

```bash
# Crontab 편집
crontab -e

# 매일 새벽 2시에 백업 실행
0 2 * * * /var/www/soy-nv-ai/backup.sh >> /var/log/soy-nv-ai-backup.log 2>&1
```

---

## 모니터링 설정

### 1. 서버 리소스 모니터링

```bash
# htop 설치 (이미 설치됨)
htop

# 또는 기본 top
top
```

### 2. 디스크 사용량 확인

```bash
df -h
du -sh /var/www/soy-nv-ai/*
```

### 3. 외부 모니터링 서비스 (선택사항)

**Uptime Robot (무료):**
- https://uptimerobot.com/
- 5분마다 서버 상태 확인
- 다운타임 알림

**Pingdom:**
- https://www.pingdom.com/
- 더 상세한 모니터링

---

## 문제 해결

### 1. 서비스가 시작되지 않는 경우

```bash
# 서비스 상태 확인
sudo systemctl status soy-nv-ai

# 로그 확인
sudo journalctl -u soy-nv-ai -n 100

# 수동 실행으로 오류 확인
cd /var/www/soy-nv-ai
source venv/bin/activate
python run.py
```

### 2. Ollama 연결 오류

```bash
# Ollama 서비스 상태 확인
sudo systemctl status ollama

# Ollama 재시작
sudo systemctl restart ollama

# Ollama 로그 확인
sudo journalctl -u ollama -n 50

# Ollama 포트 확인
netstat -tlnp | grep 11434
```

### 3. Nginx 오류

```bash
# Nginx 설정 테스트
sudo nginx -t

# Nginx 로그 확인
sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/nginx/soy-nv-ai-error.log
```

### 4. 메모리 부족

```bash
# 메모리 사용량 확인
free -h

# 프로세스별 메모리 사용량
ps aux --sort=-%mem | head

# 필요시 서버 재시작
sudo reboot
```

### 5. 디스크 공간 부족

```bash
# 디스크 사용량 확인
df -h

# 큰 파일 찾기
du -h /var/www/soy-nv-ai | sort -rh | head -20

# 로그 파일 정리
sudo journalctl --vacuum-time=7d  # 7일 이상 된 로그 삭제
```

### 6. 포트 충돌

```bash
# 포트 사용 확인
sudo netstat -tlnp | grep 5001
sudo lsof -i :5001

# 프로세스 종료
sudo kill -9 PID
```

---

## 배포 후 체크리스트

- [ ] 서버 접속 확인
- [ ] Ollama 설치 및 모델 다운로드 확인
- [ ] 프로젝트 파일 업로드 완료
- [ ] 가상환경 설정 및 의존성 설치 완료
- [ ] 환경 변수 설정 완료
- [ ] 데이터베이스 초기화 완료
- [ ] Nginx 설정 및 테스트 완료
- [ ] SSL 인증서 설치 완료 (도메인 있는 경우)
- [ ] systemd 서비스 설정 및 자동 시작 확인
- [ ] 백업 스크립트 설정 완료
- [ ] 방화벽 설정 확인
- [ ] 웹사이트 접속 테스트
- [ ] 파일 업로드 기능 테스트
- [ ] AI 채팅 기능 테스트
- [ ] 모니터링 설정 완료

---

## 유용한 명령어 모음

```bash
# 서비스 관리
sudo systemctl start/stop/restart/status soy-nv-ai
sudo systemctl start/stop/restart/status ollama
sudo systemctl start/stop/restart/status nginx

# 로그 확인
sudo journalctl -u soy-nv-ai -f
sudo journalctl -u ollama -f
sudo tail -f /var/log/nginx/soy-nv-ai-error.log

# 프로세스 확인
ps aux | grep python
ps aux | grep ollama

# 포트 확인
netstat -tlnp | grep 5001
netstat -tlnp | grep 11434

# 디스크/메모리 확인
df -h
free -h
htop

# 백업 실행
/var/www/soy-nv-ai/backup.sh
```

---

## 추가 최적화

### 1. Gunicorn 사용 (선택사항)

Flask 개발 서버 대신 Gunicorn 사용 권장:

```bash
# Gunicorn 설치
pip install gunicorn

# systemd 서비스 파일 수정
ExecStart=/var/www/soy-nv-ai/venv/bin/gunicorn \
    --bind 127.0.0.1:5001 \
    --workers 4 \
    --timeout 600 \
    --access-logfile - \
    --error-logfile - \
    run:app
```

### 2. 데이터베이스 마이그레이션

SQLite 대신 PostgreSQL 사용 고려 (대규모 사용자):

```bash
# PostgreSQL 설치
sudo apt install postgresql postgresql-contrib

# requirements.txt에 추가
# psycopg2-binary==2.9.9
```

### 3. CDN 설정

Cloudflare 사용 (무료):
- https://www.cloudflare.com/
- 도메인 DNS를 Cloudflare로 변경
- 캐싱 및 DDoS 보호

---

## 지원 및 도움말

문제가 발생하면:
1. 서버 로그 확인
2. Nginx 로그 확인
3. systemd 서비스 로그 확인
4. DigitalOcean 문서 참조: https://docs.digitalocean.com/

---

**배포 완료 후 웹사이트 접속:**
- HTTP: http://YOUR_SERVER_IP 또는 http://YOUR_DOMAIN.com
- HTTPS: https://YOUR_DOMAIN.com (SSL 설정 후)

축하합니다! 배포가 완료되었습니다! 🎉