Todo-Project/SYNOLOGY_INSTALL.md

🏠 시놀로지 NAS 설치 가이드

📋 사전 준비사항

1. 시놀로지 NAS 요구사항

• DSM 7.0 이상
• Container Manager 패키지 설치
• Git Server 패키지 설치 (선택사항)
• 최소 2GB RAM 권장

2. 필요한 포트

• 4000: 프론트엔드 (Nginx)
• 8000: 백엔드 API (FastAPI)
• 5432: PostgreSQL (내부 통신)

🚀 설치 방법

방법 1: SSH를 통한 설치 (권장)

1단계: SSH 접속

ssh admin@[시놀로지_IP주소]

2단계: 프로젝트 디렉토리 생성

sudo mkdir -p /volume1/docker/todo-project
cd /volume1/docker/todo-project

3단계: Git 클론

sudo git clone https://git.hyungi.net/hyungi/Todo-Project.git .

4단계: 환경 설정

# 환경 변수 파일 생성
sudo cp .env.example .env

# 환경 변수 편집 (필요시)
sudo nano .env

5단계: Docker 컨테이너 실행

sudo docker-compose up -d

6단계: 설치 확인

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

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

방법 2: Container Manager GUI 사용

1단계: Container Manager 열기

• DSM → Package Center → Container Manager 설치/실행

2단계: 프로젝트 생성

• Project → Create
• Project name: todo-project
• Path: /docker/todo-project

3단계: 소스 설정

• Source: Git Repository
• Repository URL: https://git.hyungi.net/hyungi/Todo-Project.git
• Branch: main

4단계: 컨테이너 실행

• Build and run 클릭
• 자동으로 docker-compose.yml 파일을 읽어서 실행

🔧 설정 및 최적화

1. 환경 변수 설정 (.env)

# 데이터베이스 설정
POSTGRES_DB=todo_project
POSTGRES_USER=todo_user
POSTGRES_PASSWORD=your_secure_password_here

# JWT 설정
SECRET_KEY=your_jwt_secret_key_here
ACCESS_TOKEN_EXPIRE_MINUTES=30

# 시놀로지 연동 설정
SYNOLOGY_DSM_HOST=localhost
SYNOLOGY_DSM_PORT=5000
SYNOLOGY_DSM_USERNAME=your_username
SYNOLOGY_DSM_PASSWORD=your_password

# 메일 설정 (MailPlus 연동용)
MAIL_SERVER=localhost
MAIL_PORT=587
MAIL_USERNAME=your_mail_username
MAIL_PASSWORD=your_mail_password
MAIL_FROM=noreply@yourdomain.com

2. 볼륨 매핑 확인

volumes:
  - /volume1/docker/todo-project/data:/data
  - todo_uploads:/data/uploads

3. 포트 포워딩 설정

• 제어판 → 외부 액세스 → 라우터 구성
• 포트 4000을 외부에서 접근 가능하도록 설정

🌐 접속 방법

내부 네트워크

http://[시놀로지_IP]:4000

외부 접속 (DDNS 설정 시)

http://[your-synology-ddns].synology.me:4000

🔒 보안 설정

1. HTTPS 설정 (Let's Encrypt)

# 인증서 디렉토리 생성
sudo mkdir -p /volume1/docker/todo-project/ssl

# docker-compose.yml에 SSL 볼륨 추가
volumes:
  - /volume1/ssl:/etc/ssl/certs

2. 방화벽 설정

• 제어판 → 보안 → 방화벽
• 필요한 포트만 열기: 4000, 8000

3. 사용자 권한 설정

# Docker 그룹에 사용자 추가
sudo usermod -aG docker $USER

📊 모니터링 및 유지보수

1. 로그 확인

# 전체 로그
sudo docker-compose logs

# 특정 서비스 로그
sudo docker-compose logs frontend
sudo docker-compose logs backend
sudo docker-compose logs db

2. 컨테이너 상태 확인

# 실행 중인 컨테이너
sudo docker-compose ps

# 리소스 사용량
sudo docker stats

3. 업데이트

# 최신 코드 가져오기
sudo git pull origin main

# 컨테이너 재빌드
sudo docker-compose down
sudo docker-compose up -d --build

4. 백업

# 데이터베이스 백업
sudo docker-compose exec db pg_dump -U todo_user todo_project > backup.sql

# 업로드 파일 백업
sudo tar -czf uploads_backup.tar.gz /volume1/docker/todo-project/data/uploads

🔧 문제 해결

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

# 로그 확인
sudo docker-compose logs

# 포트 충돌 확인
sudo netstat -tulpn | grep :4000

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

# PostgreSQL 컨테이너 상태 확인
sudo docker-compose exec db psql -U todo_user -d todo_project -c "SELECT 1;"

3. 권한 문제

# 파일 권한 수정
sudo chown -R 1000:1000 /volume1/docker/todo-project/data

4. 메모리 부족

# 메모리 사용량 확인
free -h

# Docker 메모리 제한 설정 (docker-compose.yml)
services:
  backend:
    mem_limit: 512m

📱 PWA 설정

1. HTTPS 필수

• PWA 기능을 위해서는 HTTPS 연결이 필요합니다
• Let's Encrypt 인증서 설정 권장

2. 홈화면 추가

• 모바일에서 Safari/Chrome으로 접속
• "홈화면에 추가" 선택
• 네이티브 앱처럼 사용 가능

🎯 성능 최적화

1. Nginx 캐싱 설정

location /static/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

2. 데이터베이스 최적화

-- 인덱스 생성
CREATE INDEX idx_todos_created_at ON todos(created_at);
CREATE INDEX idx_todos_status ON todos(status);

3. 이미지 최적화

• 업로드된 이미지는 자동으로 압축됩니다
• 최대 1920x1920 해상도로 리사이즈
• JPEG 품질 85%로 최적화

📞 지원

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

1. 로그 파일: sudo docker-compose logs
2. 시스템 리소스: htop 또는 DSM 리소스 모니터
3. 네트워크 연결: 포트 접근 가능 여부
4. 권한 설정: 파일 및 디렉토리 권한

---

🚀 빠른 시작 명령어

# 전체 설치 (한 번에 실행)
ssh admin@[시놀로지_IP]
sudo mkdir -p /volume1/docker/todo-project
cd /volume1/docker/todo-project
sudo git clone https://git.hyungi.net/hyungi/Todo-Project.git .
sudo cp .env.example .env
sudo docker-compose up -d

# 접속 확인
curl http://localhost:4000

설치 완료 후 http://[시놀로지_IP]:4000으로 접속하여 Todo Project를 사용하세요! 🎉