Clarify NAS source builds and Docker app image updates

2026-10-14 10:11:16 +09:00
parent d6e60ecb3b
commit d7ee49d411
1 changed files with 28 additions and 11 deletions
--- a/deploy.md
+++ b/deploy.md
@@ -69,18 +69,18 @@ sudo sh scripts/configure-nas.sh
 3. 프로젝트 이름에 **hop** 입력.
 4. 프로젝트 저장 경로는 방금 `git clone`한 **hop 폴더** 선택.
 5. YAML 가져오기에서 **compose.nas.yaml** 선택. 파일 가져오기가 없으면 해당 파일 내용을 Compose 편집기에 붙여넣습니다.
-6. **배포 / 빌드 후 시작** 누르기. 처음에는 이미지 빌드가 끝날 때까지 기다립니다.
+6. 아래 SSH 명령으로 이미지를 빌드한 뒤 앱에서 **배포** 누르기.
 7. 프로젝트의 hop 컨테이너가 **실행 중**, 상태가 **healthy**인지 확인.

-`hop.noname.company:latest`는 NAS에서 소스로 빌드하는 로컬 이미지입니다. Docker Hub에 등록된 이미지가 아니며 `docker login`은 필요하지 않습니다. YAML의 `pull_policy: never`로 외부에서 hop. 이미지를 다운로드하지 않습니다. 처음 배포와 코드 업데이트에는 **이미지 빌드**가 필요합니다.
+`hop.noname.company:latest`는 NAS에서 소스로 빌드하는 로컬 이미지입니다. Docker Hub에 등록된 이미지가 아니며 `docker login`은 필요하지 않습니다. YAML의 `pull_policy: never`는 Compose가 기존 로컬 이미지를 사용하도록 지정합니다. 앱에서 별도로 선택하는 **최신 이미지** 업데이트는 외부 다운로드를 시도할 수 있으므로 선택하지 않습니다. 처음 배포와 코드 업데이트에는 **이미지 빌드**가 필요합니다.

-Docker 앱이 빌드 전에 컨테이너 생성부터 시도하거나 `No such image`가 나오면, SSH에서 아래 명령으로 이미지만 빌드한 뒤 Docker 앱으로 돌아가 **시작 / 재배포**하세요. 이 명령은 컨테이너를 시작하거나 데이터를 삭제하지 않습니다.
+SSH에서 hop 폴더에 들어간 상태로 아래 명령을 실행하고 완료될 때까지 기다립니다. 이미지 빌드만 실행하며 컨테이너를 시작하거나 데이터를 삭제하지 않습니다.

 ```sh
 sudo docker compose --project-name hop -f compose.nas.yaml build hop
 ```

-버전별로 버튼 이름이 다를 수 있습니다. 생성한 YAML은 소스와 `.env`의 절대 경로를 사용합니다. 별도의 빈 폴더로 소스를 옮기지 마세요. 프로젝트 배포 방식은 [UGREEN 공식 안내](https://ai.ugreen.com/blogs/knowledge/docker-docker-compose-ugreen-nas)를 참고했습니다.
+버전별로 버튼 이름이 다를 수 있습니다. 재배포 시 **로컬 / 기존 이미지 사용**에 해당하는 옵션을 선택합니다. 생성한 YAML은 소스와 `.env`의 절대 경로를 사용합니다. 별도의 빈 폴더로 소스를 옮기지 마세요. 이미지 다운로드와 프로젝트 관리 방식은 [UGREEN 프로젝트 공식 안내](https://support.ugnas.com/detail/article/en-US/411)를 참고했습니다.

 ## 4. Nginx Proxy Manager 설정

@@ -246,11 +246,28 @@ cd /volume1/docker/projects/apps/hop
 git pull --ff-only origin main
 ```

-3. Docker 앱 → **프로젝트 → hop → 재빌드 / 이미지 다시 빌드**.
-4. 빌드 완료 후 **시작 / 재배포**.
+3. SSH에서 새 이미지 빌드. 완료될 때까지 기다립니다:
+
+```sh
+sudo docker compose --project-name hop -f compose.nas.yaml build hop
+```
+
+4. Docker 앱 → **프로젝트 → hop → 재배포**. **로컬 / 기존 이미지 사용**에 해당하는 옵션을 선택합니다. **최신 이미지**는 외부 다운로드이므로 선택하지 않습니다.
 5. `healthy` 확인 → 브라우저 새로고침. PWA는 앱을 닫고 다시 열기.

-앱의 재배포 버튼이 이미지 빌드까지 함께 실행한다면 그 버튼으로 진행해도 됩니다. 기존 이미지를 그대로 쓰는 단순 재시작은 새 코드를 반영하지 않습니다.
+유그린의 **최신 이미지** 업데이트는 Git 소스를 빌드하는 기능이 아닙니다. `pull access denied` 뒤에 `Running 0.0s`만 나오면 새 이미지 빌드·컨테이너 교체가 확인되지 않은 상태입니다. 기존 컨테이너를 단순 재시작해도 새 코드는 반영되지 않습니다.
+
+앱 재배포 이후에도 이전 코드가 실행되면, 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
+```
+
+현재 인증 코드 적용 여부는 아래 명령으로 확인합니다. `8`이면 비밀번호 최소 8자 변경이 반영됐고, `12`이면 이전 코드입니다:
+
+```sh
+sudo docker exec hop node -e "fetch('http://127.0.0.1:'+process.env.PORT+'/api/auth/me').then(r=>r.json()).then(v=>console.log(v.passwordMinLength))"
+```

 **저장소 전환을 완료한 뒤의 코드·UI 업데이트는 이 순서만 진행합니다.** 설정 스크립트를 다시 실행하거나 YAML을 다시 불러올 필요가 없습니다. NPM·Cloudflare Tunnel 설정도 그대로 유지합니다. 위치 검색은 양쪽 브라우저에서 위치 권한을 허용하면 자동으로 동작합니다.

@@ -388,7 +405,7 @@ HTTP 주소는 상태 확인에만 씁니다. 실제 접속·QR·로그인은 `h

 ## 이미지 다운로드 오류가 나올 때

-`pull access denied for hop.noname.company`는 소스 빌드용 로컬 이미지를 외부 레지스트리에서 찾았다는 뜻입니다. 마지막에 컨테이너 생성이 완료됐으면 경고일 수 있으니 Docker 앱에서 실행 상태를 확인합니다.
+`pull access denied for hop.noname.company`는 소스 빌드용 로컬 이미지를 외부 레지스트리에서 찾았다는 뜻입니다. 앱의 **재배포 → 최신 이미지**는 외부 다운로드 기능입니다. `Running`은 실행 상태만 나타내며 최신 Git 코드가 반영됐다는 뜻은 아닙니다.

 SSH에서 순서대로 실행하세요.

@@ -401,12 +418,12 @@ git pull --ff-only origin main
 ```

 ```sh
-sudo sh scripts/configure-nas.sh
+sudo docker compose --project-name hop -f compose.nas.yaml build --no-cache hop
 ```

-Docker 앱에서 **새 compose.nas.yaml 다시 불러오기 → 저장 → 재빌드 → 시작 / 재배포** 순서로 진행합니다. 새 YAML은 `pull_policy: never`를 사용합니다. 기존 YAML을 그대로 쓰면 수정이 적용되지 않습니다.
+빌드 완료 후 Docker 앱에서 **재배포 → 로컬 / 기존 이미지 사용**에 해당하는 옵션을 선택합니다. 앱에서 컨테이너가 교체되지 않으면 7장의 `up ... --force-recreate` 명령을 사용합니다. 기존 YAML이 이미 `pull_policy: never`이고 `/data/uploads`가 hop 폴더의 `uploads`에 연결됐다면 설정 스크립트 실행이나 YAML 교체는 필요 없습니다.

-앱에서 빌드 단계를 사용할 수 없으면 앞의 `sudo docker compose ... build hop` 명령으로 이미지를 먼저 빌드한 뒤 앱에서 시작하세요. `docker login`이나 볼륨 삭제로 해결하려고 하지 마세요. `never`의 로컬 이미지 사용 방식은 [Docker 공식 문서](https://docs.docker.com/reference/compose-file/services/#pull_policy)를 참고했습니다.
+`docker login`이나 볼륨 삭제는 필요 없습니다. `never`의 로컬 이미지 사용 방식은 [Docker 공식 문서](https://docs.docker.com/reference/compose-file/services/#pull_policy)를 참고했습니다.

 ## 초대 코드와 모바일 화면