이미지 생성 및 관리

Docker 이미지는 컨테이너를 실행하기 위한 읽기 전용 템플릿이다. 이미지는 주로 Dockerfile을 작성하여 빌드하며, 빌드된 이미지는 Docker Hub 같은 레지스트리를 통해 공유할 수 있다.

#1. Dockerfile 작성

#1-1. Dockerfile 주요 인스트럭션

# ENTRYPOINT ["java", "-jar"], CMD ["app.jar"] 인 경우
docker run myimage              # java -jar app.jar    ← 프로그램 + 기본 인자
docker run myimage other.jar    # java -jar other.jar  ← 프로그램 유지, 인자만 교체

# CMD ["python3", "app.py"] 만 있는 경우
docker run myimage              # python3 app.py  ← CMD 그대로 실행
docker run myimage bash         # bash            ← CMD 전체가 bash로 교체됨

#1-2. Dockerfile 작성 예시 — Python 애플리케이션

# 1. 베이스 이미지 지정 — Python 이 이미 들어 있는 공식 이미지
FROM python:3.13-slim

# 2. 환경 변수 설정
ENV APP_HOME=/app \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1

# 3. 작업 디렉토리 설정
WORKDIR $APP_HOME

# 4. 의존성 파일 먼저 복사 (레이어 캐시 최적화)
COPY requirements.txt .
RUN pip install -r requirements.txt

# 5. 애플리케이션 소스 복사
COPY . $APP_HOME

# 6. 포트 선언
EXPOSE 8080

# 7. 컨테이너 시작 명령어
CMD ["python", "app.py"]

RUN apt-get update && \
    apt-get install -y --no-install-recommends libpq5 && \
    rm -rf /var/lib/apt/lists/*

#1-3. .dockerignore — 빌드 컨텍스트 정리

docker build 실행 시 지정한 경로가 빌드 컨텍스트가 되어 빌더로 전송된다. .dockerignore 파일로 불필요한 파일을 제외하면 빌드 속도가 빨라지고, 민감한 파일이 이미지에 포함되는 것도 막을 수 있다.

# .dockerignore
.git
.gradle
build/
*.log
.env
secrets/
README.md

#2. 멀티 스테이지 빌드

멀티 스테이지 빌드는 Dockerfile에 FROM을 2번 이상 사용하는 것이다. FROM이 나올 때마다 새로운 단계(stage)가 시작되고, 최종 이미지는 마지막 FROM 단계만 남는다. 앞 단계는 빌드 결과물을 만들기 위한 임시 환경으로, 빌드가 끝나면 버려진다. 이를 통해 빌드 환경과 실행 환경을 분리하여 최종 이미지 크기를 크게 줄일 수 있다. 빌드에 필요한 JDK, Gradle, Node.js 등을 최종 이미지에 포함하지 않아도 된다.

#2-1. 일반 빌드 vs 멀티 스테이지 빌드

# ❌ 일반 빌드 — JDK + Gradle + 빌드 캐시까지 모두 포함
FROM gradle:8.14-jdk21
WORKDIR /app
COPY . .
RUN gradle bootJar --no-daemon
CMD ["java", "-jar", "build/libs/app.jar"]
# 결과 이미지 크기: 약 1.2GB

# ✅ 멀티 스테이지 빌드 — 실행에 필요한 JAR만 복사
# ── 1단계: 빌드 환경 ──────────────────────────────────────
FROM gradle:8.14-jdk21 AS builder
WORKDIR /build
COPY . .
RUN gradle bootJar --no-daemon

# ── 2단계: 실행 환경 (JRE만 포함한 경량 이미지) ──────────
FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=builder /build/build/libs/*.jar app.jar
EXPOSE 8080
CMD ["java", "-jar", "app.jar"]
# 결과 이미지 크기: 약 450MB

eclipse-temurin:21-jdk    726MB
eclipse-temurin:21-jre    459MB

#2-2. Node.js 멀티 스테이지 빌드 예시

# ── 1단계: 빌드 ────────────────────────────────────────────
FROM node:22 AS builder
WORKDIR /app
COPY package*.json .
RUN npm ci
COPY . .
RUN npm run build   # dist/ 디렉토리 생성

# ── 2단계: Nginx로 정적 파일 서빙 ──────────────────────────
FROM nginx:1.30
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80

npm error The `npm ci` command can only install with an existing package-lock.json

#3. 이미지 빌드

#3-1. docker build 주요 옵션

# 구형
docker build [OPTIONS] PATH

# 신형
docker image build [OPTIONS] PATH

# 기본 빌드
docker image build -t visit-counter:1.0 .

# 특정 Dockerfile 사용
docker image build -f Dockerfile.prod -t visit-counter:prod .

# ARG 값 전달
docker image build --build-arg VERSION=2.0 -t visit-counter:2.0 .

# 캐시 무시 (의존성 버전 변경 등 완전히 새로 빌드할 때)
docker image build --no-cache -t visit-counter:1.0 .

#3-2. 레이어 캐시 이해

Docker는 Dockerfile의 각 인스트럭션을 레이어(Layer) 로 저장하며, 변경되지 않은 레이어는 캐시를 재사용하여 빌드 속도를 높인다.

# ❌ 비효율적 — 소스 변경 시 pip install도 매번 재실행
COPY . /app
RUN pip3 install -r requirements.txt

# ✅ 효율적 — requirements.txt가 바뀌지 않으면 pip install 캐시 재사용
COPY requirements.txt .
RUN pip3 install -r requirements.txt
COPY . /app

#4. 이미지 관리

#4-1. 이미지 목록 조회

docker image ls 자체는 Docker 기본 명령어의 Step 8 에서 다뤘다. 여기서는 내가 만든 이미지를 확인하는 용도로만 쓴다.

docker image ls visit-counter

#4-2. 이미지 레이어 확인

# 이미지의 레이어 히스토리 확인 — 각 인스트럭션이 만든 레이어 크기 확인
docker image history visit-counter:1.0

# 예상 출력:
# IMAGE         CREATED       CREATED BY                       SIZE    COMMENT
# 15e7ed9eab62  17 sec ago    CMD ["java" "-jar" "app.jar"]    0B      buildkit.dockerfile.v0
# <missing>     17 sec ago    EXPOSE [8080/tcp]                0B      buildkit.dockerfile.v0
# <missing>     17 sec ago    COPY /build/.../app.jar app.jar  12.3kB  buildkit.dockerfile.v0
# <missing>     27 hours ago  RUN /bin/sh -c set -eux; ...     166MB   buildkit.dockerfile.v0
# ...
#
# 이미지 ID 는 맨 윗줄에만 있고 나머지는 <missing> 이다.
# 중간 레이어는 그 자체로 이미지가 아니라 최종 이미지의 구성요소이기 때문이다.

# 특정 레이어가 크다면 해당 인스트럭션에서 불필요한 파일을 포함하고 있을 가능성이 있다

#4-3. 이미지 태깅

# 버전 태그 추가 (이미지 복사가 아닌 동일 레이어 참조)
docker image tag visit-counter:1.0 visit-counter:latest

# Docker Hub 업로드를 위한 태깅 (username/repository:tag 형식 필수)
docker image tag visit-counter:1.0 myusername/visit-counter:1.0

#4-4. 이미지 삭제 — 빌드가 남기는 찌꺼기

docker image rm 의 기본 사용법은 Docker 기본 명령어의 Step 8 에 있다. 이미지를 직접 빌드하기 시작하면 거기서는 볼 일이 없던 것이 생긴다. 같은 태그로 다시 빌드할 때마다 태그를 잃은 이전 이미지(dangling 이미지)가 쌓이는 것이다.

# dangling 이미지(태그가 없는 이미지)만 삭제
docker image prune

# 컨테이너가 사용하지 않는 이미지를 전부 삭제 (태그가 있어도 지운다)
docker image prune -a

#5. Docker Hub에 이미지 공유

#5-1. Docker Hub 계정과 액세스 토큰 준비

이미지를 푸시하려면 먼저 Docker Hub 계정이 있어야 한다. hub.docker.com에서 가입한 뒤, 여기서 정한 Docker ID가 곧 이미지 이름 앞에 붙는 myusername 자리가 된다.

비밀번호 대신 액세스 토큰을 쓴다. 로그인한 뒤 계정 메뉴 → Personal access tokens 로 들어가 [Generate new token] 을 누른다.

계정 메뉴 → Personal access tokens → Generate new token

생성 폼에서 채울 것은 설명과 Access permissions 두 가지다.

Access permissions 를 Read & Write 로 바꾼다

#5-2. Docker Hub 로그인

docker login
# Username(Docker ID)과 Password(액세스 토큰) 입력

토큰을 표준 입력으로 넘기면 셸 히스토리에 값이 남지 않는다. 셸에 따라 형식이 다르다.

# 토큰을 파일에 저장해두고 파일에서 읽어 넘긴다
cat ~/dockerhub-token.txt | docker login -u myusername --password-stdin
rm ~/dockerhub-token.txt

# PowerShell
Get-Content ~/dockerhub-token.txt | docker login -u myusername --password-stdin
Remove-Item ~/dockerhub-token.txt

#5-3. 이미지 푸시(Push)

# 이미지명은 반드시 'username/repository:tag' 형식이어야 한다
docker image tag visit-counter:1.0 myusername/visit-counter:1.0
docker image push myusername/visit-counter:1.0

#5-4. 올린 것을 되받아 확인하기

docker image pull 은 Docker 기본 명령어의 Step 8 에서 다뤘다. 여기서는 내가 올린 이미지가 실제로 레지스트리에 있는지 확인하는 용도로 쓴다. 로컬 이미지를 지운 뒤 받아 보면 확실하다.

docker image rm myusername/visit-counter:1.0
docker image pull myusername/visit-counter:1.0

#6. 종합 실습 — visit-counter 이미지 빌드·최적화·배포

visit-counter 앱을 대상으로 앱 준비부터 이미지 빌드, 최적화, Docker Hub 배포까지 전 과정을 실습한다.

#6-1. 앱과 Dockerfile 준비

visit-counter 는 요청할 때마다 숫자를 하나 올려서 돌려주는 작은 Spring Boot 앱이다. 카운트를 /data/count.txt 파일에 저장하기 때문에, 볼륨을 붙였을 때와 안 붙였을 때의 차이가 눈에 보인다. 이 앱은 Docker Compose와 Part 4 의 AWS 배포까지 이어서 쓴다.

프로젝트 구조

visit-counter/
├── build.gradle
├── settings.gradle
├── .dockerignore
├── Dockerfile
└── src/main/java/com/example/
    └── VisitCounterApplication.java

settings.gradle

rootProject.name = 'visit-counter'

build.gradle

plugins {
    id 'org.springframework.boot' version '4.1.1'
    id 'io.spring.dependency-management' version '1.1.7'
    id 'java'
}

group = 'com.example'
version = '1.0.0'
java { toolchain { languageVersion = JavaLanguageVersion.of(21) } }

repositories { mavenCentral() }

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

> Could not find org.springframework.boot:spring-boot-starter-web:

VisitCounterApplication.java

package com.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;

import java.io.IOException;
import java.nio.file.*;

@SpringBootApplication
@RestController
public class VisitCounterApplication {

    // 카운트 파일 경로 — 볼륨 마운트 실습의 핵심
    private static final Path COUNT_FILE = Paths.get("/data/count.txt");

    public static void main(String[] args) throws Exception {
        Files.createDirectories(COUNT_FILE.getParent());
        SpringApplication.run(VisitCounterApplication.class, args);
    }

    @GetMapping("/")
    public String visit() throws IOException {
        long count = readCount() + 1;
        writeCount(count);
        return "방문 횟수: " + count + "\n";
    }

    @GetMapping("/count")
    public String count() throws IOException {
        return "현재 카운트: " + readCount() + "\n";
    }

    @GetMapping("/reset")
    public String reset() throws IOException {
        writeCount(0);
        return "카운터를 초기화했습니다.\n";
    }

    private long readCount() {
        try { return Long.parseLong(Files.readString(COUNT_FILE).trim()); }
        catch (Exception e) { return 0; }
    }

    private void writeCount(long n) throws IOException {
        Files.writeString(COUNT_FILE, String.valueOf(n));
    }
}

Dockerfile (멀티 스테이지 빌드)

# ── 1단계: Gradle로 JAR 빌드 ──────────────────────────────
FROM gradle:8.14-jdk21 AS builder
WORKDIR /build

# 의존성 정의 파일만 먼저 복사해 의존성을 받아 둔다.
# 이 두 파일이 바뀌지 않으면 아래 RUN 은 캐시로 건너뛴다.
COPY settings.gradle build.gradle ./
RUN gradle dependencies --no-daemon > /dev/null

# 자주 바뀌는 소스는 나중에 복사한다
COPY src ./src
RUN gradle bootJar --no-daemon

# ── 2단계: JRE만 포함한 경량 실행 이미지 ─────────────────
FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=builder /build/build/libs/visit-counter-1.0.0.jar app.jar
RUN mkdir /data
EXPOSE 8080
CMD ["java", "-jar", "app.jar"]

AS builder 는 이 단계에 이름을 붙이는 것으로, 아래 COPY --from=builder 에서 참조한다. COPY 를 두 번에 나눈 것은 3-2 레이어 캐시의 원칙 그대로다. 잘 바뀌지 않는 build.gradle 과 의존성 내려받기를 앞에, 매번 바뀌는 src 를 뒤에 둔다. COPY --from=builder /build/build/libs/... 는 builder 단계의 파일시스템(WORKDIR /build + bootJar 결과 경로)에서 JAR 를 가져와 app.jar 라는 이름으로 저장한다.

COPY --from=builder /build/build/libs/*.jar app.jar

#6-2. .dockerignore 작성

# visit-counter/.dockerignore
.git
.gradle
build/
*.log
.env
secrets/

#6-3. 이미지 빌드 및 크기 확인

# 이미지 빌드 (멀티 스테이지)
docker image build -t visit-counter:1.0 .

# 이미지 크기 확인
docker image ls visit-counter

# 레이어별 크기 확인
docker image history visit-counter:1.0

빌드한 이미지를 실제로 띄워 본다.

docker container run -d -p 8080:8080 --name visit-counter visit-counter:1.0

curl http://localhost:8080        # 방문 횟수: 1
curl http://localhost:8080        # 방문 횟수: 2
curl http://localhost:8080/count  # 현재 카운트: 2

브라우저에서 http://localhost:8080 으로도 접속해 보자. 요청할 때마다 숫자가 올라간다.

브라우저에서 새로고침할 때마다 숫자가 올라간다

/count 는 숫자를 올리지 않고 현재 값만 보여준다

#6-4. 빌드 캐시 효과 확인

# 소스 코드만 수정 후 재빌드
# VisitCounterApplication.java의 응답 메시지를 변경한다
# return "🎉 방문 횟수: " + count + " 번\n";

docker image build -t visit-counter:2.0 .
# → COPY src 이전 단계(의존성 내려받기)는 캐시 재사용, 이후만 재빌드
# 빌드 로그에서 단계 앞에 CACHED 가 붙은 줄이 캐시를 재사용한 단계다
# (Using cache 는 BuildKit 이전 구형 빌더의 문구다)

# 1.0과 2.0 이미지 비교
docker image ls visit-counter

 => CACHED [builder 3/6] COPY settings.gradle build.gradle ./
 => CACHED [builder 4/6] RUN gradle dependencies --no-daemon > /dev/null
 => [builder 5/6] COPY src ./src
 => [builder 6/6] RUN gradle bootJar --no-daemon

이 교안을 쓰며 소스 한 줄을 고친 뒤 다시 빌드한 시간을 재 봤다.

RUN --mount=type=cache,target=/root/.gradle gradle bootJar --no-daemon

#6-5. Docker Hub 배포

# Docker Hub 로그인
docker login

# 태그 추가
docker image tag visit-counter:1.0 myusername/visit-counter:1.0

# 푸시
docker image push myusername/visit-counter:1.0

# 다른 환경에서 내려받기
docker image pull myusername/visit-counter:1.0

#6-6. 정리

# 컨테이너 삭제 후 이미지 삭제
docker container rm -f visit-counter
docker image rm visit-counter:1.0 visit-counter:2.0

# 사용하지 않는 이미지 일괄 정리
docker image prune -a