From 9f12651a9c20202944d60477722f45b4ec4c670d Mon Sep 17 00:00:00 2001
From: zenn <zenn.message@gmail.com>
Date: Wed, 14 Oct 2026 10:13:33 +0900
Subject: [PATCH] Use UGREEN final Compose file for NAS updates

---
 .dockerignore |  1 +
 .gitignore    |  1 +
 deploy.md     | 14 ++++++++------
 3 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/.dockerignore b/.dockerignore
index ab661fe..670a039 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -10,6 +10,7 @@ test-results
 playwright-report
 tests/e2e/*.png
 compose.nas.yaml
+docker-compose.yaml
 backups
 uploads
 hop.proxy.conf
diff --git a/.gitignore b/.gitignore
index 8782a54..ce4f2f3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,6 +10,7 @@ test-results/
 .DS_Store
 tests/e2e/*.png
 compose.nas.yaml
+/docker-compose.yaml
 backups/
 /uploads/
 hop.proxy.conf
diff --git a/deploy.md b/deploy.md
index 1c8076f..45971bf 100644
--- a/deploy.md
+++ b/deploy.md
@@ -62,6 +62,8 @@ sudo sh scripts/configure-nas.sh
 
 마지막에 표시된 `compose.nas.yaml` 경로를 복사해 둡니다. `.env`는 NAS에만 남고 Git에 올라가지 않습니다. 기존 `.env`가 있으면 덮어쓰지 않습니다.
 
+`compose.yaml`은 Git에서 관리하는 설정 원본이고, `compose.nas.yaml`은 NAS의 절대 경로와 설정을 채워 만든 가져오기용 파일입니다. 유그린 Docker 앱에 내용을 옮겨 저장하면 실제 프로젝트 구성은 hop 폴더의 **`docker-compose.yaml`**에 저장됩니다. 앱에서 수정한 최종 설정을 기준으로 업데이트하려면 이 파일을 사용합니다. 가져오기용 파일만 다시 생성해도 앱의 최종 설정은 자동으로 바뀌지 않습니다.
+
 ## 3. Docker 앱에서 배포
 
 1. NAS의 **Docker 앱** 열기.
@@ -74,7 +76,7 @@ sudo sh scripts/configure-nas.sh
 
 `hop.noname.company:latest`는 NAS에서 소스로 빌드하는 로컬 이미지입니다. Docker Hub에 등록된 이미지가 아니며 `docker login`은 필요하지 않습니다. YAML의 `pull_policy: never`는 Compose가 기존 로컬 이미지를 사용하도록 지정합니다. 앱에서 별도로 선택하는 **최신 이미지** 업데이트는 외부 다운로드를 시도할 수 있으므로 선택하지 않습니다. 처음 배포와 코드 업데이트에는 **이미지 빌드**가 필요합니다.
 
-SSH에서 hop 폴더에 들어간 상태로 아래 명령을 실행하고 완료될 때까지 기다립니다. 이미지 빌드만 실행하며 컨테이너를 시작하거나 데이터를 삭제하지 않습니다.
+처음 프로젝트를 배포하기 전에는 SSH에서 hop 폴더에 들어간 상태로 아래 명령을 실행하고 완료될 때까지 기다립니다. 이미지 빌드만 실행하며 컨테이너를 시작하거나 데이터를 삭제하지 않습니다. 이후 앱에 프로젝트를 저장한 뒤의 업데이트는 7장처럼 최종 `docker-compose.yaml`을 사용합니다.
 
 ```sh
 sudo docker compose --project-name hop -f compose.nas.yaml build hop
@@ -249,7 +251,7 @@ git pull --ff-only origin main
 3. SSH에서 새 이미지 빌드. 완료될 때까지 기다립니다:
 
 ```sh
-sudo docker compose --project-name hop -f compose.nas.yaml build hop
+sudo docker compose --project-name hop -f docker-compose.yaml build hop
 ```
 
 4. Docker 앱 → **프로젝트 → hop → 재배포**. **로컬 / 기존 이미지 사용**에 해당하는 옵션을 선택합니다. **최신 이미지**는 외부 다운로드이므로 선택하지 않습니다.
@@ -260,7 +262,7 @@ sudo docker compose --project-name hop -f compose.nas.yaml build hop
 앱 재배포 이후에도 이전 코드가 실행되면, SSH에서 아래 명령으로 이미 빌드한 이미지에 컨테이너를 맞춥니다. 기존 DB와 업로드 저장 경로는 유지하며, 이후 시작·중지·로그 확인은 Docker 앱에서 계속 진행할 수 있습니다:
 
 ```sh
-sudo docker compose --project-name hop -f compose.nas.yaml up -d --no-build --pull never --force-recreate --wait --wait-timeout 90 hop
+sudo docker compose --project-name hop -f docker-compose.yaml up -d --no-build --pull never --force-recreate --wait --wait-timeout 90 hop
 ```
 
 현재 인증 코드 적용 여부는 아래 명령으로 확인합니다. `8`이면 비밀번호 최소 8자 변경이 반영됐고, `12`이면 이전 코드입니다:
@@ -271,7 +273,7 @@ sudo docker exec hop node -e "fetch('http://127.0.0.1:'+process.env.PORT+'/api/a
 
 **저장소 전환을 완료한 뒤의 코드·UI 업데이트는 이 순서만 진행합니다.** 설정 스크립트를 다시 실행하거나 YAML을 다시 불러올 필요가 없습니다. NPM·Cloudflare Tunnel 설정도 그대로 유지합니다. 위치 검색은 양쪽 브라우저에서 위치 권한을 허용하면 자동으로 동작합니다.
 
-DB는 `hop_hop_database` 볼륨, 파일은 hop 폴더의 `uploads`에 있습니다. `uploads`, `.env`, 생성된 `compose.nas.yaml`은 Git에서 제외하므로 일반 코드 업데이트로 덮어쓰지 않습니다. 같은 저장 경로를 사용하는 재배포에서 데이터는 유지됩니다.
+DB는 `hop_hop_database` 볼륨, 파일은 hop 폴더의 `uploads`에 있습니다. `uploads`, `.env`, 생성된 `compose.nas.yaml`, 앱이 저장한 `docker-compose.yaml`은 Git에서 제외하므로 일반 코드 업데이트로 덮어쓰지 않습니다. 같은 저장 경로를 사용하는 재배포에서 데이터는 유지됩니다.
 
 ### 7-1. 업로드 폴더 전환과 테스트 자료 초기화
 
@@ -401,7 +403,7 @@ curl -fsS "http://${HOP_NAS_IP}:50189/api/health"
 
 HTTP 주소는 상태 확인에만 씁니다. 실제 접속·QR·로그인은 `https://hop.noname.company`를 사용하세요.
 
-환경파일을 YAML에 포함하지 않는 생성 방식은 [Docker Compose 공식 문서](https://docs.docker.com/reference/cli/docker/compose/config/)의 `--no-env-resolution`을 사용합니다. `.env`, 생성된 `compose.nas.yaml`, `backups`는 Git과 Docker 빌드에서 제외됩니다.
+환경파일을 YAML에 포함하지 않는 생성 방식은 [Docker Compose 공식 문서](https://docs.docker.com/reference/cli/docker/compose/config/)의 `--no-env-resolution`을 사용합니다. `.env`, 생성된 `compose.nas.yaml`, 앱이 저장한 `docker-compose.yaml`, `backups`는 Git과 Docker 빌드에서 제외됩니다.
 
 ## 이미지 다운로드 오류가 나올 때
 
@@ -418,7 +420,7 @@ git pull --ff-only origin main
 ```
 
 ```sh
-sudo docker compose --project-name hop -f compose.nas.yaml build --no-cache hop
+sudo docker compose --project-name hop -f docker-compose.yaml build --no-cache hop
 ```
 
 빌드 완료 후 Docker 앱에서 **재배포 → 로컬 / 기존 이미지 사용**에 해당하는 옵션을 선택합니다. 앱에서 컨테이너가 교체되지 않으면 7장의 `up ... --force-recreate` 명령을 사용합니다. 기존 YAML이 이미 `pull_policy: never`이고 `/data/uploads`가 hop 폴더의 `uploads`에 연결됐다면 설정 스크립트 실행이나 YAML 교체는 필요 없습니다.