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을 통해 다음 디렉토리를 생성하세요:

# 이미지 업로드 저장소 (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 (권장)

# 시놀로지에 SSH 접속 후
cd /volume3/docker/todo-project/app
git clone https://github.com/your-username/Todo-Project.git .

# 또는 특정 브랜치
git clone -b main https://github.com/your-username/Todo-Project.git .

방법 2: 파일 업로드

1. 로컬에서 프로젝트 압축:

   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. 환경 파일 설정

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

2. 환경 변수 수정

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

# 필수 설정 (반드시 변경!)
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. 마이그레이션 파일 복사

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

---

🚀 배포 실행

1. Docker Compose 실행

cd /volume3/docker/todo-project/app

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

# 로그 확인
docker-compose logs -f

2. 컨테이너 상태 확인

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

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

3. 헬스체크 확인

# 백엔드 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. 컨테이너가 시작되지 않는 경우

# 로그 확인
docker-compose logs

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

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

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

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

3. 이미지 업로드 실패

# 업로드 디렉토리 권한 확인
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 추가:

CORS_ORIGINS=["http://192.168.1.100:4000", "https://your-domain.synology.me"]

로그 확인 명령어

# 전체 로그
docker-compose logs -f

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

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

---

🔄 유지보수

업데이트

cd /volume3/docker/todo-project/app

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

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

백업

# 데이터베이스 백업
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/

모니터링

# 컨테이너 리소스 사용량
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가 시놀로지에 성공적으로 배포되었습니다!