Todo-Project/SYNOLOGY_DEPLOYMENT_GUIDE.md

# 🚀 Todo-Project 시놀로지 배포 가이드

## 📋 목차
1. [사전 준비](#사전-준비)
2. [시놀로지 환경 설정](#시놀로지-환경-설정)
3. [프로젝트 배포](#프로젝트-배포)
4. [환경 설정](#환경-설정)
5. [배포 실행](#배포-실행)
6. [접속 및 확인](#접속-및-확인)
7. [문제 해결](#문제-해결)
8. [유지보수](#유지보수)

---

## 🛠️ 사전 준비

### 시놀로지 요구사항
- **DSM 7.0 이상**
- **Docker 패키지 설치**
- **Container Manager 설치** (DSM 7.2+) 또는 **Docker 패키지** (DSM 7.1 이하)
- **최소 2GB RAM** (권장: 4GB 이상)
- **최소 5GB 저장공간**

### 필요한 포트
- **4000**: 프론트엔드 (웹 인터페이스)
- **9000**: 백엔드 API
- **5432**: PostgreSQL 데이터베이스

---

## 🏗️ 시놀로지 환경 설정

### 1. 디렉토리 구조 생성

SSH 또는 File Station을 통해 다음 디렉토리를 생성하세요:

```bash
# 이미지 업로드 저장소 (volume1 - 빠른 액세스)
sudo mkdir -p /volume1/todo-project/uploads
sudo chmod 755 /volume1/todo-project/uploads

# 설정 및 데이터베이스 저장소 (volume3)
sudo mkdir -p /volume3/docker/todo-project/config
sudo mkdir -p /volume3/docker/todo-project/postgres
sudo mkdir -p /volume3/docker/todo-project/app

# 권한 설정
sudo chown -R 1000:1000 /volume1/todo-project
sudo chown -R 999:999 /volume3/docker/todo-project/postgres
sudo chown -R 1000:1000 /volume3/docker/todo-project/config
```

### 2. 방화벽 설정 (선택사항)

DSM > 제어판 > 보안 > 방화벽에서 다음 포트를 허용하세요:
- **4000/TCP** (Todo-Project 웹 인터페이스)
- **9000/TCP** (API 서버)

---

## 📦 프로젝트 배포

### 방법 1: Git Clone (권장)

```bash
# 시놀로지에 SSH 접속 후
cd /volume3/docker/todo-project/app
git clone https://git.hyungi.net/hyungi/Todo-Project.git .

# 또는 특정 브랜치
git clone -b main https://git.hyungi.net/hyungi/Todo-Project.git .
```

### 방법 2: 파일 업로드

1. **로컬에서 프로젝트 압축**:
   ```bash
   tar -czf todo-project.tar.gz --exclude='.git' --exclude='node_modules' --exclude='__pycache__' .
   ```

2. **시놀로지로 업로드**:
   - File Station을 통해 `/volume3/docker/todo-project/app/`에 업로드
   - 압축 해제: `tar -xzf todo-project.tar.gz`

---

## ⚙️ 환경 설정

### 1. 환경 파일 설정

```bash
cd /volume3/docker/todo-project/app
cp env.synology.example .env
```

### 2. 환경 변수 수정

`.env` 파일을 편집하여 시놀로지 환경에 맞게 설정:

```bash
# 필수 설정 (반드시 변경!)
SECRET_KEY=your-very-long-and-random-secret-key-for-production
POSTGRES_PASSWORD=your-secure-database-password-123

# 포트 설정 (필요시 변경)
FRONTEND_PORT=4000
BACKEND_PORT=9000
DATABASE_PORT=5432

# 시놀로지 볼륨 경로 (기본값 사용 권장)
SYNOLOGY_UPLOADS_PATH=/volume1/todo-project/uploads
SYNOLOGY_CONFIG_PATH=/volume3/docker/todo-project/config
SYNOLOGY_DB_PATH=/volume3/docker/todo-project/postgres

# CORS 설정 (시놀로지 IP로 변경)
CORS_ORIGINS=["http://192.168.1.100:4000", "http://localhost:4000"]

# 프로덕션 설정
DEBUG=false
```

### 3. 마이그레이션 파일 복사

```bash
# 데이터베이스 초기화 스크립트 복사
cp -r backend/migrations/* /volume3/docker/todo-project/config/migrations/
```

---

## 🚀 배포 실행

### 1. Docker Compose 실행

```bash
cd /volume3/docker/todo-project/app

# 이미지 빌드 및 컨테이너 시작
docker-compose up -d --build

# 로그 확인
docker-compose logs -f
```

### 2. 컨테이너 상태 확인

```bash
# 컨테이너 상태 확인
docker-compose ps

# 개별 서비스 로그 확인
docker-compose logs backend
docker-compose logs frontend
docker-compose logs database
```

### 3. 헬스체크 확인

```bash
# 백엔드 API 확인
curl http://localhost:9000/health

# 데이터베이스 연결 확인
docker-compose exec database pg_isready -U todo_user -d todo_db
```

---

## 🌐 접속 및 확인

### 1. 웹 인터페이스 접속

브라우저에서 다음 주소로 접속:
- **로컬**: `http://시놀로지IP:4000`
- **예시**: `http://192.168.1.100:4000`

### 2. 초기 설정

1. **관리자 계정 생성**: 최초 접속 시 관리자 계정을 설정합니다
2. **로그인**: 생성한 계정으로 로그인
3. **기능 테스트**: 메모 작성, 이미지 업로드 등 기본 기능 확인

### 3. 리버스 프록시 설정 (선택사항)

DSM > 제어판 > 로그인 포털 > 고급 > 리버스 프록시에서:

```
소스:
- 프로토콜: HTTPS
- 호스트 이름: your-domain.synology.me
- 포트: 443
- 경로: /todo

대상:
- 프로토콜: HTTP
- 호스트 이름: localhost
- 포트: 4000
```

---

## 🔧 문제 해결

### 일반적인 문제들

#### 1. 컨테이너가 시작되지 않는 경우

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

# 개별 컨테이너 재시작
docker-compose restart backend
docker-compose restart database
```

#### 2. 데이터베이스 연결 오류

```bash
# 데이터베이스 컨테이너 상태 확인
docker-compose exec database pg_isready -U todo_user

# 환경 변수 확인
docker-compose exec backend env | grep DATABASE_URL
```

#### 3. 이미지 업로드 실패

```bash
# 업로드 디렉토리 권한 확인
ls -la /volume1/todo-project/uploads/

# 권한 수정
sudo chown -R 1000:1000 /volume1/todo-project/uploads/
sudo chmod -R 755 /volume1/todo-project/uploads/
```

#### 4. CORS 오류

`.env` 파일에서 `CORS_ORIGINS`에 시놀로지 IP 추가:
```bash
CORS_ORIGINS=["http://192.168.1.100:4000", "https://your-domain.synology.me"]
```

### 로그 확인 명령어

```bash
# 전체 로그
docker-compose logs -f

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

# 최근 로그만
docker-compose logs --tail=50 backend
```

---

## 🔄 유지보수

### 업데이트

```bash
cd /volume3/docker/todo-project/app

# Git으로 최신 코드 가져오기
git pull origin main

# 컨테이너 재빌드 및 재시작
docker-compose down
docker-compose up -d --build
```

### 백업

```bash
# 데이터베이스 백업
docker-compose exec database pg_dump -U todo_user todo_db > backup_$(date +%Y%m%d).sql

# 업로드된 이미지 백업
tar -czf uploads_backup_$(date +%Y%m%d).tar.gz /volume1/todo-project/uploads/
```

### 모니터링

```bash
# 컨테이너 리소스 사용량
docker stats

# 디스크 사용량
df -h /volume1/todo-project/
df -h /volume3/docker/todo-project/
```

---

## 📞 지원

문제가 발생하면 다음을 확인하세요:

1. **로그 파일**: `docker-compose logs`
2. **포트 충돌**: `netstat -tulpn | grep :4000`
3. **디스크 공간**: `df -h`
4. **메모리 사용량**: `free -m`

---

## 🎯 성능 최적화 팁

### 1. 볼륨 배치 최적화
- **이미지 저장소**: volume1 (SSD 권장) - 빠른 액세스
- **데이터베이스**: volume3 (HDD 가능) - 대용량 저장

### 2. 메모리 설정
- 최소 2GB RAM 할당
- PostgreSQL shared_buffers 조정

### 3. 네트워크 최적화
- 리버스 프록시 사용으로 HTTPS 적용
- CDN 사용 고려 (정적 파일)

---

**🎉 축하합니다! Todo-Project가 시놀로지에 성공적으로 배포되었습니다!**