hyungi/Todo-Project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Todo-Project/SYNOLOGY_DEPLOYMENT_GUIDE.md
Hyungi Ahn 5b70657dab 📝 배포 가이드 Git URL 수정 
- GitHub URL을 실제 Gitea 저장소 URL로 변경
- https://git.hyungi.net/hyungi/Todo-Project.git 사용
2025-09-24 09:14:54 +09:00

7.1 KiB
Raw Permalink Blame History

🚀 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://git.hyungi.net/hyungi/Todo-Project.git .

# 또는 특정 브랜치
git clone -b main https://git.hyungi.net/hyungi/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가 시놀로지에 성공적으로 배포되었습니다!

Reference in New Issue View Git Blame Copy Permalink