tier-maker/docs/ugreen-nas-deploy.md

UGREEN NAS 배포 가이드

개요

• 운영 기본 컨테이너는 mariadb, backend, frontend 3개다.
• phpmyadmin은 필요할 때만 admin 프로필로 추가 실행한다.
• 외부 공개는 frontend 컨테이너 하나만 하고, /api, /uploads, /health는 내부적으로 backend로 프록시한다.
• 도메인은 https://tmaker.sori.studio 기준으로 설정한다.

파일

• 프로덕션 컴포즈: docker-compose.prod.yml
• 백엔드 이미지: backend/Dockerfile
• 프런트 이미지: frontend/Dockerfile
• 프런트 Nginx 프록시: frontend/nginx.conf
• 환경변수 예시: .env.production.example

1. 프로젝트 업로드

• NAS 작업 폴더에 현재 프로젝트를 그대로 업로드한다.
• 기존 로컬 MariaDB 내용은 무시하고 새 운영 DB로 시작해도 된다.

1-1. 권장 방식: Git clone 기반 운영

• 수동 복사는 처음 1회에는 가능하지만, 이후부터는 로컬과 NAS가 쉽게 어긋난다.
• 권장 방식은 NAS 작업 폴더를 Git 저장소로 두고, 로컬에서 작업 후 push, NAS에서는 pull만 하는 구조다.
• 추천 흐름:
  • 로컬: 개발 → 테스트 → 커밋 → git push
  • NAS: git pull → docker compose up -d --build

처음부터 Git으로 시작하려면 NAS에서:

cd /volume1/docker/projects/apps
git clone https://git.sori.studio/zenn/tier-maker.git
cd tier-maker
cp .env.production.example .env.production

• 이미 같은 경로에 수동 복사본이 있다면, 가장 깔끔한 방법은 기존 폴더를 다른 이름으로 잠시 옮기고 새로 clone하는 것이다.
• .env.production은 Git에 올리지 않고 NAS에만 유지한다.

예시:

cd /volume1/docker/projects/apps
mv tier-maker tier-maker-manual-backup
git clone https://git.sori.studio/zenn/tier-maker.git
cd tier-maker
cp .env.production.example .env.production

• 이후 기존 수동 복사본의 .env.production 값을 새 clone 폴더의 .env.production에 그대로 옮기면 된다.

2. 환경변수 파일 준비

• 루트에서 .env.production.example를 복사해 .env.production으로 만든다.
• 최소 변경값:
  • MARIADB_ROOT_PASSWORD
  • MARIADB_PASSWORD
  • SESSION_SECRET

예시:

MARIADB_ROOT_PASSWORD=very-strong-root-password
MARIADB_DATABASE=tier_cursor
MARIADB_USER=tier_cursor
MARIADB_PASSWORD=very-strong-app-password
SESSION_SECRET=very-strong-random-session-secret

3. 컨테이너 실행

docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build

• phpMyAdmin까지 같이 띄우려면:

docker compose --env-file .env.production -f docker-compose.prod.yml --profile admin up -d --build

• MariaDB 첫 초기화는 NAS 환경에서 2분 이상 걸릴 수 있다.
• 현재 프로덕션 컴포즈는 이를 고려해 start_period: 150s, retries: 20 healthcheck를 사용한다.
• 로그상 DB가 정상 기동했는데도 unhealthy가 뜬 적이 있다면 최신 docker-compose.prod.yml로 다시 올리는 것이 좋다.

3-1. 이후 업데이트 방식

• Git clone 기반으로 전환한 뒤에는 파일을 하나씩 NAS에 덮어쓰지 않는다.
• 로컬에서 커밋과 푸시가 끝난 뒤, NAS에서는 아래 두 줄이 기본 배포 절차다.

git pull origin main
docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build

• Dockerfile, Nginx 설정, 프런트 소스, 백엔드 소스가 바뀐 경우에는 --build를 유지한다.
• 단순 재시작만 필요할 때도 있지만, 운영에서는 실수 방지를 위해 up -d --build를 기본값으로 두는 편이 안전하다.

3-2. 운영 DB/업로드/세션까지 완전 초기화하고 새로 빌드하기

• 운영 데이터를 전부 버리고 새 DB로 다시 시작할 때만 사용한다.
• 아래 명령은 MariaDB 데이터, 업로드 이미지, 세션 파일 볼륨까지 같이 삭제하므로 실행 전에 정말 초기화해도 되는지 반드시 확인한다.
• .env.production은 프로젝트 폴더에 그대로 남고, Docker volume 데이터만 제거된다.

cd /volume1/docker/projects/apps/tier-maker
git pull origin main
docker compose --env-file .env.production -f docker-compose.prod.yml down -v
docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build

• 이렇게 올리면 백엔드가 빈 MariaDB에 현재 스키마를 새로 만들고, 초기 템플릿은 시스템용 freeform 한 건만 생성한다.
• down -v 후 첫 기동은 MariaDB 초기화 때문에 조금 더 오래 걸릴 수 있으니, 아래 명령으로 상태를 확인한다.

docker compose --env-file .env.production -f docker-compose.prod.yml ps
docker compose --env-file .env.production -f docker-compose.prod.yml logs -f mariadb
docker compose --env-file .env.production -f docker-compose.prod.yml logs -f backend

3-3. DB만 비우고 업로드/세션 볼륨은 유지하기

• 이미지 파일과 세션 볼륨은 유지하고 MariaDB 데이터만 새로 시작하고 싶다면 tmaker_mariadb_data 볼륨만 지운다.
• 이 경우에도 기존 티어표/유저 DB 레코드와 업로드 파일 참조가 끊길 수 있으므로, 현재 운영 데이터를 전부 버리는 전제에서만 사용한다.

cd /volume1/docker/projects/apps/tier-maker
docker compose --env-file .env.production -f docker-compose.prod.yml down
docker volume rm tier-maker_tmaker_mariadb_data
docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build

• 만약 볼륨 이름이 다르게 잡혀 있는지 확인하고 싶다면 먼저 docker volume ls | grep tmaker로 실제 이름을 확인한 뒤 지운다.

3-4. 이번 최신 main까지 적용하는 예시

• 이미 NAS 폴더가 Git clone 상태라면:

cd /volume1/docker/projects/apps/tier-maker
git pull origin main
sudo docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build

• 아직 수동 복사 폴더만 있다면:

cd /volume1/docker/projects/apps
mv tier-maker tier-maker-manual-backup
git clone https://git.sori.studio/zenn/tier-maker.git
cd tier-maker
cp .env.production.example .env.production
# 여기서 기존 .env.production 값을 새 파일에 옮긴다.
docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build

4. NAS 리버스 프록시

• 외부 도메인: tmaker.sori.studio
• 내부 대상 프로토콜: http
• 내부 대상 호스트: NAS IP 또는 localhost
• 내부 대상 포트: 18080

즉 NAS 리버스 프록시는 frontend 컨테이너의 18080만 바라보면 된다.

5. HTTPS / 쿠키

• 현재 프로덕션 컴포즈는 SESSION_COOKIE_SECURE=true를 사용한다.
• 따라서 tmaker.sori.studio에는 HTTPS 인증서가 연결되어 있어야 한다.
• NAS 리버스 프록시가 HTTPS 종료를 하고 내부는 http://frontend:80 또는 localhost:18080으로 전달하면 된다.
• 최신 프런트 Nginx 설정은 백엔드로 X-Forwarded-Proto: https를 넘기므로, 로그인 직후 세션이 바로 풀리는 경우에는 프런트 이미지를 다시 빌드해 최신 설정이 반영됐는지 먼저 확인한다.

6. 데이터 위치

• MariaDB 데이터: Docker volume tmaker_mariadb_data
• 업로드 파일: Docker volume tmaker_uploads
• 세션 파일: Docker volume tmaker_sessions

7. 점검 포인트

• 메인 접속: https://tmaker.sori.studio
• 헬스체크: https://tmaker.sori.studio/health
• 로그인 후 새로고침 또는 내 티어표 진입 시 세션이 유지되는지 확인
• 관리자 로그인 후:
  • 게임 생성
  • 썸네일 업로드
  • 티어표 저장
  • 이미지 다운로드

8. MariaDB가 unhealthy일 때

• 로그에 ready for connections가 보이면 DB 자체는 정상일 가능성이 높다.
• 이 경우는 대부분 healthcheck 시간이 짧아서 생기는 문제다.
• 최신 컴포즈 파일 반영 후 아래 순서로 다시 시작한다:

docker compose --env-file .env.production -f docker-compose.prod.yml down -v
docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build

• 이 명령도 down -v 때문에 DB/업로드/세션 볼륨을 모두 삭제한다. 데이터를 유지해야 하는 상황이면 -v를 빼고 다시 올린다.

9. 참고

• 현재 업로드 이미지는 서버 저장 전에 리사이즈/압축하지 않는다.
• 운영 중 원본 이미지가 많이 쌓이면 이후 sharp 기반 최적화 단계를 추가하는 것이 좋다.
• 프런트/백엔드/Nginx 설정을 바꿨다면 NAS에서 docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build로 이미지를 다시 빌드해 반영한다.
• 운영 중 .env.production, 업로드 파일 볼륨, MariaDB 볼륨은 Git과 별개로 NAS 로컬 자산이므로 백업 정책을 따로 잡아야 한다.