DockerfileのCOPYで何が起きているか｜ビルドコンテキストとレイヤー設計を理解する

この記事のポイント

・COPY命令はビルドコンテキストからファイルを取得し、イメージに新しいレイヤーを積む
・docker buildの遅さの多くは「コンテキストが大きすぎる」ことが原因。.dockerignoreで削る
・COPYの順序を「変更頻度の低いものを先」にするとキャッシュが最大限に効く
・COPY --fromでマルチステージビルドのビルド成果物だけを本番イメージに取り込める

COPY <src> <dest>

# カレントディレクトリ（.）をコンテキストとして指定
docker build .

# 別のディレクトリをコンテキストとして指定
docker build /home/app/myproject

$ docker build -t myapp:v1 .
[+] Building 12.3s (8/8) FINISHED
 => [internal] load build definition from Dockerfile         0.0s
 => => transferring dockerfile: 312B                         0.0s
 => [internal] load .dockerignore                            0.0s
 => => transferring context: 2B                              0.0s
 => [internal] load metadata for docker.io/library/python:3.12-slim  2.1s
 => [internal] load build context                            0.1s
 => => transferring context: 4.23kB                          0.1s
 => [1/4] FROM docker.io/library/python:3.12-slim@sha256:...  0.0s
 => [2/4] WORKDIR /app                                       0.0s
 => [3/4] COPY requirements.txt .                            0.0s
 => [4/4] RUN pip install --no-cache-dir -r requirements.txt  8.4s
 => exporting to image                                       0.9s

# .dockerignore の記述例
.git
.gitignore
node_modules
__pycache__
*.pyc
.env
*.log
tests/
docs/
README.md

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .        # レイヤー1
RUN pip install --no-cache-dir -r requirements.txt  # レイヤー2
COPY . .                       # レイヤー3
CMD ["python", "app.py"]

# NG: アプリコードが変わるたびにpip installが走る
FROM python:3.12-slim
WORKDIR /app
COPY . .                          # アプリ全体をコピー
RUN pip install --no-cache-dir -r requirements.txt
CMD ["python", "app.py"]

# OK: requirements.txtが変わらない限り、pip installはキャッシュされる
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .           # 変更頻度が低いファイルを先に
RUN pip install --no-cache-dir -r requirements.txt
COPY . .                          # アプリコードは後で
CMD ["python", "app.py"]

$ docker build -t myapp:v2 .
[+] Building 1.2s (8/8) FINISHED
 => [internal] load build definition from Dockerfile         0.0s
 => [internal] load build context                            0.0s
 => [3/4] COPY requirements.txt .                     CACHED
 => [4/4] RUN pip install --no-cache-dir -r...         CACHED
 => [5/5] COPY . .                                          0.1s
 => exporting to image                                       0.3s

# ステージ1: ビルド環境
FROM golang:1.22 AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app ./cmd/server

# ステージ2: 実行環境（最終イメージ）
FROM gcr.io/distroless/static-debian12
COPY --from=builder /app /app
ENTRYPOINT ["/app"]

# 公式イメージからcurlバイナリだけを取り込む例
FROM debian:12-slim
COPY --from=curlimages/curl:8.7.1 /usr/bin/curl /usr/local/bin/curl

# NG: コンテキスト（.）の外にある親ディレクトリのファイルは参照できない
COPY ../config/settings.yml .

# エラー例
ERROR: failed to solve: failed to read dockerfile: failed to copy files:
  COPY failed: forbidden path outside the build context: ../config/settings.yml ("/config/settings.yml")

# .dockerignoreにこう書いてある場合
config/

# Dockerfileでこうしてもエラーになる
COPY config/settings.yml .
# ERROR: COPY failed: file not found in build context or excluded by .dockerignore

# コンテキストに含まれるファイルを確認する（.dockerignoreを考慮したリスト）
docker build --no-cache --progress=plain . 2>&1 | grep "transferring context"

# より詳細：最小限のDockerfileでコンテキストの中身をlsで確認
# Dockerfile.debug として保存
FROM busybox
COPY . /ctx
RUN ls -la /ctx

docker build -f Dockerfile.debug . 2>&1 | grep -A 50 "RUN ls"