NAS 배포 Buildx 기준으로 정리

docs/deploy.md

@@ -233,31 +233,30 @@ docker compose --env-file .env.production up -d --build
 docker compose --env-file .env.production up -d
 ```
 
-### UGREEN NAS Docker 앱 Buildx 우회
+### UGREEN NAS Docker 앱 Buildx 확인
 
-UGREEN NAS Docker 앱에서 `Docker Compose requires buildx plugin to be installed` 경고가 뜨면 NAS 앱이 `Dockerfile` 빌드를 직접 수행하지 못하는 상태다. 이때는 로컬에서 앱 이미지를 만든 뒤 NAS Docker 앱에 가져오고, NAS에서는 `build:`가 없는 `docker-compose.nas.yml`로 실행한다.
-
-로컬 Mac에서 NAS용 이미지를 만든다. DXP6800 Pro 같은 Intel NAS 기준은 `linux/amd64`다.
+UGREEN NAS Docker 앱에서 `Docker Compose requires buildx plugin to be installed` 경고가 뜨면 NAS의 Docker CLI 플러그인 경로에 Buildx가 설치되지 않은 상태다. Buildx는 프로젝트별 파일이 아니라 NAS Docker 환경 단위 플러그인이므로 한 번 설치한 뒤 기본 `docker-compose.yml`로 빌드한다.
 
 ```bash
-docker buildx build --platform linux/amd64 -t sori-studio:latest --load .
-docker save sori-studio:latest -o sori-studio-latest.tar
+sudo docker buildx version
 ```
 
-NAS Docker 앱에서 `sori-studio-latest.tar` 이미지를 가져온 뒤, Compose 생성 화면에는 `docker-compose.nas.yml` 내용을 사용한다. 이 파일은 앱 서비스를 `image: ${SORI_STUDIO_IMAGE:-sori-studio:latest}`로 실행하므로 NAS에서 Buildx 빌드를 시도하지 않는다.
-
-이미지를 가져온 뒤 NAS Docker 앱의 이미지 목록에서 이름과 태그가 `sori-studio:latest`인지 확인한다. 다른 이름으로 표시되면 `.env.production`에 아래처럼 실제 이미지 이름을 맞춘다.
+명령이 `unknown command`를 출력하면 Debian 12 x86_64 기준으로 Buildx 바이너리를 CLI 플러그인 경로에 설치한다.
 
 ```bash
-SORI_STUDIO_IMAGE=가져온이미지이름:태그
+sudo mkdir -p /usr/local/lib/docker/cli-plugins
+sudo curl -L -o /usr/local/lib/docker/cli-plugins/docker-buildx \
+  https://github.com/docker/buildx/releases/download/v0.19.3/buildx-v0.19.3.linux-amd64
+sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-buildx
+sudo docker buildx version
 ```
 
-`docker-compose.nas.yml`은 `pull_policy: never`를 사용해 앱 이미지가 없을 때 Docker Hub에서 `sori-studio`를 찾으러 가지 않는다. 이 오류가 계속 뜨면 이미지 가져오기가 누락됐거나, 가져온 이미지 태그와 `SORI_STUDIO_IMAGE` 값이 서로 다른 상태다.
-
-SSH를 쓸 수 있는 NAS에서는 같은 파일로 아래처럼 실행할 수 있다.
+`unknown command`가 계속 나오면 Docker가 다른 플러그인 경로를 보는 구성이므로 공용 경로에 링크한다.
 
 ```bash
-docker compose -f docker-compose.nas.yml up -d
+sudo mkdir -p /usr/lib/docker/cli-plugins
+sudo ln -sf /usr/local/lib/docker/cli-plugins/docker-buildx /usr/lib/docker/cli-plugins/docker-buildx
+sudo docker buildx version
 ```
 
 코드 변경 없이 `.env.production`만 수정했다면 `--build` 없이 `up -d`만으로 충분하다.

docs/history.md

@@ -1,3 +1,7 @@
+## 2026-08-13 v1.12.15 — NAS 배포는 Buildx 설치 후 기본 Compose로 통일한다
+
+UGREEN NAS의 Docker 빌드 문제는 프로젝트별 Compose 차이가 아니라 NAS Docker 환경에 Buildx CLI 플러그인이 없는 문제로 확인했다. Buildx는 프로젝트 파일이 아니라 Docker 환경 단위 플러그인이므로, 임시로 추가했던 `docker-compose.nas.yml` 이미지 실행 우회 경로는 제거하고 기본 `docker-compose.yml` 빌드 경로를 유지한다. 배포 문서에는 Debian 12 x86_64 NAS에서 Buildx를 수동 설치하고 `sudo docker buildx version`으로 확인하는 절차를 남긴다.
+
 ## 2026-08-13 v1.12.14 — NAS 앱 이미지는 pull이 아니라 가져온 태그로 맞춘다
 
 NAS Docker 앱에서 `docker-compose.nas.yml`을 먼저 실행하면 로컬에 `sori-studio:latest` 이미지가 없어서 Docker Hub에서 같은 이름을 pull하려고 시도할 수 있다. 이 이름은 공개 레지스트리 이미지가 아니라 로컬에서 만들어 NAS에 가져오는 앱 이미지이므로, NAS용 Compose에는 `pull_policy: never`를 추가해 원격 pull 시도를 막는다. 운영자는 이미지 가져오기 후 NAS 이미지 목록의 실제 이름과 태그를 확인하고, 기본값과 다르면 `.env.production`의 `SORI_STUDIO_IMAGE`로 실행 이미지명을 맞춘다.

docs/map.md

@@ -128,7 +128,6 @@
 |------|------|
 | Dockerfile | Nuxt 프로덕션 앱 이미지 빌드 |
 | docker-compose.yml | Docker CLI·Buildx 가능 환경의 앱 빌드 포함 Compose 실행 |
-| docker-compose.nas.yml | UGREEN NAS Docker 앱처럼 Buildx 없이 가져온 앱 이미지를 실행하는 Compose 설정 |
 
 ## Nuxt 모듈
 

docs/update.md

@@ -1,5 +1,10 @@
 # 업데이트 이력
 
+## v1.12.15
+
+- Buildx 설치 후 기본 `docker-compose.yml` 배포를 사용하도록 NAS 이미지 실행 우회 Compose 제거.
+- UGREEN NAS Docker 앱 Buildx 설치 확인 절차를 배포 문서에 정리.
+
 ## v1.12.14
 
 - NAS 이미지 실행용 Compose가 로컬 앱 이미지 누락 시 Docker Hub pull을 시도하지 않도록 `pull_policy: never` 추가.