Keep NAS application images local and document explicit builds

compose.yaml

@@ -1,7 +1,8 @@
 services:
   hop:
     image: hop.noname.company:latest
-    pull_policy: build
+    # This image is built on the NAS; it is not published in a registry.
+    pull_policy: never
     build:
       context: .
       dockerfile: Dockerfile

deploy.md

@@ -70,6 +70,14 @@ sh scripts/configure-nas.sh
 6. **배포 / 빌드 후 시작** 누르기. 처음에는 이미지 빌드가 끝날 때까지 기다립니다.
 7. 프로젝트의 hop 컨테이너가 **실행 중**, 상태가 **healthy**인지 확인.
 
+`hop.noname.company:latest`는 NAS에서 소스로 빌드하는 로컬 이미지입니다. Docker Hub에 등록된 이미지가 아니며 `docker login`은 필요하지 않습니다. YAML의 `pull_policy: never`로 외부에서 hop. 이미지를 다운로드하지 않습니다. 처음 배포와 코드 업데이트에는 **이미지 빌드**가 필요합니다.
+
+Docker 앱이 빌드 전에 컨테이너 생성부터 시도하거나 `No such image`가 나오면, SSH에서 아래 명령으로 이미지만 빌드한 뒤 Docker 앱으로 돌아가 **시작 / 재배포**하세요. 이 명령은 컨테이너를 시작하거나 데이터를 삭제하지 않습니다.
+
+```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)를 참고했습니다.
 
 ## 4. Nginx Proxy Manager 설정
@@ -278,3 +286,25 @@ 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 빌드에서 제외됩니다.
+
+## 이미지 다운로드 오류가 나올 때
+
+`pull access denied for hop.noname.company`는 소스 빌드용 로컬 이미지를 외부 레지스트리에서 찾았다는 뜻입니다. 마지막에 컨테이너 생성이 완료됐으면 경고일 수 있으니 Docker 앱에서 실행 상태를 확인합니다.
+
+SSH에서 순서대로 실행하세요.
+
+```sh
+cd /volume1/docker/projects/apps/hop
+```
+
+```sh
+git pull --ff-only origin main
+```
+
+```sh
+sh scripts/configure-nas.sh
+```
+
+Docker 앱에서 **새 compose.nas.yaml 다시 불러오기 → 저장 → 재빌드 → 시작 / 재배포** 순서로 진행합니다. 새 YAML은 `pull_policy: never`를 사용합니다. 기존 YAML을 그대로 쓰면 수정이 적용되지 않습니다.
+
+앱에서 빌드 단계를 사용할 수 없으면 앞의 `sudo docker compose ... build hop` 명령으로 이미지를 먼저 빌드한 뒤 앱에서 시작하세요. `docker login`이나 볼륨 삭제로 해결하려고 하지 마세요. `never`의 로컬 이미지 사용 방식은 [Docker 공식 문서](https://docs.docker.com/reference/compose-file/services/#pull_policy)를 참고했습니다.