# UNIARE 실행·배포 가이드

필요한 부분만 골라서 읽으면 된다.

1. 내 컴퓨터에서 실행: `1. 로컬 실행`
2. NAS에 처음 설치: `2. NAS 최초 배포`
3. 이미지나 카드 데이터 반영: `3. 정적 파일 업데이트`
4. API나 Docker 설정 반영: `4. 전체 업데이트`

로컬 주소는 `http://localhost:44082`, 운영 주소는 `https://uniare.sori.studio`이다.
Git 저장소는 `https://git.sori.studio/sori.studio/uniare.sori.studio.git`이다.

## 시작 전 확인

- 명령은 프로젝트 폴더에서 실행한다.
- 로컬과 NAS는 각각 다른 `.env`와 DB를 사용한다.
- `.env`, DB, 비밀번호는 Git에 올리지 않는다.
- 카드 이미지는 Git LFS로 관리한다.
- 로컬 위치는 `<LOCAL_PROJECT_DIR>/uniare.sori.studio`, NAS 위치는 `<NAS_PROJECT_DIR>/uniare.sori.studio`로 표기한다.

## 1. 로컬 실행

최초 한 번 프로젝트 폴더에서 `cp .env.example .env`를 실행한다.

`.env`에서 다음 값을 변경한다.

```env
JWT_SECRET=32자_이상의_랜덤_문자열
ADMIN_EMAIL=관리자_이메일
ADMIN_PASSWORD=8자_이상의_비밀번호
WEB_PORT=44082
APP_BASE_URL=http://localhost:44082
RESEND_API_KEY=Resend_API_Key
RESEND_FROM_EMAIL=UNIARE <인증된_발신주소>
STATS_API_TOKEN=대시보드용_토큰_또는_빈값
```

랜덤 문자열은 `openssl rand -hex 32`로 만들 수 있다.

실행은 `npm start`, 종료는 `npm stop`, 로그 확인은 `npm run logs`를 사용한다.
실행 후 브라우저에서 `http://localhost:44082`에 접속한다.

## 2. NAS 최초 배포

NAS에 Git, Git LFS, Docker, Docker Compose가 설치되어 있어야 한다.

저장소를 받는다.

```bash
cd <NAS_PROJECT_DIR>
git clone https://git.sori.studio/sori.studio/uniare.sori.studio.git uniare.sori.studio
cd uniare.sori.studio
git lfs pull
cp .env.example .env
```

`.env`에서 다음 값을 운영 환경에 맞게 변경한다.

```env
JWT_SECRET=32자_이상의_랜덤_문자열
ADMIN_EMAIL=관리자_이메일
ADMIN_PASSWORD=8자_이상의_비밀번호
ADMIN_USERNAME=admin
WEB_PORT=44082
CORS_ORIGINS=https://uniare.sori.studio
APP_BASE_URL=https://uniare.sori.studio
RESEND_API_KEY=Resend_API_Key
RESEND_FROM_EMAIL=UNIARE <account@인증된_발신도메인>
STATS_API_TOKEN=대시보드용_긴_랜덤_문자열
```

Resend에서 소유한 도메인 또는 발신용 하위 도메인을 먼저 추가하고 DNS 인증을 완료해야 한다. API Key에는 메일 발송 권한이 필요하며 `.env` 외에는 기록하지 않는다.

Docker 실행: `docker compose -f docker-compose.prod.yml up -d --build`

상태 확인: `docker compose -f docker-compose.prod.yml ps`

API 확인: `curl -fsS http://localhost:44082/api/v1/health`

운영 지표 확인: `curl -fsS http://localhost:44082/api/stats`

정상이면 `{"ok":true,"version":"4.0.16"}`이 표시된다.

이메일 기능 확인:

1. 실제 수신 가능한 주소로 신규 가입한다.
2. 인증 메일 링크를 누르기 전 로그인이 차단되고 로그인 화면에 `인증 메일 다시 보내기`가 표시되는지 확인한다.
3. 로그인 화면에서 재발송 후 60초 대기와 최초 발송 포함 월 3회 안내가 표시되는지 확인한다.
4. 인증 후 기본 한국어 완료 안내와 로그인이 정상 동작하는지 확인한다.
5. 로그인 화면의 `비밀번호를 잊으셨나요?`와 비밀번호 찾기·재설정 화면이 선택 언어로 표시되는지 확인한다.
6. 같은 계정에서 인증·재설정 메일을 합산해 월 3회 초과 시 관리자 문의 안내가 표시되는지 확인한다.
7. 관리자 화면에서 미인증 회원의 `이메일 인증 승인` 버튼으로 수동 승인 후 로그인되는지 확인한다.

회원 탈퇴 확인:

1. 일반 회원 프로필 최하단의 작은 `회원 탈퇴` 문구를 눌러 모달이 열리는지 확인한다.
2. `DELETE`를 정확히 입력하기 전에는 `YES` 버튼이 비활성화되는지 확인한다.
3. 탈퇴 후 로그아웃되고 같은 계정으로 로그인할 수 없는지 확인한다.
4. 탈퇴 회원의 덱은 삭제되지 않고 작성자가 `익명`으로 표시되는지 확인한다.
5. 관리자 회원 수정 모달에서 다른 회원을 탈퇴 처리할 수 있고, 자신의 관리자 계정은 삭제할 수 없는지 확인한다.
6. 관리자 덱 관리에서 복수 선택·현재 목록 전체 선택·일괄 삭제와 썸네일 정리가 동작하는지 확인한다.

NAS 리버스 프록시는 `https://uniare.sori.studio`을 `http://<NAS_IP>:44082`로 연결한다.

## 3. 정적 파일 업데이트

이미지, 카드 데이터, HTML, CSS, 프론트 JavaScript는 Docker 이미지를 다시 빌드하지 않아도 된다.

### 이미지만 변경

NAS 프로젝트 폴더에서 `git pull --ff-only`와 `git lfs pull`을 실행한 뒤 브라우저를 강력 새로고침한다. 컨테이너 재시작은 필요 없다.

### `datas/*.js` 변경

NAS 프로젝트 폴더에서 다음 명령을 실행한다.

```bash
git pull --ff-only
git lfs pull
docker compose -f docker-compose.prod.yml restart uniare-api
```

API가 카드 데이터를 메모리에 저장하므로 `datas/` 변경 시 API만 재시작한다. 이미지와 `datas/*.js`를 함께 변경한 경우도 같은 절차를 사용한다.

확인할 내용:

- `imgSrc`와 실제 이미지 파일명이 같은가?
- 파일명 대소문자가 같은가?
- 신규 시리즈가 번역 파일 3개에 등록되어 있는가?
- 카드 목록과 저장 덱에서 모두 정상 표시되는가?

### HTML·일반 CSS·프론트 JavaScript 변경

NAS는 npm이 없어도 된다. `style/output.css`는 로컬에서 빌드해 Git에 포함되므로 **`git pull`만 하면** 스타일이 반영된다.

```bash
git pull --ff-only
git lfs pull
```

배포 후 확인 (NAS 프로젝트 폴더):

```bash
wc -c style/output.css    # 약 55000 (55KB) — 44000대면 구버전, pull 누락
head -1 login.html        # output.css?v= 버전 쿼리 포함 여부
```

브라우저에서도 `개발자 도구 → Network → output.css`·`deck-favorites.js` 크기·상태를 확인한다. Cloudflare를 쓰면 구 파일이 `immutable`로 남을 수 있어 HTML에 `?v=` 쿼리를 붙인다 (v4.0.6+ CSS, v4.0.7+ 덱 페이지 JS).

`script/deck-favorites.js`는 `window.UaDeckFavorites.init`이 있어야 한다. 없으면 `git pull` 누락 또는 JS CDN 캐시다.

`nginx/default.conf`를 변경했다면 **반드시** 웹 컨테이너를 재생성한다 (볼륨 마운트 반영):

```bash
docker compose -f docker-compose.prod.yml up -d --build uniare-web
```

배포 검증 (NAS 프로젝트 폴더):

```bash
# 호스트 파일 — v4.0.8·shim 포함 여부
rg "4\.0\.8|deck-favorites-shim" deckHistory.html

# 컨테이너가 같은 파일을 보는지 (다르면 compose 경로/마운트 문제)
docker exec uniare-web rg "deck-favorites-shim|4\.0\.8" /usr/share/nginx/html/deckHistory.html

# Docker 직접 접속 (Cloudflare 우회) — 위와 같아야 함
curl -s http://127.0.0.1:44082/deckHistory.html | rg "deck-favorites-shim|4\.0\.8"
curl -s http://127.0.0.1:44082/script/deck-favorites.js | tail -1
```

호스트·컨테이너·`curl 127.0.0.1`은 최신인데 `https://uniare.sori.studio`만 구버전이면 **Cloudflare 캐시 Purge**가 필요하다.

HTML·`style/`·`script/`만 바뀐 경우 API 컨테이너 재시작은 필요 없다.

이메일 기능은 API와 Compose 환경 변수가 함께 바뀌므로 `git pull`만으로 반영되지 않는다. 반드시 `.env` 설정 후 전체 스택을 다시 빌드한다.

## 4. 전체 업데이트

`api/`, `nginx/`, Dockerfile, Compose 설정을 변경했다면 NAS 프로젝트 폴더에서 다음 명령을 실행한다.

```bash
git pull --ff-only
git lfs pull
docker compose -f docker-compose.prod.yml up -d --build
```

상태 확인은 `docker compose -f docker-compose.prod.yml ps`, API 확인은 `curl -fsS http://localhost:44082/api/v1/health`를 사용한다.

`.env`를 변경했다면 `docker compose -f docker-compose.prod.yml up -d --force-recreate`로 컨테이너를 재생성한다.

## 5. CSS 빌드

Tailwind 클래스를 새로 추가했을 때만 로컬에서 `npm install`과 `npm run build:css`를 실행한다.
생성된 `style/output.css`도 Git에 포함한다.
이미지, 카드 데이터, 기존 CSS만 수정했다면 실행하지 않아도 된다.

## 6. 자주 쓰는 운영 명령

- 전체 재시작: `docker compose -f docker-compose.prod.yml restart`
- API만 재시작: `docker compose -f docker-compose.prod.yml restart uniare-api`
- 로그 확인: `docker compose -f docker-compose.prod.yml logs -f`
- 종료: `docker compose -f docker-compose.prod.yml down`
- 다시 실행: `docker compose -f docker-compose.prod.yml up -d`

## 7. 백업

DB는 Docker 볼륨의 `/data/uadeck.db`에 있다.
덱 미리보기와 아바타는 `api/data/previews/`, `api/data/avatars/`에 있다.

DB 백업:

```bash
mkdir -p backup
BACKUP_FILE="uadeck-$(date +%Y%m%d-%H%M%S).db"
docker exec uniare-api node --input-type=module -e "import Database from 'better-sqlite3'; const db = new Database('/data/uadeck.db'); await db.backup('/data/$BACKUP_FILE'); db.close();"
docker cp "uniare-api:/data/$BACKUP_FILE" "./backup/$BACKUP_FILE"
docker exec uniare-api rm "/data/$BACKUP_FILE"
```

미리보기와 아바타 백업: `tar -czf "./backup/uploads-$(date +%Y%m%d-%H%M%S).tar.gz" api/data/previews api/data/avatars`

`.env`는 Git이 아닌 접근 제한된 별도 위치에 보관한다.

## 8. 롤백

문제가 발생하면 DB를 먼저 백업하고 `git log --oneline -10`으로 이전 정상 커밋을 확인한다.

```bash
git checkout <정상_커밋_해시>
git lfs pull
docker compose -f docker-compose.prod.yml up -d --build
```

API 확인: `curl -fsS http://localhost:44082/api/v1/health`

최신 `main`으로 돌아갈 때는 `git checkout main`과 `git pull --ff-only`를 실행한다.

## 9. 문제가 생겼을 때

웹이 열리지 않으면 `docker compose -f docker-compose.prod.yml ps`와 `docker compose -f docker-compose.prod.yml logs --tail=100`을 확인한다.

로그인이나 저장이 안 되면 `curl -fsS http://localhost:44082/api/v1/health`로 API 상태를 확인한다.

카드 이미지가 보이지 않으면 `git lfs pull`을 실행하고 `datas/*.js`의 `imgSrc`와 실제 이미지 파일명을 비교한다.

## 완료 확인

- `uniare-web`, `uniare-api`가 실행 중인가?
- API가 `ok: true`를 반환하는가?
- 홈과 카드 이미지가 열리는가?
- 로그인과 덱 저장이 동작하는가?
- `.env`와 DB가 Git에 포함되지 않았는가?