Docker Build 사용법 완벽 가이드! Docker 이미지 빌드하기

Docker를 사용하는 가장 기본적인 과정은 애플리케이션을 실행할 수 있는 이미지를 만드는 것입니다.

컨테이너는 이미지(Image)를 기반으로 실행되며, 개발자가 작성한 애플리케이션 코드와 실행 환경을 하나의 패키지 형태로 관리할 수 있습니다.

이때 Docker 이미지를 생성하는 핵심 명령어가 바로 docker build입니다.

Docker Build는 Dockerfile을 기반으로 새로운 Docker 이미지를 생성하는 명령어입니다. 운영 환경과 동일한 실행 환경을 쉽게 구성할 수 있으며, 개발·테스트·배포 과정에서 가장 중요한 Docker 명령어 중 하나입니다.

이번 글에서는 Docker Build의 개념부터 기본 사용법, Dockerfile 작성 방법, 주요 옵션, 이미지 빌드 과정, 실무 활용 방법까지 자세히 알아보겠습니다.

Docker Build란 무엇인가?

Docker Build는 Dockerfile에 작성된 명령을 순서대로 실행하여 새로운 Docker Image를 생성하는 명령어입니다.

Dockerfile에는 다음과 같은 정보가 포함됩니다.

사용할 기본 이미지
패키지 설치
환경 설정
애플리케이션 코드 복사
실행 명령

Docker Build는 이 Dockerfile을 읽어 최종 실행 가능한 이미지를 생성합니다.

Docker Build는 언제 사용하는가?

다음과 같은 상황에서 사용합니다.

애플리케이션 이미지 생성
배포용 Docker 이미지 제작
개발 환경 구성
CI/CD 자동 빌드
서버 배포 자동화
커스텀 이미지 제작

Docker 기반 서비스를 운영한다면 반드시 사용하는 명령어입니다.

Docker Build 기본 구조

Docker Build의 기본 형식입니다.

docker build [옵션] 경로

가장 기본적인 사용 방법:

docker build .

현재 디렉터리의 Dockerfile을 읽어 이미지를 생성합니다.

Dockerfile이란?

Dockerfile은 Docker 이미지를 만들기 위한 설정 파일입니다.

예:

FROM nginx

COPY index.html /usr/share/nginx/html/

EXPOSE 80

구성:

FROM : 사용할 기본 이미지 지정
COPY : 파일 복사
EXPOSE : 사용할 포트 지정

Docker Build는 이 Dockerfile 내용을 기반으로 이미지를 생성합니다.

Docker 이미지 이름 지정하기

이미지 이름을 지정하려면 -t 옵션을 사용합니다.

docker build -t my-nginx .

생성 후 이미지 목록 확인:

docker images

출력:

REPOSITORY    TAG       IMAGE ID
my-nginx      latest    a12bc34de56

my-nginx라는 이름의 이미지가 생성된 것을 확인할 수 있습니다.

이미지 태그 지정하기

버전을 관리하려면 Tag를 지정하는 것이 좋습니다.

docker build -t my-app:v1.0 .

생성 결과:

REPOSITORY    TAG
my-app        v1.0

운영 환경에서는 버전별 Tag 관리가 일반적입니다.

다른 Dockerfile 사용하기

기본 파일명은 Dockerfile이지만 다른 파일을 지정할 수도 있습니다.

docker build \
-f Dockerfile.production \
-t my-app .

개발용과 운영용 Dockerfile을 분리할 때 사용합니다.

Build Context란 무엇인가?

Docker Build에서 마지막에 입력하는 경로를 Build Context라고 합니다.

예:

docker build -t my-app .

여기서 .은 현재 디렉터리를 의미합니다.

Docker는 해당 디렉터리 안의 파일을 Build Context로 전달합니다.

Docker Build 과정

Docker Build는 다음 순서로 진행됩니다.

Dockerfile 확인
Build Context 전송
각 명령 실행
Layer 생성
최종 Image 생성

예:

Dockerfile
   ↓
FROM 실행
   ↓
RUN 실행
   ↓
COPY 실행
   ↓
Image 생성

각 단계는 Layer 형태로 저장됩니다.

Docker Build 실무 활용 예제

Docker Build는 개발 환경부터 운영 배포까지 Docker 기반 서비스의 핵심 과정입니다. Dockerfile을 활용하면 동일한 실행 환경을 반복적으로 생성할 수 있어 배포 안정성을 높일 수 있습니다.

기본 이미지 빌드하기

현재 디렉터리의 Dockerfile을 사용합니다.

docker build -t my-app .

생성된 이미지 확인:

docker images

출력:

REPOSITORY   TAG
my-app       latest

Docker 이미지가 정상적으로 생성된 것을 확인할 수 있습니다.

Node.js 애플리케이션 이미지 만들기

예제 Dockerfile:

FROM node:22

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

CMD ["npm", "start"]

빌드:

docker build -t node-app:v1 .

실행:

docker run -p 3000:3000 node-app:v1

Node.js 애플리케이션이 Docker 컨테이너에서 실행됩니다.

Python 애플리케이션 이미지 만들기

Dockerfile:

FROM python:3.12

WORKDIR /app

COPY requirements.txt .

RUN pip install -r requirements.txt

COPY . .

CMD ["python", "app.py"]

빌드:

docker build -t python-app:v1 .

Python 실행 환경을 포함한 이미지가 생성됩니다.

특정 Dockerfile 사용하기

프로젝트마다 Dockerfile이 여러 개라면 -f 옵션을 사용합니다.

docker build \
-f Dockerfile.prod \
-t production-app .

운영 환경 전용 이미지를 생성할 때 사용합니다.

Build 진행 과정 확인하기

빌드 과정에서는 각 Layer 생성 과정을 확인할 수 있습니다.

예:

Step 1/5 : FROM nginx
 ---> Using cache

Step 2/5 : COPY index.html

Step 3/5 : RUN apt update

Successfully built image

각 명령이 하나의 Layer로 생성됩니다.

이미지 재빌드하기

기존 캐시를 사용하지 않고 다시 빌드하려면:

docker build --no-cache -t my-app .

패키지 업데이트나 환경 변경 후 새롭게 빌드할 때 사용합니다.

Build 진행 상황 자세히 보기

출력 형식을 변경할 수 있습니다.

docker build --progress=plain -t my-app .

CI/CD 로그 분석 시 유용합니다.

Linux 서버 문제 해결

개발팀에서 애플리케이션을 배포하는 과정에서 Docker 이미지 빌드 오류가 발생했습니다.

기존 빌드 명령:

docker build -t web-app .

실행 결과:

ERROR: failed to solve:
package.json not found

확인 결과 Dockerfile의 COPY 대상 파일과 실제 프로젝트 구조가 맞지 않았습니다.

프로젝트 구조:

project/

├── Dockerfile
├── src/
└── package.json

Dockerfile 수정:

COPY package.json .

수정 후 다시 빌드했습니다.

docker build -t web-app:v1 .

정상적으로 이미지가 생성되었습니다.

Docker Build 오류 대부분은 Dockerfile 설정, Build Context 경로, 파일 위치 문제에서 발생하기 때문에 구조를 먼저 확인하는 것이 중요합니다.

Docker Build 사용 시 주의사항

Docker Build를 사용할 때는 다음 사항을 확인해야 합니다.

첫 번째는 Build Context 크기입니다.

현재 디렉터리 전체가 Docker Engine으로 전달되기 때문에 불필요한 파일이 많으면 빌드 속도가 느려집니다.

.dockerignore 파일을 활용하는 것이 좋습니다.

예:

node_modules
.git
log
temp

두 번째는 Dockerfile Layer 순서입니다.

변경이 적은 명령을 위쪽에 배치하면 캐시 효과를 얻을 수 있습니다.

세 번째는 이미지 크기 관리입니다.

불필요한 패키지 설치를 줄이면 더 가벼운 이미지를 만들 수 있습니다.

네 번째는 운영 환경에서는 반드시 버전 Tag를 사용하는 것이 좋습니다.

예:

docker build -t app:v1.0 .

Best Practice

Docker Build를 사용할 때는 다음 방법을 추천합니다.

이미지 이름과 Tag를 명확하게 관리합니다.
.dockerignore를 사용합니다.
Dockerfile Layer 구조를 최적화합니다.
작은 Base Image를 선택합니다.
운영 배포용 이미지는 버전을 관리합니다.
CI/CD 환경에서는 자동 Build를 구성합니다.

이러한 방법을 적용하면 빠르고 안정적인 Docker 이미지 빌드 환경을 만들 수 있습니다.

자주 묻는 질문

Docker Build는 무엇을 생성하나요?

Dockerfile을 기반으로 Docker Image를 생성합니다.

Dockerfile 없이 Build할 수 있나요?

기본적으로 Dockerfile이 필요하지만 -f 옵션으로 다른 파일을 지정할 수 있습니다.

이미지와 컨테이너의 차이는 무엇인가요?

Image는 실행 환경이 저장된 템플릿이고, Container는 Image를 실행한 실제 서비스 환경입니다.

Build Cache는 왜 사용하나요?

이전에 생성된 Layer를 재사용하여 빌드 시간을 줄이기 위해 사용합니다.

마무리

Docker Build는 Docker 환경에서 애플리케이션 실행에 필요한 이미지를 생성하는 가장 기본적이고 중요한 명령어입니다.

Dockerfile을 기반으로 동일한 환경을 반복 생성할 수 있기 때문에 개발, 테스트, 운영 배포 과정에서 필수적으로 사용됩니다.

특히 .dockerignore 활용, Layer 최적화, Tag 관리, Build Cache 활용을 적용하면 더욱 빠르고 효율적인 Docker 이미지 관리가 가능합니다.