math-quiz/docs/synology-deploy.md

Synology NAS Docker Compose 배포

이 문서는 현재 프로젝트를 Synology NAS에서 math-quiz 컨테이너로 실행하고, Nginx Proxy Manager(NPM)에서 math-quiz.jisangs.com으로 연결하는 절차입니다.

전제

• NAS에 Docker 또는 Container Manager가 설치되어 있어야 합니다.
• NPM 컨테이너가 80/443 포트를 사용하고 있어야 합니다.
• math-quiz.jisangs.com DNS가 NAS로 연결되어 있어야 합니다.
• NPM 컨테이너와 math-quiz 컨테이너가 같은 Docker 네트워크에 있어야 합니다.

1. NPM 공용 네트워크 준비

NAS SSH에서 한 번만 실행합니다.

docker network create npm-proxy

이미 같은 이름의 네트워크가 있으면 에러가 나도 괜찮습니다.

NPM 컨테이너가 이미 실행 중이라면 같은 네트워크에 붙입니다.

docker network connect npm-proxy <npm-container-name>

예를 들어 NPM 컨테이너 이름이 nginx-proxy-manager라면:

docker network connect npm-proxy nginx-proxy-manager

2. 프로젝트 파일 업로드

NAS에 배포 디렉터리를 만듭니다.

mkdir -p /volume1/docker/math-quiz

로컬 작업 폴더에서 NAS로 프로젝트를 복사합니다.

rsync -av --delete \
  --exclude .git \
  --exclude node_modules \
  --exclude .next \
  --exclude .pnpm-store \
  ./ <nas-user>@<nas-host>:/volume1/docker/math-quiz/

Git을 NAS에서 직접 사용할 수 있다면 아래 방식도 가능합니다.

cd /volume1/docker
git clone <repo-url> math-quiz

이미 clone 되어 있다면:

cd /volume1/docker/math-quiz
git pull

3. 운영 환경변수 작성

NAS의 /volume1/docker/math-quiz/.env.production 파일을 만듭니다.

cd /volume1/docker/math-quiz
cp .env.production.example .env.production
vi .env.production

현재 구현은 DB/Redis/NextAuth를 아직 사용하지 않지만, 이후 기능 추가를 위해 키는 준비해 둡니다.

DATABASE_URL=
REDIS_URL=
NEXTAUTH_SECRET=
NEXTAUTH_URL=https://math-quiz.jisangs.com

NEXTAUTH_SECRET을 사용할 때는 아래처럼 생성할 수 있습니다.

openssl rand -base64 32

4. Docker 이미지 빌드 및 실행

cd /volume1/docker/math-quiz
docker compose up -d --build

상태 확인:

docker compose ps
docker logs -f math-quiz

정상 실행되면 컨테이너 내부에서 Next.js 서버가 3000 포트로 떠 있습니다. 외부 80/443은 NPM이 담당하므로 docker-compose.yml에는 호스트 포트 노출을 두지 않았습니다.

5. Nginx Proxy Manager 설정

NPM 관리자 화면에서 Proxy Host를 추가합니다.

• Domain Names: math-quiz.jisangs.com
• Scheme: http
• Forward Hostname / IP: math-quiz
• Forward Port: 3000
• Websockets Support: 필요 시 활성화
• SSL: Let's Encrypt 인증서 발급
• Force SSL: 활성화

NPM 컨테이너와 math-quiz 컨테이너가 npm-proxy 네트워크를 공유해야 Forward Hostname에 math-quiz를 사용할 수 있습니다.

6. 업데이트 반영

로컬에서 변경한 파일을 다시 rsync 하거나 NAS에서 git pull 후 재빌드합니다.

cd /volume1/docker/math-quiz
docker compose up -d --build
docker image prune -f

로그 확인:

docker logs -f math-quiz

참고: 네트워크 이름이 다를 때

NPM에서 이미 쓰는 Docker 네트워크 이름이 있다면 docker-compose.yml의 npm-proxy를 해당 네트워크 이름으로 바꿉니다.

networks:
  npm-proxy:
    external: true

위 블록의 npm-proxy 이름과 서비스의 networks 값을 같은 이름으로 맞추면 됩니다.