docker build 명령어 완벽 가이드: Dockerfile로 이미지 만들기

설명 (Description): docker build 명령어의 사용법을 자세히 알아봅니다. 빌드 컨텍스트(Build Context), Dockerfile, 태그(-t) 지정, 주요 옵션(-f, --build-arg) 활용법과 빌드 최적화 팁을 예제 코드와 함께 설명합니다.

TL;DR: docker build는 Dockerfile이라는 설계도와 '빌드 컨텍스트'라는 재료를 사용해 도커 이미지를 생성하는 핵심 명령어입니다. 명령어의 마지막에 위치하는 경로(예: .)는 빌드에 필요한 파일들이 담긴 컨텍스트를 지정하며, -t 옵션으로 이미지에 이름과 태그를 부여합니다. 빌드 과정은 Dockerfile의 각 명령어를 한 줄씩 실행하며 레이어(Layer)를 쌓는 방식으로 진행되며, .dockerignore 파일을 통해 불필요한 파일이 컨텍스트에 포함되지 않도록 하여 빌드 속도와 이미지 용량을 최적화할 수 있습니다.

---

H2: docker build 명령어란?

docker build 명령어는 사용자가 작성한 Dockerfile의 지침에 따라 새로운 도커 이미지를 생성하는 데 사용됩니다. 이 과정은 단순히 파일을 복사하는 것을 넘어, 필요한 소프트웨어를 설치하고, 환경 변수를 설정하며, 애플리케이션을 실행할 준비를 마치는 모든 단계를 포함합니다. 성공적으로 빌드된 이미지는 도커 허브(Docker Hub) 같은 레지스트리에 푸시하거나, 로컬 환경에서 직접 컨테이너로 실행할 수 있습니다.

기본적인 명령어 구조는 다음과 같습니다.

docker build [OPTIONS] PATH | URL | -

여기서 PATH는 이미지를 빌드하는 데 필요한 파일들이 위치한 디렉토리를 의미하며, 이를 '빌드 컨텍스트'라고 부릅니다.

Why it matters: docker build는 재현 가능하고(Reproducible) 이식성 있는(Portable) 애플리케이션 환경을 코드로 정의하고 생성하는 핵심 프로세스입니다. 이를 통해 개발자는 어떤 환경에서든 동일한 이미지를 만들고, "내 컴퓨터에서는 되는데..."라는 문제를 완벽하게 해결할 수 있습니다.

핵심 개념 1: 빌드 컨텍스트 (Build Context)

많은 초보 개발자들이 docker build . 명령어의 마지막 .이 의미하는 바를 간과합니다. 이 .은 현재 디렉토리를 빌드 컨텍스트로 사용하겠다는 의미입니다.

빌드 컨텍스트란 도커 데몬(Docker Daemon)이 이미지를 빌드하기 위해 접근할 수 있는 파일 및 디렉토리의 집합입니다. docker build 명령이 실행되면, CLI는 먼저 지정된 경로의 모든 파일(하위 디렉토리 포함)을 도커 데몬으로 전송합니다. 따라서 Dockerfile 내에서 COPY나 ADD 명령어로 파일을 이미지에 추가할 때, 그 파일들은 반드시 빌드 컨텍스트 내에 존재해야 합니다.

.dockerignore 파일의 중요성

빌드 컨텍스트에 불필요한 파일(예: node_modules, .git, 로그 파일, 로컬 설정 파일)이 포함되면 여러 문제가 발생합니다.

1. 빌드 속도 저하: 불필요한 대용량 파일까지 도커 데몬으로 전송되므로 빌드가 느려집니다.
2. 이미지 용량 증가: 이미지에 불필요한 파일이 포함되어 용량이 커집니다.
3. 보안 위험: 민감한 정보나 비밀 키가 이미지에 포함될 수 있습니다.

이를 해결하기 위해 .dockerignore 파일을 사용합니다. 이 파일에 명시된 파일이나 디렉토리는 빌드 컨텍스트에서 제외됩니다.

예시 .dockerignore 파일:

.git
.gitignore
node_modules
npm-debug.log
Dockerfile*
README.md

Why it matters: 빌드 컨텍스트를 정확히 이해하고 .dockerignore를 적극적으로 활용하는 것은 효율적이고 안전한 도커 이미지를 만드는 첫걸음입니다. 이는 빌드 시간을 단축하고, 이미지 크기를 줄이며, 잠재적인 보안 위협을 예방하는 가장 기본적인 최적화 방법입니다.

docker build 기본 사용법과 주요 옵션

간단한 Node.js 애플리케이션을 예제로 docker build 명령어 사용법을 알아보겠습니다.

프로젝트 구조:

.
├── .dockerignore
├── Dockerfile
├── package.json
└── server.js

Dockerfile:

FROM node:18-alpine

WORKDIR /app

# COPY package.json과 RUN npm install을 분리하여 캐시 효율 극대화
COPY package*.json ./
RUN npm install

# 나머지 소스 코드 복사
COPY . .

EXPOSE 8080
CMD ["node", "server.js"]

이미지 빌드 및 태그(-t) 지정

가장 기본적인 빌드 명령어는 다음과 같습니다.

# docker build -t [이미지 이름]:[태그] [빌드 컨텍스트 경로]
docker build -t my-node-app:1.0 .

• -t 또는 --tag: 생성될 이미지에 이름:태그 형식으로 식별자를 부여합니다. 태그를 생략하면 latest가 기본값으로 사용됩니다. 일반적으로 username/repository:version 형식으로 지정합니다.
• .: 현재 디렉토리를 빌드 컨텍스트로 사용하겠다는 의미입니다.

자주 사용되는 유용한 옵션들

옵션	설명	사용 예시
-f, --file	사용할 Dockerfile의 경로와 파일명을 직접 지정합니다. 기본값은 컨텍스트 루트의 Dockerfile입니다.	docker build -f ./dockerfiles/Dockerfile.dev .
--build-arg	빌드 시점에 Dockerfile 내의 ARG 변수에 값을 전달합니다.	docker build --build-arg VERSION=1.2 -t my-app .
--no-cache	빌드 과정에서 기존의 캐시된 레이어를 전혀 사용하지 않고 처음부터 새로 빌드합니다.	docker build --no-cache -t my-app .
--pull	빌드를 시작하기 전에 항상 베이스 이미지의 최신 버전을 다운로드하려고 시도합니다.	docker build --pull -t my-app .
--platform	다른 아키텍처(예: linux/arm64)용 이미지를 빌드할 때 사용합니다. (예: Apple Silicon에서 AMD64 서버용 이미지 빌드)	docker build --platform linux/amd64 -t my-app .

Why it matters: 다양한 옵션을 활용하면 개발, 테스트, 프로덕션 등 각기 다른 환경에 맞는 이미지를 유연하게 생성할 수 있습니다. 특히 --build-arg와 -f 옵션은 하나의 소스 코드로 여러 버전의 이미지를 관리해야 할 때 매우 유용합니다.

빌드 캐시와 최적화

도커는 이미지 빌드 속도를 높이기 위해 레이어 캐싱(Layer Caching) 메커니즘을 사용합니다. Dockerfile의 각 명령어는 이미지의 한 레이어(Layer)에 해당합니다.

빌드 시, 도커는 각 명령어 라인을 이전 빌드와 비교하여 변경 사항이 없는 경우, 기존에 만들어둔 캐시된 레이어를 재사용합니다. 변경이 감지된 라인부터는 캐시가 무효화되고, 해당 라인과 그 이후의 모든 라인은 새로 실행됩니다.

이러한 특성 때문에 Dockerfile 작성 순서는 매우 중요합니다.

• 변경이 잦지 않은 내용은 Dockerfile의 앞부분에 위치시킵니다. (예: RUN apt-get update && apt-get install -y ...)
• 변경이 잦은 내용은 뒷부분에 위치시킵니다. (예: COPY . .)

위 예시 Dockerfile에서 COPY package*.json .와 RUN npm install을 COPY . .보다 먼저 실행하는 이유가 바로 이것입니다. 소스 코드는 자주 바뀌지만 package.json은 상대적으로 덜 바뀌기 때문에, npm install로 생성된 무거운 node_modules 레이지를 최대한 캐시로 재사용하기 위함입니다.

Why it matters: 빌드 캐시를 이해하고 Dockerfile을 최적화하면 개발 사이클을 크게 단축할 수 있습니다. 특히 CI/CD 파이프라인에서는 몇 초의 빌드 시간 단축이 전체 개발 생산성에 큰 영향을 미칩니다.

---

결론 (요약 정리)

docker build는 Dockerfile과 빌드 컨텍스트를 기반으로 도커 이미지를 생성하는 필수적인 명령어입니다. 빌드 컨텍스트의 개념을 이해하고 .dockerignore를 활용하여 최적화하는 것이 중요하며, -t 옵션으로 이미지에 명확한 이름과 버전을 부여해야 합니다. 또한, 빌드 캐시의 원리를 이해하고 Dockerfile의 명령어 순서를 전략적으로 배치함으로써 빌드 속도를 획기적으로 개선할 수 있습니다.

References:

1. docker build command reference | Docker Documentation | 2025-09-27 | https://docs.docker.com/engine/reference/commandline/build/
2. Best practices for writing Dockerfiles | Docker Documentation | 2025-09-27 | https://docs.docker.com/develop/develop-images/dockerfile_best-practices/
3. Understanding the Docker build context | Snyk | 2023-08-22 | https://snyk.io/blog/understanding-the-docker-build-context/
4. How To Build a Node.js Application with Docker | DigitalOcean | 2023-01-18 | https://www.digitalocean.com/community/tutorials/how-to-build-a-node-js-application-with-docker
5. Speed up Docker builds with dockerignore | ITNEXT | 2023-05-15 | https://itnext.io/speed-up-docker-builds-with-dockerignore-347c65388c1c