zenn/sori.studio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

NAS 배포 Buildx 기준으로 정리

Browse Source
This commit is contained in:
zenn
2026-08-13 15:24:04 +09:00
parent 29fba4f780
commit 5600a20294
7 changed files with 25 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/deploy.md
View File

@@ -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`만으로 충분하다.