161 lines
6.9 KiB
Markdown
161 lines
6.9 KiB
Markdown
# UGREEN NAS 배포 가이드
|
|
|
|
## 개요
|
|
- 운영 기본 컨테이너는 `mariadb`, `backend`, `frontend` 3개다.
|
|
- `phpmyadmin`은 필요할 때만 `admin` 프로필로 추가 실행한다.
|
|
- 외부 공개는 `frontend` 컨테이너 하나만 하고, `/api`, `/uploads`, `/health`는 내부적으로 `backend`로 프록시한다.
|
|
- 도메인은 `https://tmaker.sori.studio` 기준으로 설정한다.
|
|
|
|
## 파일
|
|
- 프로덕션 컴포즈: [docker-compose.prod.yml](/Users/bicute/Desktop/zenn.dev/tier-cursor/docker-compose.prod.yml)
|
|
- 백엔드 이미지: [backend/Dockerfile](/Users/bicute/Desktop/zenn.dev/tier-cursor/backend/Dockerfile)
|
|
- 프런트 이미지: [frontend/Dockerfile](/Users/bicute/Desktop/zenn.dev/tier-cursor/frontend/Dockerfile)
|
|
- 프런트 Nginx 프록시: [frontend/nginx.conf](/Users/bicute/Desktop/zenn.dev/tier-cursor/frontend/nginx.conf)
|
|
- 환경변수 예시: [.env.production.example](/Users/bicute/Desktop/zenn.dev/tier-cursor/.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에서:
|
|
|
|
```bash
|
|
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에만 유지한다.
|
|
|
|
예시:
|
|
|
|
```bash
|
|
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`
|
|
|
|
예시:
|
|
|
|
```env
|
|
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. 컨테이너 실행
|
|
|
|
```bash
|
|
docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build
|
|
```
|
|
|
|
- phpMyAdmin까지 같이 띄우려면:
|
|
|
|
```bash
|
|
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에서는 아래 두 줄이 기본 배포 절차다.
|
|
|
|
```bash
|
|
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. 이번 v0.1.34까지 적용하는 예시
|
|
- 이미 NAS 폴더가 Git clone 상태라면:
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
- 아직 수동 복사 폴더만 있다면:
|
|
|
|
```bash
|
|
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 시간이 짧아서 생기는 문제다.
|
|
- 최신 컴포즈 파일 반영 후 아래 순서로 다시 시작한다:
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
## 9. 참고
|
|
- 현재 업로드 이미지는 서버 저장 전에 리사이즈/압축하지 않는다.
|
|
- 운영 중 원본 이미지가 많이 쌓이면 이후 `sharp` 기반 최적화 단계를 추가하는 것이 좋다.
|
|
- 프런트/백엔드/Nginx 설정을 바꿨다면 NAS에서 `docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build`로 이미지를 다시 빌드해 반영한다.
|
|
- 운영 중 `.env.production`, 업로드 파일 볼륨, MariaDB 볼륨은 Git과 별개로 NAS 로컬 자산이므로 백업 정책을 따로 잡아야 한다.
|