ERP-node/deploy/onpremise/README.md

# Vexplor 온프레미스(공장) 배포 가이드

## 개요

이 가이드는 Vexplor를 **공장 내부 서버(온프레미스)**에 배포하는 방법을 설명합니다.

**Watchtower**를 사용하여 Harbor에 새 이미지가 푸시되면 **자동으로 업데이트**됩니다.

---

## 사전 요구사항

### 서버 요구사항

| 항목 | 최소 사양 | 권장 사양 |
| :--- | :--- | :--- |
| OS | Ubuntu 20.04+ | Ubuntu 22.04 LTS |
| CPU | 4 Core | 8 Core |
| RAM | 8 GB | 16 GB |
| Disk | 50 GB | 100 GB SSD |
| Network | Harbor 접근 가능 | - |

### 필수 소프트웨어

```bash
# Docker 설치 확인
docker --version    # 20.10 이상

# Docker Compose 설치 확인
docker compose version   # v2.0 이상
```

---

## 1단계: 초기 설정

### 1.1 배포 폴더 생성

```bash
# 배포 폴더 생성
sudo mkdir -p /opt/vexplor
cd /opt/vexplor

# 파일 복사 (또는 git clone)
# deploy/onpremise/ 폴더의 내용을 복사
```

### 1.2 환경 변수 설정

```bash
# 예제 파일 복사
cp env.example .env

# 편집
nano .env
```

**필수 수정 항목:**

```bash
# 서버 IP (이 서버의 실제 IP)
SERVER_IP=192.168.0.100

# 회사 코드
COMPANY_CODE=SPIFOX

# DB 비밀번호 (강력한 비밀번호 설정)
DB_PASSWORD=MySecurePassword123!

# JWT 시크릿 (32자 이상)
JWT_SECRET=your-super-secret-jwt-key-minimum-32-chars

# Harbor 인증 정보
HARBOR_USER=your_username
HARBOR_PASSWORD=your_password
```

### 1.3 Harbor 레지스트리 로그인

Watchtower가 이미지를 당겨올 수 있도록 Docker 로그인이 필요합니다.

```bash
# Harbor 로그인
docker login harbor.wace.me

# Username: (입력)
# Password: (입력)

# 로그인 성공 확인
cat ~/.docker/config.json
```

---

## 2단계: 서비스 실행

### 2.1 서비스 시작

```bash
cd /opt/vexplor

# 이미지 다운로드 & 실행
docker compose up -d

# 상태 확인
docker compose ps
```

### 2.2 정상 동작 확인

```bash
# 모든 컨테이너 Running 상태 확인
docker compose ps

# 로그 확인
docker compose logs -f

# 개별 서비스 로그
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f watchtower
```

### 2.3 웹 접속 테스트

```
프론트엔드: http://SERVER_IP:80
백엔드 API: http://SERVER_IP:3001/health
```

---

## 3단계: 자동 업데이트 확인

### Watchtower 동작 확인

```bash
# Watchtower 로그 확인
docker compose logs -f watchtower
```

**정상 로그 예시:**

```
watchtower  | time="2024-12-28T10:00:00+09:00" level=info msg="Checking for updates..."
watchtower  | time="2024-12-28T10:00:05+09:00" level=info msg="Found new image harbor.wace.me/vexplor/vexplor-backend:latest"
watchtower  | time="2024-12-28T10:00:10+09:00" level=info msg="Stopping container vexplor-backend"
watchtower  | time="2024-12-28T10:00:15+09:00" level=info msg="Starting container vexplor-backend"
```

### 업데이트 주기 변경

```bash
# .env 파일에서 변경
UPDATE_INTERVAL=3600  # 1시간마다 확인

# 변경 후 watchtower 재시작
docker compose restart watchtower
```

---

## 운영 가이드

### 서비스 관리 명령어

```bash
# 모든 서비스 상태 확인
docker compose ps

# 모든 서비스 중지
docker compose stop

# 모든 서비스 시작
docker compose start

# 모든 서비스 재시작
docker compose restart

# 모든 서비스 삭제 (데이터 유지)
docker compose down

# 모든 서비스 삭제 + 볼륨 삭제 (주의: 데이터 삭제됨!)
docker compose down -v
```

### 로그 확인

```bash
# 전체 로그 (실시간)
docker compose logs -f

# 특정 서비스 로그
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f database

# 최근 100줄만
docker compose logs --tail=100 backend
```

### 수동 업데이트 (긴급 시)

자동 업데이트를 기다리지 않고 즉시 업데이트하려면:

```bash
# 최신 이미지 다운로드
docker compose pull

# 재시작
docker compose up -d
```

### 특정 버전으로 롤백

```bash
# .env 파일에서 버전 지정
IMAGE_TAG=v1.0.0

# 재시작
docker compose up -d
```

---

## 백업 가이드

### DB 백업

```bash
# 백업 디렉토리 생성
mkdir -p /opt/vexplor/backups

# PostgreSQL 백업
docker compose exec database pg_dump -U vexplor vexplor > /opt/vexplor/backups/backup_$(date +%Y%m%d_%H%M%S).sql
```

### 업로드 파일 백업

```bash
# 볼륨 위치 확인
docker volume inspect vexplor_backend_uploads

# 또는 직접 복사
docker cp vexplor-backend:/app/uploads /opt/vexplor/backups/uploads_$(date +%Y%m%d)
```

### 자동 백업 스크립트 (Cron)

```bash
# crontab 편집
crontab -e

# 매일 새벽 3시 DB 백업
0 3 * * * docker compose -f /opt/vexplor/docker-compose.yml exec -T database pg_dump -U vexplor vexplor > /opt/vexplor/backups/backup_$(date +\%Y\%m\%d).sql
```

---

## 문제 해결

### 컨테이너가 시작되지 않음

```bash
# 로그 확인
docker compose logs backend

# 일반적인 원인:
# 1. 환경 변수 누락 → .env 파일 확인
# 2. 포트 충돌 → netstat -tlnp | grep 3001
# 3. 메모리 부족 → free -h
```

### DB 연결 실패

```bash
# DB 컨테이너 상태 확인
docker compose logs database

# DB 직접 접속 테스트
docker compose exec database psql -U vexplor -d vexplor -c "SELECT 1"
```

### Watchtower가 업데이트하지 않음

```bash
# Watchtower 로그 확인
docker compose logs watchtower

# Harbor 인증 확인
docker pull harbor.wace.me/vexplor/vexplor-backend:latest

# 라벨 확인 (라벨이 있는 컨테이너만 업데이트)
docker inspect vexplor-backend | grep watchtower
```

### 디스크 공간 부족

```bash
# 사용하지 않는 이미지/컨테이너 정리
docker system prune -a

# 오래된 로그 정리
docker compose logs --tail=0 backend  # 로그 초기화
```

---

## 보안 권장사항

1. **방화벽 설정**: 필요한 포트(80, 3001)만 개방
2. **SSL/TLS**: Nginx 리버스 프록시 + Let's Encrypt 적용 권장
3. **정기 백업**: 최소 주 1회 DB 백업
4. **로그 모니터링**: 비정상 접근 감시

---

## 연락처

배포 관련 문의: [담당자 이메일]