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 접근 가능 | - |
필수 소프트웨어
# Docker 설치 확인
docker --version # 20.10 이상
# Docker Compose 설치 확인
docker compose version # v2.0 이상
1단계: 초기 설정
1.1 배포 폴더 생성
# 배포 폴더 생성
sudo mkdir -p /opt/vexplor
cd /opt/vexplor
# 파일 복사 (또는 git clone)
# deploy/onpremise/ 폴더의 내용을 복사
1.2 환경 변수 설정
# 예제 파일 복사
cp env.example .env
# 편집
nano .env
필수 수정 항목:
# 서버 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 로그인이 필요합니다.
# Harbor 로그인
docker login harbor.wace.me
# Username: (입력)
# Password: (입력)
# 로그인 성공 확인
cat ~/.docker/config.json
2단계: 서비스 실행
2.1 서비스 시작
cd /opt/vexplor
# 이미지 다운로드 & 실행
docker compose up -d
# 상태 확인
docker compose ps
2.2 정상 동작 확인
# 모든 컨테이너 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 동작 확인
# 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"
업데이트 주기 변경
# .env 파일에서 변경
UPDATE_INTERVAL=3600 # 1시간마다 확인
# 변경 후 watchtower 재시작
docker compose restart watchtower
운영 가이드
서비스 관리 명령어
# 모든 서비스 상태 확인
docker compose ps
# 모든 서비스 중지
docker compose stop
# 모든 서비스 시작
docker compose start
# 모든 서비스 재시작
docker compose restart
# 모든 서비스 삭제 (데이터 유지)
docker compose down
# 모든 서비스 삭제 + 볼륨 삭제 (주의: 데이터 삭제됨!)
docker compose down -v
로그 확인
# 전체 로그 (실시간)
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
수동 업데이트 (긴급 시)
자동 업데이트를 기다리지 않고 즉시 업데이트하려면:
# 최신 이미지 다운로드
docker compose pull
# 재시작
docker compose up -d
특정 버전으로 롤백
# .env 파일에서 버전 지정
IMAGE_TAG=v1.0.0
# 재시작
docker compose up -d
백업 가이드
DB 백업
# 백업 디렉토리 생성
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
업로드 파일 백업
# 볼륨 위치 확인
docker volume inspect vexplor_backend_uploads
# 또는 직접 복사
docker cp vexplor-backend:/app/uploads /opt/vexplor/backups/uploads_$(date +%Y%m%d)
자동 백업 스크립트 (Cron)
# 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
문제 해결
컨테이너가 시작되지 않음
# 로그 확인
docker compose logs backend
# 일반적인 원인:
# 1. 환경 변수 누락 → .env 파일 확인
# 2. 포트 충돌 → netstat -tlnp | grep 3001
# 3. 메모리 부족 → free -h
DB 연결 실패
# DB 컨테이너 상태 확인
docker compose logs database
# DB 직접 접속 테스트
docker compose exec database psql -U vexplor -d vexplor -c "SELECT 1"
Watchtower가 업데이트하지 않음
# Watchtower 로그 확인
docker compose logs watchtower
# Harbor 인증 확인
docker pull harbor.wace.me/vexplor/vexplor-backend:latest
# 라벨 확인 (라벨이 있는 컨테이너만 업데이트)
docker inspect vexplor-backend | grep watchtower
디스크 공간 부족
# 사용하지 않는 이미지/컨테이너 정리
docker system prune -a
# 오래된 로그 정리
docker compose logs --tail=0 backend # 로그 초기화
보안 권장사항
- 방화벽 설정: 필요한 포트(80, 3001)만 개방
- SSL/TLS: Nginx 리버스 프록시 + Let's Encrypt 적용 권장
- 정기 백업: 최소 주 1회 DB 백업
- 로그 모니터링: 비정상 접근 감시
연락처
배포 관련 문의: [담당자 이메일]