zenn/playuniare.sori.studio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
269a3218718e86413ca78a4502c4289c218bed64
playuniare.sori.studio/docs/deploy.md

9.9 KiB
Raw Blame History

UGREEN NAS Docker 배포 안내

문서 목적

이 문서는 터미널과 Docker에 익숙하지 않은 사용자가 Play Uniare의 테스트 버전과 운영 버전을 UGREEN NAS에서 실행하고 업데이트하는 절차를 설명한다.

현재 프로젝트는 Vue 정적 프런트엔드만 포함한다. 실시간 서버가 추가되면 compose.yaml에 백엔드 서비스와 상태 저장소를 함께 추가한다.

배포 방식

사용자 브라우저
    ↓
NAS 포트 또는 리버스 프록시
    ↓
Play Uniare 컨테이너의 Nginx
    ├── /              → Vue 빌드 결과
    └── /card-assets/  → 기존 Uniare 카드 이미지

Docker 이미지를 만들 때 Node.js로 Vue를 빌드하고, 실행할 때는 가벼운 Nginx가 빌드 결과를 제공한다.

카드 이미지는 다음 기존 폴더를 복사하지 않고 읽기 전용으로 연결한다.

/volume1/docker/projects/apps/uniare/config/www/images

NAS에서 처음 한 번 준비하기

1. Docker 앱 설치

UGREEN NAS의 앱 센터에서 Docker 또는 Container Manager에 해당하는 앱을 설치한다. 모델과 UGOS 버전에 따라 앱 이름이 다를 수 있다.

2. 프로젝트 저장 폴더 준비

NAS 공유 폴더에 다음과 같은 폴더를 만든다.

/volume1/docker/projects/apps/
├── uniare/
│   └── config/
│       └── www/
│           ├── index.html
│           └── images/
└── playuniare/

이 프로젝트의 NAS 경로는 다음으로 고정한다.

/volume1/docker/projects/apps/playuniare

3. SSH 사용 여부 결정

UGREEN 관리 화면에서 Docker Compose 프로젝트를 직접 등록할 수 있다면 GUI를 우선 사용한다. GUI에서 Git 저장소를 직접 받을 수 없거나 업데이트가 어려운 경우에만 SSH 터미널을 사용한다.

SSH를 활성화할 때는 관리자 화면에서 포트와 계정을 확인한다. NAS 비밀번호를 문서, .env, Git 저장소에 기록하지 않는다.

테스트 버전 실행

테스트 버전은 외부 도메인에 연결하기 전에 NAS 내부에서 확인하는 용도다.

1. NAS에 프로젝트 받기

NAS 터미널에서 프로젝트 저장 폴더로 이동한다.

cd /volume1/docker/projects/apps

처음 한 번만 저장소를 복제한다.

git clone https://git.sori.studio/zenn/playuniare.sori.studio.git playuniare
cd playuniare

비공개 저장소가 인증을 요구하면 비밀번호 대신 Git 서버에서 발급한 접근 토큰을 사용하는 것을 권장한다. 토큰을 명령문이나 문서에 저장하지 않는다.

2. 테스트 컨테이너 빌드 및 실행

docker compose \
  -f compose.test.yaml \
  -f compose.test.nas.yaml \
  up -d --build

이 명령은 다음 작업을 한 번에 수행한다.

  • 최신 소스 코드로 Docker 이미지 생성
  • 테스트 컨테이너 실행
  • NAS의 18080 포트와 컨테이너 연결

3. 브라우저에서 확인

NAS의 내부 IP가 192.168.0.20이라면 다음 주소로 접속한다.

http://192.168.0.20:18080

실제 NAS IP는 공유기 또는 UGREEN 관리 화면에서 확인한다.

4. 테스트 로그 확인

화면이 열리지 않으면 다음을 실행한다.

docker compose \
  -f compose.test.yaml \
  -f compose.test.nas.yaml \
  ps

docker compose \
  -f compose.test.yaml \
  -f compose.test.nas.yaml \
  logs --tail=100

Up 또는 running 상태인지 확인한다.

5. 테스트 버전 중지

docker compose \
  -f compose.test.yaml \
  -f compose.test.nas.yaml \
  down

컨테이너는 제거되지만 소스 코드와 Docker 이미지는 남아 있다.

운영 버전 최초 배포

1. 배포 전 로컬 검증

개발 컴퓨터에서 다음 명령이 성공해야 한다.

npm install
npm run build

그 후 변경 사항을 커밋하고 원격 저장소에 푸시한다.

2. NAS에서 운영 컨테이너 실행

NAS 프로젝트 폴더에서 실행한다.

cd /volume1/docker/projects/apps/playuniare
git pull
docker compose \
  -f compose.yaml \
  -f compose.nas.yaml \
  up -d --build

운영 컨테이너는 NAS의 18081 포트를 사용한다.

http://NAS_IP:18081

3. 도메인 연결

UGREEN NAS 또는 사용 중인 리버스 프록시에서 다음과 같이 연결한다.

외부 도메인: https://playuniare.sori.studio
내부 대상: http://127.0.0.1:18081
  • 외부 접속은 HTTPS를 사용한다.
  • 공유기에서 컨테이너 포트를 그대로 외부에 노출하기보다 리버스 프록시를 사용한다.
  • 인증서 자동 갱신이 설정되어 있는지 확인한다.

4. 카드 이미지 연결 확인

브라우저에서 실제 카드 파일 하나를 직접 연다.

http://NAS_IP:18081/card-assets/ua03/EX01BT_HTR-2-001.png

이미지가 보이면 읽기 전용 마운트와 Nginx 경로가 정상이다. 파일명이 실제로 존재하는 카드인지 먼저 확인한다.

이미지가 보이지 않으면 NAS 터미널에서 원본 경로를 확인한다.

ls /volume1/docker/projects/apps/uniare/config/www/images

시리즈 폴더가 보여야 한다. 다음 명령으로 컨테이너 내부 연결도 확인한다.

docker exec playuniare-web ls /srv/uniare-card-images

이 경로 역시 같은 시리즈 폴더를 보여야 한다.

새 버전 업데이트

안전한 권장 순서

  1. 개발 컴퓨터에서 npm run build를 실행한다.
  2. 변경 내용을 Git에 커밋하고 푸시한다.
  3. NAS에서 테스트 버전을 먼저 업데이트한다.
  4. 테스트 주소에서 주요 기능을 확인한다.
  5. 문제가 없으면 운영 버전을 업데이트한다.

테스트 버전 업데이트

cd /volume1/docker/projects/apps/playuniare
git pull
docker compose \
  -f compose.test.yaml \
  -f compose.test.nas.yaml \
  up -d --build

브라우저에서 http://NAS_IP:18080을 확인한다.

운영 버전 업데이트

cd /volume1/docker/projects/apps/playuniare
git pull
docker compose \
  -f compose.yaml \
  -f compose.nas.yaml \
  up -d --build

브라우저에서 실제 도메인을 확인한다.

사용하지 않는 Docker 이미지 정리

업데이트를 여러 번 하면 이전 이미지가 NAS 용량을 차지할 수 있다.

docker image prune

삭제 대상 확인 질문이 나오면 내용을 읽고 y를 입력한다. -a 옵션이나 볼륨 삭제 명령은 데이터 유실 가능성이 있으므로 이 문서에서는 사용하지 않는다.

이전 버전으로 되돌리기

문제가 생기면 먼저 현재 커밋을 확인한다.

git log --oneline -10

정상 동작했던 커밋 식별자를 확인한 뒤 다음처럼 전환한다.

git checkout 정상커밋식별자
docker compose \
  -f compose.yaml \
  -f compose.nas.yaml \
  up -d --build

복구가 끝난 뒤 개발 컴퓨터에서 문제를 수정하고 정상 브랜치에 새 커밋을 만든다. NAS에서 임의로 소스 파일을 직접 수정하지 않는다.

다시 최신 main으로 돌아갈 때:

git checkout main
git pull
docker compose \
  -f compose.yaml \
  -f compose.nas.yaml \
  up -d --build

운영 점검 명령

docker compose -f compose.yaml -f compose.nas.yaml ps
docker compose -f compose.yaml -f compose.nas.yaml logs --tail=100
docker compose -f compose.yaml -f compose.nas.yaml restart
  • ps: 실행 상태 확인
  • logs: 최근 오류 확인
  • restart: 같은 이미지로 컨테이너 재시작

배포 체크리스트

  • 로컬 npm run build 성공
  • 관련 문서 업데이트
  • Git 커밋과 푸시 완료
  • 테스트 컨테이너 재빌드
  • 테스트 URL 주요 기능 확인
  • 운영 컨테이너 재빌드
  • 실제 도메인 HTTPS 접속 확인
  • /card-assets/<series>/<fileName> 이미지 접속 확인
  • 카드 이미지 마운트가 읽기 전용인지 확인
  • 브라우저 새로고침과 직접 URL 접근 확인
  • 오류 로그 확인
  • .env, 토큰, 비밀번호가 Git에 없는지 확인

향후 실시간 서버 추가 시

프런트엔드만 있을 때는 Nginx 컨테이너 하나면 충분하다. Socket.IO 서버가 추가되면 다음 항목이 필요하다.

  • Node.js 서버 컨테이너
  • WebSocket을 지원하는 리버스 프록시 설정
  • 프런트엔드와 서버의 환경변수
  • 방 상태 백업 또는 Redis 도입 여부
  • 컨테이너 재시작 시 방이 종료된다는 안내

로컬 개발 서버의 기본 포트는 31873으로 정한다. Docker 네트워크 안에서는 다른 컨테이너가 같은 내부 포트를 사용해도 문제가 없다. 충돌하는 것은 NAS 호스트에 공개한 포트다.

운영 환경에서는 Socket.IO 서버 포트를 NAS 외부에 직접 공개하지 않는 것을 원칙으로 한다.

브라우저
  → https://playuniare.sori.studio/socket.io
  → Play Uniare Nginx
  → Docker 내부 Socket.IO 서버:31873

이 구조에서는 NAS의 다른 서비스가 호스트 포트 31873을 사용 중이어도 Socket.IO 컨테이너가 해당 포트를 호스트에 공개하지 않는 한 충돌하지 않는다. 실시간 서버 구현 시 expose만 사용하고 ports는 추가하지 않는 방향을 우선한다.

이 구조가 변경되면 반드시 이 문서와 docs/history.md를 함께 수정한다.

NAS 전용 Compose 파일을 분리한 이유

  • compose.yaml: 어느 컴퓨터에서도 검사하고 빌드할 수 있는 공통 운영 설정
  • compose.nas.yaml: NAS에만 존재하는 카드 이미지 절대 경로 연결
  • compose.test.yaml: 공통 테스트 설정
  • compose.test.nas.yaml: 테스트 컨테이너의 NAS 카드 이미지 연결

개발 Mac에는 /volume1/... 경로가 없으므로 NAS 전용 파일을 사용하지 않는다. NAS에서는 반드시 공통 파일과 NAS 전용 파일을 함께 지정한다.

Reference in New Issue View Git Blame Copy Permalink