SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

Docker Compose build와 image 설정 차이 및 VPS 적용법

Docker Compose에서 image와 build 키의 차이를 설명합니다. VPS 환경에서 Dockerfile 변경 사항이 반영되지 않는 이유와 docker-compose up 실행 시 이미지를 강제로 다시 빌드하는 정확한 해결 방법을 안내합니다.

Docker Compose build와 image의 차이: 요약

Docker Compose 파일에서 image:은 로컬 이미지, 태그, 다이제스트 참조를 포함하여 사용할 이미지를 지정합니다. 반면 build:은 소스 코드로부터 이미지를 빌드하는 방법을 Compose에 지시합니다. image:만 설정하면 Compose는 pull_policy에 따라 이미지를 사용하거나 가져옵니다(pull). build:만 설정하면 Compose는 구성된 빌더를 사용하여 이미지를 빌드하며, 프로젝트 이름과 서비스 이름을 조합하여 이미지 이름을 생성합니다. 두 항목을 모두 설정하면 pull_policy가 Compose의 가져오기 또는 빌드 여부를 결정합니다. 빌드 시에는 image:에 지정된 이름으로 결과물에 태그를 붙이는데, 이것이 바로 원하는 이름으로 이미지를 빌드하고 푸시하는 방법입니다. 빌더는 로컬에서 실행하거나 원격 Docker 호스트에서 실행할 수 있습니다.

이것이 두 설정의 전체적인 차이점입니다. 아래의 내용은 서버 운영 시 어떤 의미를 갖는지 설명합니다. 이 설명은 Docker Engine과 Compose 플러그인이 이미 설치되어 있다는 가정하에 작성되었습니다. VPS에서 Docker 실행하기에서 해당 설치 과정을 다룹니다.

세 가지 전체 형태

게시된 태그를 사용하며, 기본 pull 정책에 따라 이미지가 없으면 가져옵니다. 이 과정에서 Dockerfile은 사용되지 않습니다.

services:
  web:
    image: nginx:1.27
    restart: unless-stopped
    ports:
      - "80:80"

프로젝트 디렉터리의 Dockerfile에서 빌드합니다. 빌드 과정에서 Dockerfile에 필요한 이미지를 가져오거나 의존성을 다운로드할 수 있습니다.

services:
  web:
    build: .
    restart: unless-stopped
    ports:
      - "80:80"

빌드 후 docker compose build 태그를 지정합니다. 명시적인 pull 정책이 없으면 up은 빌드 전에 해당 이미지를 가져오려 시도합니다. 이후 docker compose push를 사용하여 해당 태그를 레지스트리로 전송할 수 있습니다.

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    image: registry.example.com/acme/web:1.4.2
    restart: unless-stopped
    ports:
      - "80:80"

context은 빌더로 전송되는 디렉터리입니다. dockerfile은 해당 컨텍스트를 기준으로 해석되므로, dockerfile: docker/prod.Dockerfile과 함께 context: .를 사용하는 것은 일반적이며 올바른 방식입니다. docker compose images를 실행하여 각 서비스 컨테이너의 이미지 이름과 이미지 ID를 확인하십시오. 서비스가 image:, build: 중 무엇을 사용하는지, 혹은 둘 다 사용하는지는 Compose 파일을 확인하여 확정할 수 있습니다.

Dockerfile을 수정했는데 왜 docker compose up이 다시 빌드하지 않습니까?

일반적인 up은 빌드를 요청하거나 빌드가 필요한 정책을 설정하지 않는 한 기존 이미지를 재사용하기 때문입니다.

Compose는 build: 섹션만 있는 서비스를 시작할 때, 이미지가 존재하면 해당 이미지를 사용합니다. Dockerfile을 읽거나 소스 파일의 변경 사항을 비교하거나 타임스탬프를 확인하지 않습니다. image:와 build:이 모두 있고 명시적인 pull_policy이 없는 경우, Compose는 먼저 이미지를 가져오려고(pull) 시도하며, 레지스트리나 플랫폼 캐시에 이미지가 없을 때만 빌드합니다. 이미지가 존재하면 충분한 것으로 간주합니다.

따라서 app.py를 수정하고 docker compose up -d을 실행하면, Compose는 컨테이너가 실행 중이라고 보고하고 이전 코드를 서비스합니다. 실패한 것이 없으므로 경고도 발생하지 않습니다. Compose가 컨테이너 이름 옆에 출력하는 상태 단어를 확인하면 알 수 있습니다. Compose가 교체한 컨테이너는 recreated 또는 started로 보고되지만, 그대로 두기로 결정한 컨테이너는 running으로 보고됩니다.

두 가지 확인 방법으로 이를 판별할 수 있습니다. docker compose images는 각 컨테이너가 사용하는 이미지 ID를 출력하므로, 배포 전후의 ID를 기록하여 비교하십시오. docker image ls에는 CREATED 열이 있지만, 캐시된 빌드와 재현 가능한 타임스탬프 때문에 날짜만으로는 최신 소스가 빌드되었는지 증명할 수 없습니다.

어떤 플래그가 재빌드를 강제하는가

  • docker compose up -d --build은 먼저 빌드를 수행한 뒤, 이미지가 변경된 컨테이너를 재생성합니다. 대부분의 사용자가 찾는 플래그입니다.
  • docker compose build web은 하나의 서비스를 빌드하고 아무것도 시작하지 않습니다. 이후 docker compose up --no-deps -d web을 실행하여 해당 컨테이너만 교체하고 나머지 스택은 그대로 유지할 수 있습니다.
  • docker compose build --no-cache web는 캐시된 레이어를 우회하여 서비스를 다시 빌드합니다.
  • docker compose build --pull은 FROM에 정의된 베이스 이미지의 최신 버전을 가져오려고 시도합니다. 따라서 node:22와 같이 변경되는 태그를 사용할 경우, 3월에 다운로드한 사본 대신 현재 내용을 가져오게 됩니다.
  • docker compose up -d --force-recreate은 설정과 이미지가 변경되지 않았더라도 컨테이너 재생성을 강제합니다. 이 플래그 자체가 빌드를 요청하는 것은 아니지만, 이미지가 없거나 풀 정책에 따라 필요한 경우 up가 여전히 빌드를 수행할 수 있습니다. --build를 의도했을 때 이 플래그를 사용하는 것은 흔히 발생하는 막다른 길입니다.

빌드 여부를 파일 내에서 결정할 수도 있습니다. Compose 명세에 따르면 pull_policy: build은 Compose가 이미지를 빌드하며, 이미 존재하더라도 다시 빌드함을 의미합니다. 이 경우 모든 up마다 빌드 비용이 발생하므로, 노트북 환경에서는 유용하지만 서버 환경에서는 거의 사용하지 않는 방식입니다.

services:
  web:
    build: .
    image: registry.example.com/acme/web:dev
    pull_policy: build

알아두어야 할 상호작용이 하나 더 있습니다. docker compose pull은 build 섹션이 있는 서비스에 대해서도 이미지 풀을 시도하며, 풀에 실패하면 이미지를 빌드해야 한다고 알립니다. 해당 서비스를 조용히 건너뛰려면 --ignore-buildable을 전달하십시오.

빌드 캐시가 배포 시간을 결정하는 방식

빌더는 Dockerfile의 각 명령어를 검사하여 해당 명령어와 입력값이 변경되지 않았을 때 재사용 가능한 캐시 결과가 있는지 확인합니다. COPY의 경우, 입력값에는 파일 내용과 메타데이터가 포함되며 수정 시간은 제외됩니다. 일단 한 레이어에서 캐시 적중이 실패하면, 그 레이어에 의존하는 후속 단계들은 모두 다시 빌드됩니다.

이 단 하나의 규칙이 배포 시간을 초 단위로 끝낼지 분 단위로 늘릴지를 결정합니다. Dockerfile은 거의 변경되지 않는 내용부터 커밋마다 변경되는 내용 순으로 작성하십시오.

FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]

npm ci는 COPY . . 위에 위치하므로, 소스 파일을 수정해도 설치 레이어는 캐시된 상태로 유지되며 빌드는 copy 단계부터 재개됩니다. 이 두 줄의 순서를 바꾸면 단 한 글자만 수정해도 모든 의존성을 다시 설치하게 됩니다. COPY . .가 npm ci가 빌드되는 기반 레이어를 무효화하기 때문입니다. 동일한 구조가 pip install -r requirements.txt과 go mod download에도 적용됩니다.

--no-cache은 오래된 레이어가 수정 사항을 가리고 있다고 의심될 때 사용하는 적절한 도구입니다. 하지만 이를 기본값으로 사용하는 것은 좋지 않습니다. Dockerfile의 순서 최적화를 통해 얻을 수 있는 캐시 재사용 이점을 모두 버리기 때문입니다.

이미지에서 설정하고 Compose에서 재정의할 수 있는 한 가지 요소가 있습니다. Dockerfile의 CMD는 이미지가 기본적으로 실행하는 명령어이며, 서비스의 command: 키는 이를 대체합니다. command와 entrypoint의 상호작용 방식을 이해하는 것이 중요합니다. Compose 재정의 설정으로 인해 새로 빌드된 이미지가 이전 이미지와 완전히 동일하게 동작할 수 있기 때문입니다.

빌드 컨텍스트와 .dockerignore

context: .은 프로젝트 디렉터리를 빌더가 사용할 수 있도록 제공합니다. 제외 설정을 하지 않으면 .git를 비롯해 소스 코드 옆에 둔 모든 데이터 디렉터리가 포함됩니다. BuildKit이 사용되지 않는 파일을 건너뛰고 변경 사항만 점진적으로 전송하긴 하지만, 변경 사항이 없는 프로젝트에서 transferring-context 단계가 멈춘다면 컨텍스트가 너무 크다는 신호입니다.

컨텍스트 루트에 있는 .dockerignore 파일은 해당 경로들을 전송 대상에서 제외합니다. 문법은 .gitignore와 유사합니다.

.git
node_modules
*.log
data/
.env

이 설정을 통해 두 가지 이점을 얻을 수 있습니다. 첫째, 전송량이 줄어들어 파일 전송 시간이 단축됩니다. 둘째, COPY . .가 실수로 .env을 이미지 내부로 복사하는 일을 방지하여, 이미지를 내려받은 사람이 해당 파일을 읽어내는 보안 사고를 막을 수 있습니다.

시간이 지날수록 빌드가 느려지는 주된 원인은 바인드 마운트입니다. 네임드 볼륨은 프로젝트 디렉터리 외부에 존재하지만, ./data:/var/lib/postgresql/data과 같은 바인드 마운트는 빌드 컨텍스트 내부에 위치합니다. 따라서 데이터베이스가 커질수록 매주 빌드 속도가 느려집니다. .dockerignore에 한 줄만 추가하면 이 문제를 해결할 수 있습니다. 네임드 볼륨을 사용하는 바인드 마운트에서 더 자세한 비교 내용을 다룹니다.

빌드 인자(build argument) 역시 이와 유사하지만 규모가 작은 위험을 내포합니다. args:를 통해 전달된 값은 이미지 히스토리나 출처 메타데이터에 남을 수 있으므로, 버전 번호와 같은 정보만 사용하고 토큰은 절대 포함하지 마십시오. 미리 정의된 프록시 인자는 Dockerfile에서 명시적으로 참조하지 않는 한 기본적으로 빌드 캐시와 docker history에서 제외됩니다. Compose의 Env 파일과 시크릿에서 자격 증명을 어디에 관리해야 하는지 설명합니다.

VPS에서 빌드할 것인가, 외부에서 빌드하여 가져올 것인가?

트래픽을 처리하는 서버에서 직접 빌드하는 방식은 가장 짧은 경로이므로 기본값으로 사용됩니다. 즉, git pull를 실행한 뒤 docker compose up -d --build를 실행하는 방식입니다. 아무도 의존하지 않는 작은 서버라면 이 방식도 괜찮습니다. 하지만 측정 가능한 두 가지 이유와, 문제가 발생했을 때만 드러나는 한 가지 이유 때문에 이 방식은 곧 한계에 부딪힙니다.

메모리. 빌드 과정에서는 컴파일러와 번들러가 실행 중인 애플리케이션과 함께 동작하며, 대부분의 스택에서 이들은 메모리를 매우 많이 소모합니다. JavaScript 번들러나 Rust 컴파일 작업은 1 GB VPS의 가용 메모리를 모두 소진할 수 있습니다. 메모리가 고갈되면 커널은 메모리 사용량, 할당 컨텍스트, oom_score_adj 등을 기반으로 산정한 점수에 따라 OOM(Out of Memory) 희생자를 선택합니다. 단순히 가장 큰 프로세스를 종료하는 것이 아닙니다. 빌드가 Killed와 함께 종료 코드 137로 중단될 수도 있고, 데이터베이스가 대신 종료되어 배포 도중 사이트가 다운될 수도 있습니다. dmesg -T | grep -i oom를 사용하면 커널 로그에서 OOM 메시지를 검색할 수 있으며, 이 로그를 읽으려면 권한이 필요합니다.

디스크. 빌드 후에는 이미지 레이어와 빌드 캐시가 남습니다. docker system df을 실행하면 디스크 사용량을 확인할 수 있습니다. BuildKit은 설정된 정책에 따라 주기적으로 가비지 컬렉션을 수행하여 캐시를 회수합니다. 사용하지 않는 이미지는 docker image prune로, 캐시된 레이어는 docker builder prune로 정리하십시오. 디스크가 가득 차면 빌드만 멈추는 것이 아닙니다. 데이터베이스의 쓰기 작업도 중단되며, 이러한 장애는 느린 배포보다 훨씬 큰 비용을 초래합니다.

재현성. 서버에서 빌드한 이미지를 푸시하거나 내보내지 않으면 해당 이미지는 오직 그 서버에만 존재합니다. 이전 이미지를 사용할 수 없는 경우, 롤백을 하려면 이전 커밋을 체크아웃하여 다시 빌드해야 합니다. 하지만 베이스 태그나 패키지 미러가 변경되었을 수 있으므로, 이 빌드가 이전과 동일한 결과를 보장하지는 않습니다. 외부에서 빌드하여 태그를 푸시하는 방식을 사용하면 롤백은 단순한 설정 변경이 됩니다. image:를 이전 태그로 지정하고 docker compose up -d을 실행하기만 하면 됩니다.

가장 권장되는 구성은 명확합니다. CI(지속적 통합) 환경에서 빌드를 수행하고 registry.example.com/acme/web:<git-sha>에 푸시합니다. VPS의 Compose 파일은 image:를 사용하며 build: 키는 아예 포함하지 않습니다. 이렇게 하면 배포는 메모리를 거의 사용하지 않는 두 개의 명령어로 완료됩니다.

docker compose pull
docker compose up -d

서버에서 docker login registry.example.com를 실행하여 비공개 태그를 가져오기 위한 자격 증명을 저장하십시오.

빌드 섹션은 삭제하지 말고 개발용으로 유지하십시오. 이때 파일 이름은 직접 지정해야 합니다.

# compose.dev.yaml
services:
  web:
    build:
      context: .
    pull_policy: build
docker compose -f compose.yaml -f compose.dev.yaml up -d --build

해당 파일의 이름을 compose.override.yaml이 아닌 compose.dev.yaml로 지정하십시오. Compose는 오버라이드 파일이 존재하면 자동으로 로드하므로, 실수로 복사된 오버라이드 파일이 서버에서 빌드를 다시 시작하게 만들 수 있습니다. 여러 Compose 파일 계층화하기에서 각 키가 병합되는 방식을 설명합니다.

다른 환경에서 빌드할 때 발생하는 아키텍처 문제

단일 플랫폼 이미지는 빌드된 CPU 아키텍처 정보를 포함합니다. Apple Silicon 노트북에서 ARM 이미지를 빌드하여 푸시한 뒤, 이를 x86_64 VPS에서 사용하면 문제가 발생합니다. 명시적인 플랫폼 지정 없이 호환되지 않는 캐시 이미지를 사용하려 할 때 Docker는 컨테이너 생성 과정에서 경고를 보냅니다. 에뮬레이션이 없으면 프로세스는 exec format error 오류와 함께 실패합니다. 이 오류는 바이너리 손상처럼 보이지만 실제로는 그렇지 않습니다. 대상 아키텍처를 명시하여 빌드하십시오.

docker buildx build --platform linux/amd64 \
  -t registry.example.com/acme/web:1.4.2 --push .

노트북이 x86인데 x86이 아닌 ARM VPS를 운영하는 경우에도 동일한 불일치가 발생합니다. 배포 대상과 동일한 아키텍처에서 CI가 빌드하도록 설정하면 이러한 문제를 방지할 수 있습니다. 멀티 플랫폼 이미지를 사용하는 것도 해결책입니다. 이미지를 가져올 때 Docker가 일치하는 변형을 자동으로 선택하기 때문입니다.

배포 후 확인 사항

  • docker compose images은 실행 중인 모든 컨테이너의 이미지와 태그를 출력합니다. 변경된 이미지 ID는 새로운 빌드가 서비스 중이라는 증거입니다.
  • docker compose config는 변수 치환이 완료된 병합 파일을 출력하므로, 명령을 실행하기 전에 Compose가 사용할 최종 이미지 이름을 확인할 수 있습니다.
  • docker compose logs -f web은 교체 후 첫 30초 동안 실행합니다. 시작과 종료를 반복하는 컨테이너는 restart policy에 설정된 경우에만 재시작되므로, 로그에서 원인을 확인하십시오.
  • docker image ls은 CREATED 열을 보여줍니다. 생성 타임스탬프만으로는 재빌드 여부를 판단할 수 없으므로, 빌드 출력 결과와 배포된 이미지 ID를 함께 확인하십시오.

파일을 작성 중이라면 VPS에서 Compose 파일의 기초에서 관련 키를 다루고 있으며, Compose 명령어 요약에서 나머지 하위 명령어를 확인할 수 있습니다.

FAQ

하나의 서비스에서 build와 image를 동시에 사용할 수 있습니까?

네, 직접 빌드하는 프로젝트에서는 이것이 일반적인 설정입니다. Compose가 build: 섹션에서 빌드를 수행하면, 그 결과물에 image: 값을 태그로 지정합니다. 명시적인 pull_policy가 없으면 up는 먼저 이미지를 가져오려고(pull) 시도합니다. 해당 태그는 docker compose push이 레지스트리로 전송하고 다른 머신이 가져오는 대상이 됩니다. image: 키가 없어도 Compose는 빌드를 수행하지만, 프로젝트와 서비스 이름을 따서 이미지 이름을 짓고 해당 속성이 누락되어 이미지를 푸시할 수 없다는 경고를 표시합니다.

docker compose up 명령이 Dockerfile 변경 사항을 반영하지 않는 이유는 무엇입니까?

일반적인 up은 빌드를 요청하거나 빌드가 필요한 정책을 설정하지 않는 한 기존 이미지를 재사용하기 때문입니다. Dockerfile이나 소스 파일과 이미지를 비교하여 재빌드 여부를 결정하지 않습니다. docker compose up -d --build를 실행하거나, docker compose build web을 실행한 뒤 docker compose up --no-deps -d web을 실행하여 특정 서비스를 교체하십시오. 서비스에 pull_policy: build를 설정하면 모든 up 실행 시 재빌드가 수행되므로 개발 환경에 적합합니다.

--build와 --force-recreate의 차이점은 무엇입니까?

--build는 이미지를 다시 빌드한 다음, 이미지가 변경된 컨테이너를 재생성합니다. --force-recreate는 설정이나 이미지가 변경되지 않았더라도 컨테이너 재생성을 강제합니다. 이 옵션 자체는 빌드를 요청하지 않습니다. 소스 코드나 Dockerfile을 변경했다면 --build 플래그를 사용해야 합니다. --force-recreate은 동일한 이미지를 유지하면서 쓰기 가능 레이어를 초기화하는 등 컨테이너 자체를 재설정할 때 사용합니다.

Docker 이미지는 VPS에서 빌드해야 합니까, 아니면 다른 곳에서 빌드해야 합니까?

다른 곳에서 빌드하고 서버가 트래픽을 처리 중일 때는 태그를 가져오는(pull) 방식을 권장합니다. 빌드 과정은 애플리케이션과 메모리를 두고 경쟁하며, 메모리가 부족해지면 커널은 조정 가능한 OOM 점수를 기준으로 희생자를 선택하는데, 이때 빌드 프로세스나 데이터베이스가 종료될 수 있습니다. 또한 빌드는 디스크에 캐시를 남깁니다(BuildKit이 가비지 컬렉션 정책에 따라 자동으로 회수하기는 합니다). 사용자가 없는 소규모 프로젝트라면 서버에서 빌드해도 괜찮으며, 나중에 build: 섹션을 개발 전용 Compose 파일로 분리하면 쉽게 이전할 수 있습니다.

Docker 빌드 캐시가 디스크를 가득 채우지 않게 하려면 어떻게 해야 합니까?

docker system df를 실행하여 이미지와 빌드 캐시가 각각 차지하는 공간을 확인하십시오. docker builder prune은 캐시된 레이어를 제거하고, docker image prune은 이전 빌드에서 남은 사용되지 않는(dangling) 이미지를 제거합니다. -a를 추가하면 사용되지 않는 모든 빌드 캐시나 컨테이너가 참조하지 않는 모든 이미지를 각각 제거합니다. 다만, 다음 빌드가 완전히 처음부터 수행됨을 보장하지는 않습니다. 서버에서 docker system prune -af --volumes을 예약 작업으로 설정하지 마십시오. 중지된 컨테이너와 사용되지 않는 익명 볼륨을 제거하므로, 익명 볼륨에 저장된 데이터베이스 데이터가 유지보수 중에 삭제될 위험이 있습니다.

이 글이 도움이 되었나요?