DockerfileのRUN --mountオプションでビルドを高速化・セキュア化する方法｜cacheマウントとsecretマウントの実践設計

この記事のポイント

・RUN --mount=type=cacheでpip/npm/aptのキャッシュを再利用できる
・RUN --mount=type=secretでAPIキーをイメージに含めずビルドに使える
・DOCKER_BUILDKIT=1（または compose build）で自動的に有効になる
・docker build --secret id=...,src=...でsecretをビルドに渡す

# Docker 23.0以降: デフォルトで有効（設定不要）

# Docker 20.x系: 環境変数で有効化
$ export DOCKER_BUILDKIT=1
$ docker build -t myapp:latest .

# バージョン確認
$ docker version --format '{{.Server.Version}}'
26.1.4

# BuildKitが有効か確認
$ docker buildx version
github.com/docker/buildx v0.14.1 ...

# syntax=docker/dockerfile:1
FROM python:3.12-slim-bookworm

WORKDIR /app
COPY requirements.txt .

# cache mount でpipキャッシュを保持（ビルド間で共有）
RUN --mount=type=cache,target=/root/.cache/pip     pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["python", "main.py"]

# syntax=docker/dockerfile:1
FROM node:20-alpine

WORKDIR /app
COPY package*.json ./

# npmのキャッシュを保持（UID=1000のnodeユーザー向けパスを指定）
RUN --mount=type=cache,target=/root/.npm     npm ci --prefer-offline

COPY . .
RUN npm run build
CMD ["node", "dist/index.js"]

# syntax=docker/dockerfile:1
FROM ubuntu:24.04

# cache mountで apt パッケージをキャッシュ
RUN --mount=type=cache,target=/var/cache/apt     --mount=type=cache,target=/var/lib/apt     apt-get update &&     apt-get install -y --no-install-recommends         build-essential         libpq-dev

# syntax=docker/dockerfile:1
FROM python:3.12-slim-bookworm

WORKDIR /app
COPY requirements.txt .

# secret mountでGitHub Packagesの認証トークンを渡す
# /run/secrets/github_token にマウントされる（ビルド後は消える）
RUN --mount=type=secret,id=github_token     pip install       --extra-index-url "https://$(cat /run/secrets/github_token)@pypi.example.com/simple/"       -r requirements.txt

COPY . .
CMD ["python", "main.py"]

# APIキーを一時ファイルに書き出す
$ echo "ghp_xxxxxxxxxxxxxxxxxxxx" > /tmp/github_token.txt

# ビルド時に --secret フラグで渡す
$ docker build     --secret id=github_token,src=/tmp/github_token.txt     -t myapp:latest .

# 後処理: 一時ファイルを削除
$ rm /tmp/github_token.txt

# 念のためイメージにsecretが残っていないことを確認
$ docker history myapp:latest
IMAGE          CREATED         CREATED BY                            SIZE
a1b2c3d4e5f6   2 seconds ago   RUN /bin/sh -c pip install ...       45.2MB
# ← APIキーの文字列はどこにも見えない

# .github/workflows/build.yml（抜粋）
- name: Build Docker image
  run: |
    echo "${{ secrets.PYPI_TOKEN }}" > /tmp/pypi_token
    docker build       --secret id=pypi_token,src=/tmp/pypi_token       -t myapp:latest .
    rm /tmp/pypi_token

# Dockerfileの先頭行を確認
$ head -1 Dockerfile
# syntax=docker/dockerfile:1   ← これが必要

# DockerのBuildKitが有効か確認
$ docker info | grep "buildkit"
  buildkitd: true

# pipのキャッシュパスをコンテナ内で確認
$ docker run --rm python:3.12-slim pip cache dir
/root/.cache/pip

# npmのキャッシュパスを確認
$ docker run --rm node:20-alpine npm config get cache
/root/.npm

# NG: srcファイルが存在しない
$ docker build --secret id=mytoken,src=/tmp/mytoken.txt .
ERROR: secret file '/tmp/mytoken.txt': no such file or directory

# OK: ビルド前にsrcファイルの存在を確認
$ test -f /tmp/mytoken.txt && echo "OK" || echo "ファイルが存在しません"
OK
$ docker build --secret id=mytoken,src=/tmp/mytoken.txt .