docker-build

Docker Build — イメージの構築と管理

docker build とイメージのライフサイクル管理に関する完全なリファレンスです。構築、タグ付け、検査、プッシュ、削除を行います。

使用する場面

ユーザーが次の内容に言及した場合は、必ずこのスキルを使用してください。

• 「docker build」、「イメージの構築方法」、「docker build コマンド」
• 「docker tag」、「docker push」、「イメージのプッシュ」
• 「docker images」、「イメージ管理」、「docker image」
• 「--build-arg」、「ビルド引数」
• 「docker history」、「docker inspect」、「イメージの確認」
• 「docker image prune」、「docker system prune」、「イメージのクリーンアップ」

✅ 使用する場面	❌ 代わりに使用
docker build の実行、タグ付け、プッシュ
ローカルイメージの管理
docker build CLI リファレンスが必要な場合
Dockerfile 自体の作成	docker-dockerfile
マルチプラットフォームビルド	docker-buildx
BuildKit の高度な機能	docker-buildx

docker build — 完全な構文

docker build [OPTIONS] PATH | URL | -

基本的なオプション

# Basic build
docker build -t myapp:v1 .

# Tag multiple tags at once
docker build -t myapp:v1.2.3 -t myapp:latest -t ghcr.io/org/myapp:v1.2.3 .

# Build from specific Dockerfile
docker build -f Dockerfile.prod -t myapp:prod .

# Build from Git repository
docker build -t myapp https://github.com/user/repo.git#main

# Build from stdin
cat Dockerfile | docker build -t myapp -
docker build -t myapp - <<EOF
FROM alpine:3.20
CMD ["echo", "hello"]
EOF

ビルド引数（--build-arg）

# Pass build arguments
docker build --build-arg NODE_VERSION=22 --build-arg ENV=production -t myapp .

# From file
docker build --build-arg $(cat .env.build | xargs) -t myapp .

ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
ARG ENV=development
ENV NODE_ENV=${ENV}
RUN echo "Building for ${NODE_ENV}"

オプション	目的
--build-arg KEY=VALUE	単一の引数を渡す
--build-arg-file FILE	ファイルから引数を読み込む
ARG KEY=default	デフォルト値付きで Dockerfile に定義する

ビルドの制御

# No cache (force full rebuild)
docker build --no-cache -t myapp .

# Pull base image even if cached locally
docker build --pull -t myapp .

# Quiet mode (only image ID)
docker build -q -t myapp .

# Set build target (multi-stage)
docker build --target builder -t myapp:builder .

# BuildKit output (export to local directory)
docker build --output type=local,dest=./out .

# Platform (with BuildKit)
docker build --platform linux/amd64 -t myapp .

# Add metadata
docker build --label "org.opencontainers.image.version=v1.2.3" -t myapp .

ビルドコンテキスト

# Current directory
docker build -t myapp .

# Specific directory
docker build -t myapp ./app

# Remote Git repo
docker build -t myapp https://github.com/user/repo.git#v1.0.0:subdir

# Pipe context via stdin (no context)
docker build -t myapp - < Dockerfile

イメージのタグ付け — docker tag

# Tag an existing image
docker tag myapp:v1 myapp:latest
docker tag myapp:v1 ghcr.io/org/myapp:v1

# Tag with registry
docker tag myapp:v1 registry.example.com:5000/myapp:v1

# Force overwrite existing tag
docker tag myapp:v1 myapp:latest   # replaces where :latest points

タグの命名規則

[registry[:port]/][namespace/]name[:tag|@digest]

ghcr.io/myorg/myapp:v1.2.3
│       │     │      │
│       │     │      └── tag (semver)
│       │     └── image name
│       └── namespace
└── registry

イメージの検査

# List images
docker images
docker image ls
docker image ls --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

# Inspect image details
docker inspect myapp:v1
docker inspect --format='{{.Config.Env}}' myapp:v1
docker inspect --format='{{.Created}}' myapp:v1

# View layer history
docker history myapp:v1
docker history --no-trunc --human myapp:v1

# Show digest
docker image ls --digests myapp
docker inspect --format='{{index .RepoDigests 0}}' myapp:v1

レジストリへのプッシュ

# Login
docker login
docker login ghcr.io -u USERNAME -p $TOKEN

# Push
docker push myapp:v1
docker push myapp --all-tags

# Push with digest
docker push myapp@sha256:abc123...

イメージのクリーンアップ

# Remove specific image
docker rmi myapp:v1
docker image rm myapp:v1

# Remove dangling images (<none>:<none>)
docker image prune

# Remove all unused images
docker image prune -a

# Full system cleanup
docker system prune -a --volumes

# Check disk usage
docker system df
docker system df -v

ワークフロー — 推奨するビルド手順

Step 1: Dockerfile の準備：作成済みであることを確認します（または docker-dockerfile を使用して生成します）。 Step 2: ビルド引数の設定：--build-arg、--label、--target を確認します。 Step 3: ビルドの実行：docker build -t myapp:v1 -t myapp:latest . Step 4: イメージの検証：docker images / docker history / docker inspect Step 5: リポジトリへのプッシュ：docker push の前に docker login を実行し、本番環境では digest で固定します。

注意点 — よくある落とし穴

• docker build -t myapp . はコンテキスト全体を送信します：.dockerignore がないと、node_modules/.git などすべてが送信されます。.dockerignore を使ってコンテキストを最小限にしてください。
• docker build --no-cache は時間がかかります：本当に必要な場合にのみ使用してください。通常のビルドではキャッシュされたレイヤーが再利用されます。
• docker tag は変更可能です：タグは付け替えられます。本番環境ではタグの代わりに digest（@sha256:...）を使用してください。
• ログインせずに docker push を実行すると、エラーが表示されないまま失敗します：必ず先に docker login を実行するか、CI の認証情報ヘルパーを使用してください。
• docker system prune -a は破壊的な操作です：未使用のイメージ、コンテナー、ネットワークをすべて削除します。確認せずに本番環境で実行しないでください。
• docker build --pull はベースイメージを変更します：ベースイメージが更新されていると、ビルド結果が異なる場合があります。

境界 — 対応範囲（適用する場面と適用しない場面）

分類	場面	説明
✅ 対応	docker build によるイメージの構築	完全なコマンド構文、コンテキスト管理、複数タグ
✅ 対応	docker tag によるタグ付け	命名規則、複数レジストリのタグ
✅ 対応	docker push によるイメージのプッシュ	リポジトリへのログイン、digest による固定
✅ 対応	イメージ管理（inspect/history/prune）	ローカルイメージのライフサイクル
⚠️ 条件付き	BuildKit の高度な機能（secret/cache/ssh）	docker-buildx を使用
⚠️ 条件付き	ネットワークが不安定な場合の大容量イメージのプッシュ	max-concurrent-uploads を設定
❌ 対象外	Dockerfile の作成	docker-dockerfile を使用
❌ 対象外	マルチプラットフォームビルド（arm64/amd64）	docker-buildx を使用
❌ 対象外	CI/CD パイプラインへの統合	docker-cicd を使用

このスキルを使用しない場面

❌ 使用しない	✅ 代わりに使用
Dockerfile 自体の作成	docker-dockerfile
マルチプラットフォーム／arm64 ビルド	docker-buildx
BuildKit の secrets/cache/SSH	docker-buildx
コンテナーの実行	docker-run
Docker の基本	docker-basics

セキュリティと安定性

• 本番レジストリにプッシュする前に、必ず docker scout で構築したイメージをスキャンしてください。
• ベースイメージにセキュリティパッチが適用された最新の状態にするため、docker build --pull を使用してください。
• ビルド引数にシークレットを埋め込まないでください（--build-arg はイメージの履歴から見えてしまいます）。代わりに BuildKit の --secret を使用してください。
• 監査証跡として、メタデータ（バージョン、git SHA、ビルドタイムスタンプ）を記録するために、イメージへ --label でタグ付けしてください。
• ディスク容量を確保し、攻撃対象領域を減らすため、docker image prune で未使用のイメージを定期的に削除してください。

📚 公式ドキュメントの参考情報

ドキュメント	アドレス
Docker Build	https://docs.docker.com/build/
docker build コマンド	https://docs.docker.com/reference/cli/docker/build/
docker tag	https://docs.docker.com/reference/cli/docker/image/tag/
docker push	https://docs.docker.com/reference/cli/docker/image/push/
docker image	https://docs.docker.com/reference/cli/docker/image/
Dockerfile リファレンス	https://docs.docker.com/reference/dockerfile/

🧭 Docker Skills Journey

📍 現在地：docker-build — イメージの構築と管理

basics → dockerfile → build → buildx → run → compose → ...

→ 次へ：docker-buildx — マルチプラットフォームビルドとBuildKitの高度な機能