Skip to content

Docker チートシート

コンテナでアプリケーションを開発・配布・実行するためのプラットフォーム。

01

はじめに

基本コマンド

docker run はコンテナを作成して起動します。-d でバックグラウンド実行、-p でホストポートをコンテナポートへマッピングします。pull はレジストリ(デフォルトは Docker Hub)からイメージをダウンロードします。

docker
# check version
docker --version

# pull an image
docker pull nginx:latest

# run a container
docker run -d --name mynginx -p 8080:80 nginx

# list running containers
docker ps

# list all containers (including stopped)
docker ps -a

# stop and remove a container
docker stop mynginx
docker rm mynginx

# list images
docker images

コンテナのライフサイクル

run は内部で create + start を行います。stop は SIGTERM を送り優雅な停止を促し、kill は即座に SIGKILL を送ります。pause は cgroup フリーザーを使い、プロセスを止めずにスナップショットを取るのに有用です。

docker
# create a container without starting it
docker create --name web nginx

# start a created (or stopped) container
docker start web

# stop gracefully (SIGTERM then SIGKILL after 10s)
docker stop web

# force kill immediately
docker kill web

# restart a container
docker restart web

# pause/resume (freezes process with cgroups)
docker pause web
docker unpause web

イメージの基本

イメージは読み取り専用のレイヤーです。rmi はコンテナがまだそのイメージを参照していると失敗します — 先にコンテナを削除しましょう。history は各レイヤーを作った命令とサイズを表示し、ビルドの最適化に有用です。

docker
# list local images
docker images
docker image ls

# remove an image
docker rmi nginx:latest
docker image rm nginx

# remove all dangling (untagged) images
docker image prune

# remove all unused images
docker image prune -a

# show image history (each layer)
docker history nginx:latest

システム情報

docker info はデーモンの設定(ストレージドライバ、ランタイム、レジストリ、swarm 状態)を表示します。system df は回収可能なスペースを明らかにします — 参照されないイメージや停止中のコンテナがディスクを浪費します。--format フラグは Go テンプレートで構造化出力を行います。

docker
# docker system-wide info
docker info
docker version

# disk usage breakdown (images, containers, volumes)
docker system df

# detailed disk usage with reclaimable space
docker system df -v

# running containers count
docker ps -q | wc -l

# show docker root directory and storage driver
docker info --format '{{.DockerRootDir}} {{.Driver}}'

クリーンアップと prune

prune は停止中/参照されないリソースを安全に削除します。system prune -a はどのコンテナからも参照されていないイメージも削除します。--volumes を加えると未使用のボリュームを削除します — データは取り返しがつきません。本番では慎重に使いましょう。

docker
# remove stopped containers
docker container prune

# remove dangling images
docker image prune

# remove unused volumes (CAUTION: data loss)
docker volume prune

# remove unused networks
docker network prune

# remove everything unused at once
docker system prune

# also remove volumes (very aggressive)
docker system prune -a --volumes

ヘルプの使い方

Docker はコマンドを管理用の名前空間にグループ化します(docker image、docker container、docker network、docker volume)。旧形式(docker rmi)と新形式(docker image rm)のどちらも動きます。サブコマンドの --help でフラグと使用法が表示されます。

docker
# list all commands
docker --help
docker help

# help for a specific command
docker run --help
docker image --help

# list management commands (grouped)
docker image --help
docker container --help
docker network --help

# show daemon config
docker info

# command reference online
# https://docs.docker.com/reference/
02

イメージの管理

イメージの pull

タグは可変のラベルです — 同じタグが時期により異なるイメージを指すことがあります。再現可能なデプロイにはダイジェスト(@sha256:...)で固定しましょう。--platform で pull すると異なるアーキテクチャ用のイメージを取得でき、x86 ホスト上での ARM ビルドに有用です。

docker
# pull latest tag
docker pull nginx

# pull specific tag
docker pull nginx:1.25-alpine

# pull all tags of a repository
docker pull -a alpine

# pull from a different registry
docker pull ghcr.io/user/repo:tag

# pull by digest (immutable, reproducible)
docker pull nginx@sha256:abc123...

# pull multiple platforms (multi-arch)
docker pull --platform linux/arm64 nginx

イメージのビルド

最後の . がビルドコンテキストです — デーモンへ送られるファイルです。.dockerignore で小さく保つとビルドが速くなります。デバッグ時には --no-cache で新しいレイヤーを強制します。BuildKit を使うとマルチステージのキャッシュ、SSH マウント、シークレットのマウントが可能になります。

docker
# build from Dockerfile in current dir, tag it
docker build -t myapp:1.0 .

# build with a different Dockerfile name
docker build -f Dockerfile.prod -t myapp:prod .

# build with build args
docker build --build-arg VERSION=1.2.3 -t myapp .

# build with no cache
docker build --no-cache -t myapp .

# build for a different platform
docker build --platform linux/arm64 -t myapp:arm .

# build using BuildKit (advanced features)
DOCKER_BUILDKIT=1 docker build -t myapp .

イメージのタグ付け

タグは同じイメージ ID を指す別名です。よくあるワークフローは、バージョンタグでビルドし、latest とメジャーバージョンのタグを加えます。レジストリの URL でタグ付けすると、そのレジストリへの push の準備が整います。

docker
# tag a local image
docker tag myapp:1.0 myapp:latest

# tag for pushing to Docker Hub
docker tag myapp:1.0 username/myapp:1.0

# tag for a private registry
docker tag myapp:1.0 registry.local:5000/myapp:1.0

# tag with multiple tags at once
docker tag myapp:1.0 myapp:stable
docker tag myapp:1.0 myapp:1

# tag by digest reference
docker tag myapp@sha256:abc... myapp:pinned

イメージの push

push の前に、イメージにレジストリの宛先でタグを付ける必要があります。push はレジストリにまだ存在しないレイヤーだけをアップロードします。自己署名証明書のプライベートレジストリでは、/etc/docker/daemon.json の insecure-registries に設定しましょう。

docker
# login to Docker Hub
docker login

# login to a private registry
docker login registry.local:5000 -u user -p pass

# push to Docker Hub
docker push username/myapp:1.0

# push all tags in a repository
docker push -a username/myapp

# push to private registry
docker push registry.local:5000/myapp:1.0

# logout when done
docker logout

イメージの検査

inspect は詳細な JSON を返します:アーキテクチャ、OS、レイヤー、env、entrypoint、設定。history は各レイヤーのコマンドとサイズを明らかにします — イメージ最適化の基礎です。manifest inspect は pull せずにリモートレジストリを確認できます。

docker
# low-level image metadata (JSON)
docker inspect nginx:latest

# specific field via Go template
docker inspect --format '{{.Arch}} {{.Os}}' nginx

# show image layers and sizes
docker history nginx:latest

# no-trunc to see full command for each layer
docker history --no-trunc nginx:latest

# inspect an image in a registry (manifest)
docker manifest inspect nginx:latest

イメージの保存と読み込み

save/load はイメージのレイヤーと履歴を保持します — イメージをオフラインで転送する正しい選択です。export/import は単一レイヤーへ平坦化し、履歴を失います。オンライン転送には tar ファイルよりレジストリの push/pull を推奨します。

docker
# save an image to a tar file
docker save -o myapp.tar myapp:1.0

# save multiple images
docker save -o bundle.tar myapp:1.0 nginx:latest

# load an image from a tar file
docker load -i myapp.tar

# pipe between hosts (no intermediate file)
docker save myapp:1.0 | gzip | ssh host 'gunzip | docker load'

# export a container filesystem (not an image)
docker export mycontainer | gzip > fs.tar.gz
03

コンテナの管理

コンテナの実行

-it は -i(stdin を開いたまま)と -t(tty を割り当て)を組み合わせ、対話セッションにします。--rm は終了後の後始末をします — 1 回限りのコマンドに最適です。--restart unless-stopped は再起動に耐えつつ、手動の停止は尊重します。

docker
# run in background with a name and port mapping
docker run -d --name web -p 8080:80 nginx

# run interactively with a terminal
docker run -it --name shell alpine sh

# run and auto-remove on exit
docker run --rm alpine echo hello

# run with a volume
docker run -d -v mydata:/data alpine

# run with environment variables
docker run -d -e MYSQL_ROOT_PASSWORD=secret mysql

# run with a restart policy
docker run -d --restart unless-stopped nginx

コマンドの実行(exec)

exec は既に稼働中のコンテナ内で新しいプロセスを実行します — 元の entrypoint は動き続けます。デバッグ、管理作業、1 回限りのスクリプト実行に使いましょう。デフォルトのユーザーはイメージの USER です。-u で上書きできます。

docker
# open an interactive shell in a running container
docker exec -it web sh

# run a command and return
docker exec web ls /usr/share/nginx/html

# run as a specific user
docker exec -u root web whoami

# set environment variables for the command
docker exec -e DEBUG=1 web env

# run with a working directory
docker exec -w /tmp web pwd

# run as detached (rarely useful)
docker exec -d web touch /tmp/marker

ログの表示

logs はコンテナのロギングドライバが取り込んだ stdout/stderr を表示します。docker logs と統合するため、アプリはファイルではなく stdout へログを書くべきです。--since/--until は RFC3339 のタイムスタンプか Go の期間(30m、2h)を受け付けます。

docker
# follow (tail) logs
docker logs -f web

# show last 100 lines
docker logs --tail 100 web

# show logs since a timestamp
docker logs --since 2024-01-01T00:00:00 web

# show logs from the last 30 minutes
docker logs --since 30m web

# add timestamps to each line
docker logs -t web

# show logs for a specific timeframe
docker logs --since 10m --until 5m web

コンテナの検査

inspect は設定、状態、ネットワーク、マウントをカバーする豊富な JSON を返します。Go テンプレートで特定のフィールドを取り出せます — スクリプティングに極めて有用です。LogPath で json-file ドライバがホストのどこにログを保存するか分かります。

docker
# full JSON metadata
docker inspect web

# container IP address
docker inspect --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' web

# container log path (json-file driver)
docker inspect --format '{{.LogPath}}' web

# mounts and volumes
docker inspect --format '{{json .Mounts}}' web

# container state (running, exited, etc.)
docker inspect --format '{{.State.Status}} {{.State.ExitCode}}' web

# all container ports
docker inspect --format '{{json .NetworkSettings.Ports}}' web

起動、停止、再起動

start は停止中のコンテナを元の設定のまま再開します。update は再作成せずに稼働中のコンテナの制約と再起動ポリシーを変更します — 本番でリソース制限を引き締めるのに有用です。

docker
# start a stopped container
docker start web

# stop with a custom timeout (seconds)
docker stop -t 30 web

# restart (keeps container intact)
docker restart web

# rename a container
docker rename web webserver

# update container config (e.g. restart policy)
docker update --restart unless-stopped web

# pause/resume (cgroup freezer)
docker pause web
docker unpause web

ファイルのコピー

cp は双方向に、また停止中のコンテナに対しても動きます — ホットフィックスの注入やログの取り出しに便利です。高頻度の同期向けには設計されていません。開発ワークフローには bind マウントかボリュームを使いましょう。tar+exec のトリックで大きなツリーを効率的にストリーミングできます。

docker
# copy a file from host to container
docker cp file.txt web:/tmp/

# copy from container to host
docker cp web:/etc/nginx/nginx.conf ./nginx.conf

# copy a directory
docker cp ./app web:/usr/src/app

# copy with archive mode (preserves perms)
docker cp -a ./config web:/etc/app

# copy to a stopped container (works too)
docker cp script.sh web:/script.sh

# tar stream from host to container stdin
docker exec -i web tar xzf - -C /app < app.tar.gz
04

Dockerfile の基本

FROM — ベースイメージ

FROM は最初の命令でベースレイヤーを定義します。最小限のベース(alpine、distroless、scratch)を選ぶと攻撃面とサイズが減ります。タグは変わり得るため、ダイジェストによる固定が再現可能なビルドを保証します。

docker
# use an official base image
FROM ubuntu:22.04

# pin a specific digest for reproducibility
FROM ubuntu@sha256:abc123def...

# multi-arch build (buildx picks the host arch)
FROM --platform=$BUILDPLATFORM golang:1.21 AS builder

# use a minimal image
FROM alpine:3.18

# scratch = empty image, for static binaries
FROM scratch

# use a previous build stage
FROM builder AS final

RUN — コマンドの実行

各 RUN がレイヤーを作ります。関連するコマンドを && で連結し、同じレイヤー内で後始末すればイメージが小さく保てます。exec 形式(JSON 配列)はシェルを呼ばないため変数展開や連結はできませんが、シグナルを正しく扱います。

docker
# install packages
RUN apt-get update && apt-get install -y curl

# clean up in the same layer to reduce size
RUN apt-get update && apt-get install -y --no-install-recommends curl \
    && rm -rf /var/lib/apt/lists/*

# combine commands with && to reduce layers
RUN mkdir -p /app/config && chown 1000:1000 /app/config

# use exec form (preferred) to ensure signals
RUN ["npm", "install"]

# use a shell for variables and chaining
RUN VERSION=1.0 && wget https://example.com/v${VERSION}.tar.gz

COPY と ADD

ローカルのファイルには COPY が推奨です — 明示的で予測可能です。ADD には魔法があります:URL の取得と tar/zip アーカイブの自動展開です。この魔法は思わぬ挙動を招くため、展開が必要なときだけ ADD に手を伸ばしましょう。どちらもレイヤーを作ります。

docker
# copy a file into the image
COPY package.json /app/

# copy a directory
COPY src/ /app/src/

# copy with ownership
COPY --chown=node:node package.json /app/

# copy from a previous build stage
COPY --from=builder /app/dist /app/dist

# ADD can fetch URLs and extract archives
ADD https://example.com/app.tar.gz /tmp/

# ADD extracts local tar archives automatically
ADD app.tar.gz /usr/src/

WORKDIR

WORKDIR は以後の命令とコンテナのデフォルトの作業ディレクトリを設定します。ディレクトリがなければ作成します。RUN 内の cd より常に WORKDIR を推奨 — cd はレイヤーをまたいで残りません。分かりやすさのため絶対パスを使いましょう。

docker
# set the working directory
WORKDIR /usr/src/app

# subsequent RUN, CMD, COPY use this dir
COPY . .
RUN npm install

# WORKDIR creates the directory if it does not exist
WORKDIR /opt/data/logs

# use a relative path (relative to previous WORKDIR)
WORKDIR sub

# avoid this anti-pattern (use absolute paths)
WORKDIR /app
RUN cd /app && do_something   # cd is lost after RUN

USER

USER は RUN、CMD、ENTRYPOINT のユーザー(と省略可能なグループ)を設定します。非 root での実行は重要なセキュリティのベストプラクティスです。ユーザーはイメージ内に存在する必要があります。数値の UID はイメージ間で移植可能で、名前解決の問題を避けられます。

docker
# create a non-root user and switch to it
RUN groupadd -r app && useradd -r -g app appuser
USER appuser

# run subsequent instructions as this user
RUN whoami   # appuser

# use a numeric UID for portability
USER 1000

# USER in compose/runtime overrides this
USER 1000:1000

# common pattern: node image ships a 'node' user
FROM node:20-alpine
USER node

.dockerignore

.dockerignore はデーモンへ送るビルドコンテキストを減らします — ビルドが速くなり、コンテキストが小さくなり、.env のようなシークレットがイメージレイヤーへ漏れるのを防ぎます。構文は .gitignore と似ています。node_modules やビルド中に再生成される成果物は必ず除外しましょう。

docker
# .dockerignore — exclude files from the build context

# version control
.git
.gitignore

# dependencies (fetched inside the image)
node_modules
npm-debug.log

# build artifacts
dist
build
*.log

# local env files (NEVER bake secrets)
.env
.env.local

# docker files themselves
Dockerfile
docker-compose*.yml

# OS files
.DS_Store
Thumbs.db
05

Dockerfile 応用

CMD と ENTRYPOINT

ENTRYPOINT が実行ファイルを定義し、CMD が上書き可能なデフォルト引数を提供します。シグナルをプロセスが直接受け取れるよう exec 形式(JSON 配列)を使いましょう — シェル形式は /bin/sh -c で包み、優雅な停止が壊れます。定番パターン:ENTRYPOINT スクリプト + CMD のデフォルト引数。

docker
# CMD: default command, easily overridden
CMD ["nginx", "-g", "daemon off;"]

# override at runtime
# docker run myimage nginx -v

# ENTRYPOINT: fixed command, CMD becomes args
ENTRYPOINT ["nginx"]
CMD ["-g", "daemon off;"]

# runtime args append to ENTRYPOINT
# docker run myimage -v  ->  nginx -v

# shell form (avoid — no signal handling)
CMD nginx -g "daemon off;"

# script as entrypoint that accepts args
ENTRYPOINT ["./entrypoint.sh"]
CMD ["--help"]

ENV — 環境変数

ENV はビルド時と実行時に見えるイメージレベルの変数を作ります。最終イメージへ設定を漏らさないため、ビルド専用の値には ARG を使いましょう。exec 形式の CMD/ENTRYPOINT では ${VAR} はシェルで展開されません — sh -c で包みましょう。

docker
# set a persistent env var (baked into image)
ENV NODE_ENV=production
ENV PATH=/app/node_modules/.bin:$PATH

# use in subsequent RUN instructions
ENV VERSION=1.2.3
RUN wget https://example.com/v${VERSION}.tar.gz

# multiple in one line
ENV NODE_ENV=production PORT=3000 LOG_LEVEL=info

# override at runtime
# docker run -e NODE_ENV=development myapp

# view env vars of a container
docker exec web env

# reference env vars in CMD
ENV APP_PORT=3000
CMD ["sh", "-c", "node server.js ${APP_PORT}"]

ARG — ビルド引数

ARG の値は、それを宣言したステージのビルド中にだけ存在します。実行時のコンテナには引き継がれません — 実行時に値を持ちたいなら ENV を使いましょう。FROM の前に宣言した ARG は「グローバル」ですが、各ステージで使うには再宣言が必要です。

docker
# declare a build argument with a default
ARG VERSION=latest
FROM base:${VERSION}

# use ARG only during build (not at runtime)
ARG NODE_ENV=production
RUN echo "Building for ${NODE_ENV}"

# multi-stage: ARG must be redeclared per stage
ARG VERSION
FROM base:${VERSION}
ARG VERSION
RUN echo ${VERSION}

# pass at build time
# docker build --build-arg VERSION=1.0 .

# ARG not available in CMD (use ENV to pass through)
ARG PORT=3000
ENV PORT=${PORT}
CMD ["sh", "-c", "serve --port ${PORT}"]

EXPOSE

EXPOSE はドキュメントです — ポートを公開しません。公開は実行時の -p(host:container)か Compose の ports: で行われます。EXPOSE はツールが意図されたポートを理解する助けになり、レガシーネットワークでの自動リンクも可能にします。

docker
# document which port the container listens on
EXPOSE 80

# expose multiple ports
EXPOSE 80 443

# expose with protocol
EXPOSE 53/udp

# EXPOSE does NOT publish the port
# you still need -p at runtime
# docker run -p 8080:80 myapp

# in compose, expose vs ports
# expose: only to linked services
# ports: published to the host

# view exposed ports
docker inspect --format '{{json .Config.ExposedPorts}}' myapp

LABEL とメタデータ

LABEL はイメージにキー・バリューのメタデータを付けます。レジストリやツールとの相互運用のため、OCI の org.opencontainers.image.* ラベルを採用しましょう。ラベルはバージョン、ソース、ライセンス、CI ビルド情報の追跡に有用です。

docker
# add a label (key=value metadata)
LABEL maintainer="[email protected]"
LABEL version="1.0"
LABEL description="My web app"

# multiple labels in one instruction
LABEL org.opencontainers.image.title="myapp" \
      org.opencontainers.image.version="1.0" \
      org.opencontainers.image.source="https://github.com/me/myapp"

# view labels
docker inspect --format '{{json .Config.Labels}}' myapp

# filter images by label
docker images --filter "label=version=1.0"

# deprecated: MAINTAINER (use LABEL maintainer instead)
# MAINTAINER Alice <[email protected]>

Dockerfile の VOLUME

VOLUME はマウントポイントを宣言します。ホストパスを bind しない限り、Docker は初回実行時に匿名ボリュームを作ります。このディレクトリが状態を持つデータを保持することを示す合図です。落とし穴:COPY の後に VOLUME を宣言すると、コピーしたファイルが空のボリュームで覆い隠されることがあります。

docker
# declare an anonymous volume mount point
VOLUME /data

# multiple mount points
VOLUME /data /config /logs

# at runtime, Docker creates an anonymous volume
# docker run -v mydata:/data myapp  (named instead)

# VOLUME in Dockerfile: any files copied to /data
# are copied into the new anonymous volume on first run

# inspect volumes
docker inspect --format '{{json .Mounts}}' myapp

# avoid: VOLUME after COPY can hide your data
COPY ./config /config
VOLUME /config   # new empty volume shadows /config
06

マルチステージビルド

基本のマルチステージ

マルチステージビルドは最終成果物だけを実行イメージへコピーします — ビルドツール、ソース、開発依存はビルダーステージに残ります。結果:小さく安全な実行イメージです。COPY --from で参照できるよう、AS でステージに名前を付けましょう。

docker
# stage 1: build
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# stage 2: runtime (small)
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

ビルドステージの選択

--target は指定したステージまでだけビルドし、後のステージをスキップします。これで dev、test、本番に 1 つの Dockerfile が使えます:CI には 'test'、本番には 'final'。BuildKit は独立したステージを自動的に並列化します。

docker
# build only up to a named stage
# docker build --target builder -t myapp:dev .

FROM node:20 AS builder
RUN npm ci && npm run build

FROM node:20-alpine AS test
COPY --from=builder /app /app
RUN npm test

FROM nginx:alpine AS final
COPY --from=builder /app/dist /usr/share/nginx/html

# target a specific stage
# docker build --target test .

スリムな実行イメージ

静的バイナリ(Go、Rust)には、scratch が攻撃面ゼロの最小のイメージを作ります。HTTPS のため CA 証明書を加えましょう。Distroless はルート CA と非 root ユーザー付きの最小ベースで、動的言語やシェルなしの実行環境に最適です。

docker
# build stage
FROM golang:1.21 AS builder
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -o app -ldflags="-s -w" .

# scratch = empty image, only the static binary
FROM scratch
COPY --from=builder /src/app /app
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
ENTRYPOINT ["/app"]

# result: ~10MB image
# or use distroless for a minimal OS base
FROM gcr.io/distroless/static
COPY --from=builder /src/app /app
ENTRYPOINT ["/app"]

コンパイル言語のビルダーパターン

フル SDK のイメージでコンパイルし、成果物を実行専用イメージ(JRE)へコピーします。イメージが劇的に縮み(JDK 約 600MB に対し JRE 約 200MB)、ビルドツールが本番から除かれます。COPY 前の依存の先回り取得でレイヤーキャッシュが向上します。

docker
# stage 1: compile
FROM maven:3.9 AS builder
WORKDIR /build
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src ./src
RUN mvn package -DskipTests

# stage 2: runtime with only the JRE
FROM eclipse-temurin:21-jre-alpine
COPY --from=builder /build/target/*.jar /app/app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

# benefits: no JDK, no source, no Maven cache in runtime

外部イメージからのコピー

COPY --from は任意のイメージから pull できます — ビルドステージなしで複数のベースからツールを組み立てるのに有用です。ステージはインデックス(0 起点)でも参照できますが、AS での名前付けの方が明快です。再現性のため外部イメージはダイジェストで固定しましょう。

docker
# copy a binary from another image (no build stage needed)
FROM alpine:3.18
COPY --from=nginx:alpine /usr/sbin/nginx /usr/sbin/nginx
COPY --from=nginx:alpine /etc/nginx /etc/nginx
RUN apk add --no-cache libpcre2
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

# use a specific digest for reproducibility
COPY --from=redis:7@sha256:abc... /usr/local/bin/redis-server /usr/local/bin/

# copy from a built stage referenced by index
COPY --from=0 /build/output /app

BuildKit の機能

BuildKit はキャッシュマウント(npm/pip のキャッシュがイメージを肥大させずビルド間で残る)、シークレットマウント(認証情報がレイヤーに触れない)、プライベートリポジトリ向けの SSH 転送、きれいな複数行 RUN のための heredoc 構文を可能にします。Dockerfile フロントエンドのバージョン固定に # syntax ディレクティブを加えましょう。

docker
# enable BuildKit
# DOCKER_BUILDKIT=1 docker build .

# syntax directive for latest frontend
# syntax=docker/dockerfile:1
FROM alpine

# mount a cache (persists across builds, not in image)
RUN --mount=type=cache,target=/root/.npm npm ci

# mount a secret (never written to layers)
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci

# mount an SSH socket for private repos
RUN --mount=type=ssh git clone [email protected]:me/repo.git

# heredoc for multi-line scripts
RUN <<EOF
set -ex
apk add --no-cache curl
mkdir -p /app/data
EOF
07

ボリューム

ボリュームの作成と使用

名前付きボリュームは Docker が管理し、データ永続化の推奨方法です。コンテナの削除後も生き延び、ホストのファイルシステム構成に依存しません。:ro 接尾辞で読み取り専用マウントになります。inspect で /var/lib/docker/volumes の下のディスク上のパスが分かります。

docker
# create a named volume
docker volume create mydata

# use it in a container
docker run -d -v mydata:/data alpine sh -c "sleep 1h"

# inspect the volume
docker volume inspect mydata

# mount read-only
docker run -v mydata:/data:ro alpine ls /data

# mount with a different filesystem (e.g. tmpfs)
docker run --tmpfs /cache alpine

# default volume driver: local
docker volume create --driver local mydata

ボリュームの一覧と検査

ls が名前付きボリュームを一覧し、inspect がドライバとマウントポイントを表示します。どのコンテナがボリュームを使っているかは、ps を volume でフィルタして調べましょう。ボリュームは Linux ホストでは /var/lib/docker/volumes/<name>/_data にあります — docker exec 経由でアクセスし、ホスト側を直接編集しないでください。

docker
# list all volumes
docker volume ls

# filter by name
docker volume ls -q --filter name=mydata

# show volume details (driver, mountpoint, options)
docker volume inspect mydata

# find the on-disk path
docker volume inspect --format '{{.Mountpoint}}' mydata

# find containers using a volume
docker ps -a --filter volume=mydata --format '{{.Names}}'

# check volume disk usage
docker system df -v | grep mydata

ボリュームドライバ

local ドライバはマウントオプション経由で NFS、ブロックデバイス、tmpfs に対応します。クラウドストレージ(EBS、Azure Disk)にはプラグインドライバを使いましょう。ドライバがストレージを抽象化するため、run コマンドを変えずにコンテナがホスト間を移動できます — Swarm/Kubernetes に重要です。

docker
# local driver (default, on host disk)
docker volume create --driver local mydata

# NFS volume
docker volume create --driver local \
  --opt type=nfs \
  --opt o=addr=10.0.0.5,rw \
  --opt device=:/export/data nfsvol

# tmpfs (in-memory, ephemeral)
docker run --tmpfs /cache alpine

# block device
docker volume create --driver local \
  --opt type=ext4 \
  --opt device=/dev/sdb1 blockvol

# third-party drivers (e.g. cloud)
docker volume create --driver rexray/ebs ebsvol

ボリュームのバックアップ

一時コンテナでボリュームとホストディレクトリの両方をマウントし、内容を tar すればボリュームをバックアップできます。復元はその逆です。このパターンはどのボリュームドライバでも機能し、自動バックアップスクリプトの基礎です。

docker
# back up a volume to a tar file
docker run --rm -v mydata:/data -v $(pwd):/backup alpine \
  tar czf /backup/mydata.tar.gz -C /data .

# restore a volume from a tar file
docker volume create mydata2
docker run --rm -v mydata2:/data -v $(pwd):/backup alpine \
  tar xzf /backup/mydata.tar.gz -C /data

# migrate data between volumes
docker run --rm -v src:/src -v dst:/dst alpine \
  cp -a /src/. /dst/

# snapshot using a temporary container
docker run --rm -v mydata:/data alpine ls -la /data

ボリュームの削除

コンテナが参照している間はボリュームを削除できません(先にコンテナを削除しましょう)。prune は未使用のボリュームだけを削除します。ボリュームの削除は取り返しがつきません — データは恒久的に失われます。prune の前に必ず本番ボリュームをバックアップしましょう。

docker
# remove a named volume (must not be in use)
docker volume rm mydata

# remove all unused volumes
docker volume prune

# remove volumes older than 24h not used
docker volume prune --filter "until=24h"

# force remove (even if a stopped container referenced it)
docker volume rm -f mydata

# remove with a label filter
docker volume prune --filter "label=temporary"

# CAUTION: data is gone permanently
docker volume rm mydata

コンテナ間でのボリューム共有

複数のコンテナが同じボリュームをマウントして状態を共有できます。--volumes-from は他のコンテナのボリュームマウントを複製します — サイドカーパターンに便利です。読み取り専用の利用側には :ro を加えましょう。破損を避けるため同時書き込みを調整してください。ロックが必要なアプリもあります。

docker
# share a volume between two containers
docker run -d --name db -v shared:/data alpine sleep 1h
docker run -d --name app -v shared:/data alpine sleep 1h

# use --volumes-from to copy a container's mounts
docker run -d --name helper --volumes-from db alpine sleep 1h

# read-only shared volume
docker run -d --name reader -v shared:/data:ro alpine sleep 1h

# compose: shared volume across services
# volumes:
#   shared:
# services share 'shared' via volumes: ['shared:/data']

# verify both see the same data
docker exec db sh -c "echo hi > /data/msg"
docker exec app cat /data/msg
08

Bind マウント

基本の Bind マウント

bind マウントはホストのパスをコンテナへ直接マッピングします — ホストの編集が即座に反映されるライブ開発に最適です。ホストのパスは絶対パスで。:ro 接尾辞がコンテナからホストへの書き込みを防ぎます。明快さのため、モダンな構文では --mount を使いましょう。

docker
# bind mount a host directory (modern syntax)
docker run -d --type bind --source $(pwd)/app --target /app nginx

# short form (-v)
docker run -d -v $(pwd)/app:/app nginx

# absolute host path required
docker run -v /home/me/app:/app nginx

# mount a single file
docker run -v /home/me/app.conf:/etc/app/app.conf:ro nginx

# mount read-only
docker run -v $(pwd)/app:/app:ro nginx

# compose equivalent
# volumes:
#   - ./app:/app

読み取り専用の Bind マウント

読み取り専用マウントは、ホストの設定をコンテナの書き込みから守ります — セキュリティ上重要です。--read-only でルートファイルシステム全体が不変になり、/tmp やログディレクトリには書き込み可能なマウントが明示的に必要になります。これでコンテナが侵害に強くなります。

docker
# mount config read-only
docker run -v /etc/myapp:/etc/myapp:ro myapp

# --mount equivalent with explicit type
docker run --mount type=bind,source=/etc/myapp,target=/etc/myapp,readonly myapp

# read-only root filesystem (extra security)
docker run --read-only -v /tmp myapp

# combine read-only root with a writable tmpfs
docker run --read-only --tmpfs /tmp --tmpfs /var/cache myapp

# verify the mount is read-only
docker exec myapp touch /etc/myapp/test  # should fail

開発ワークフロー

ソースコードをマウントすれば、ホストの編集がコンテナに即座に反映されます。「node_modules への匿名ボリューム」のトリックは、ホストの空の node_modules がイメージ内のインストール済み依存を覆い隠すのを防ぎます。Windows/Mac ではファイル監視の信頼性のためポーリングが必要なことがあります。

docker
# live-reload: mount source, run dev server
docker run -d -p 3000:3000 -v $(pwd)/src:/app/src node:20 \
  sh -c "cd /app && npm run dev"

# mount node_modules separately (avoid host override)
docker run -d -v $(pwd):/app -v /app/node_modules node:20 npm start

# compose dev workflow
# services:
#   web:
#     volumes:
#       - ./src:/app/src
#       - /app/node_modules  # anonymous, isolates deps

# hot reload with file watching (polling for Windows/Mac)
docker run -e CHOKIDAR_USEPOLLING=true -v $(pwd):/app node:20 npm start

SELinux と AppArmor ラベル

SELinux 有効なホスト(RHEL/CentOS/Fedora)では、bind マウントに :z か :Z 接尾辞を付け、ホストパスのラベルを付け直してコンテナからアクセス可能にする必要があります。:z はパスをコンテナ間で共有し、:Z はプライベートにします。接尾辞の付け忘れは「permission denied」エラーの原因です。

docker
# SELinux: :z (shared) or :Z (private) suffix
docker run -v /host/path:/container/path:z myapp
docker run -v /host/path:/container/path:Z myapp

# :z labels the host path as shared among containers
# :Z labels it private to this container

# disable SELinux isolation (NOT recommended)
docker run --security-opt label=disable myapp

# AppArmor profile
docker run --security-opt apparmor=docker-default myapp

# custom AppArmor profile
docker run --security-opt apparmor=myprofile myapp

Mount と Volume と tmpfs の違い

ボリューム:Docker 管理で移植性があり、永続データに最適。bind マウント:ホストパスで、開発と設定の注入に最適。tmpfs:メモリ内で、シークレットと一時キャッシュに最適。--mount 構文は -v より明示的で自己文書化されます。

docker
# named volume (Docker-managed, portable)
docker run -v mydata:/data nginx

# bind mount (host path, host-dependent)
docker run -v /home/me/data:/data nginx

# --mount explicit syntax (recommended)
docker run --mount type=volume,source=mydata,target=/data nginx
docker run --mount type=bind,source=/home/me/data,target=/data nginx
docker run --mount type=tmpfs,target=/cache nginx

# tmpfs (in-memory, ephemeral, fast)
docker run --tmpfs /cache nginx

# tmpfs with size limit
docker run --mount type=tmpfs,target=/cache,tmpfs-size=64m nginx

Compose での Bind マウント

Compose では、相対パス(./html)が bind マウントになり、volumes: セクションを参照する名前(logs)が名前付きボリュームになり、素のパス(/cache)が匿名ボリュームになります。長形式の構文なら read_only のようなオプションが明示的になります。

docker
# docker-compose.yml
services:
  web:
    image: nginx
    volumes:
      # relative host path = bind mount
      - ./html:/usr/share/nginx/html:ro
      # named volume
      - logs:/var/log/nginx
      # anonymous volume
      - /cache
volumes:
  logs:   # declare named volumes here

# use ~ (tilde) — Compose expands it
volumes:
  - ~/config:/etc/app:ro

# long-form syntax with options
volumes:
  - type: bind
    source: ./html
    target: /usr/share/nginx/html
    read_only: true
09

ネットワーキング

Bridge ネットワーク(デフォルト)

デフォルトの bridge ネットワークには自動 DNS がなく、コンテナは IP を使う必要があります。カスタムの bridge ネットワークは DNS ベースのサービス発見を提供します:コンテナが名前で互いを解決します。これが Compose が各プロジェクトにカスタムネットワークを自動作成する理由です。

docker
# the default bridge network (named 'bridge')
docker run -d --name web nginx

# create a custom bridge network (recommended)
docker network create mynet

# attach a container to a custom network
docker run -d --name web --network mynet nginx
docker run -d --name db --network mynet postgres

# containers on the same custom network can resolve by name
docker exec web ping db   # DNS resolves 'db'

# the default bridge does NOT support DNS names
# always use a custom bridge for multi-container apps

Host ネットワーク

Host ネットワーキングはネットワーク名前空間を取り除きます — コンテナがホストのインターフェースとポートを共有します。最高のパフォーマンスですが、分離とポートマッピングを犠牲にします。Linux でのみ利用可能です。Mac/Windows ではホストではなく VM のネットワークにマッピングされます。

docker
# use the host's network stack directly (no isolation)
docker run --network host nginx

# host network disables port mapping
# -p is ignored when --network host is used

# useful for performance-sensitive apps
docker run --network host -d myapp

# only works on Linux (not Docker Desktop on Mac/Windows)
# inspect host network
docker network inspect host

# bound to host interfaces — be careful with privileged ports
docker run --network host --cap-add NET_ADMIN myapp

Overlay ネットワーク(Swarm)

Overlay ネットワークは複数の Swarm ノードにまたがり、組み込み DNS による安全なホスト間通信を可能にします。--attachable でスタンドアロンのコンテナが overlay に参加できます(デバッグに有用)。暗号化がノード間のトラフィックを保護します。機密性の高いワークロードには有効化しましょう。

docker
# create an overlay network (requires Swarm mode)
docker network create -d overlay myoverlay

# overlay with encryption
docker network create -d overlay -o encrypted myoverlay

# deploy a service on the overlay
docker service create --network myoverlay --name web nginx

# multi-host communication for Swarm services
# containers on different nodes resolve by service name

# node-local network bridged to overlay
docker network create -d overlay --attachable myoverlay
docker run -d --network myoverlay alpine   # standalone container

カスタムネットワーク

カスタムネットワークでサブネット、ゲートウェイ、分離を制御できます。--internal で外向きのインターネットアクセスを防ぎます。macvlan はコンテナに物理 LAN での実在性を与えます(それぞれが独自の MAC を持つ)— レガシーアプリに有用ですが、デフォルトではホストとコンテナの通信が壊れます。

docker
# create a bridge network with a subnet
docker network create --subnet 172.20.0.0/16 mynet

# assign a static IP
docker run -d --network mynet --ip 172.20.0.10 nginx

# set a custom gateway
docker network create --subnet 172.20.0.0/16 \
  --gateway 172.20.0.1 mynet

# restrict to internal only (no external access)
docker network create --internal mynet

# specify a driver and options
docker network create -d bridge \
  -o com.docker.network.bridge.name=br0 mynet

# macvlan (container gets a MAC on the physical network)
docker network create -d macvlan \
  --subnet 192.168.1.0/24 -o parent=eth0 mymacvlan

コンテナ DNS

Docker の組み込み DNS(127.0.0.11)はユーザー定義ネットワーク上でコンテナ名を解決します。デフォルトの bridge には DNS がありません。--dns で外部リゾルバを追加し、--add-host で静的エントリを注入します。コンテナ間通信には IP ではなくサービス名を使いましょう — 再デプロイしても DNS が壊れません。

docker
# containers on custom networks resolve by name
docker network create mynet
docker run -d --name db --network mynet postgres
docker run -it --network mynet alpine nslookup db

# the embedded DNS server is at 127.0.0.11
docker exec web cat /etc/resolv.conf

# add custom DNS servers
docker run --dns 8.8.8.8 alpine nslookup example.com

# add DNS search domains
docker run --dns-search example.com alpine nslookup myhost

# add a host entry (like /etc/hosts)
docker run --add-host myservice:10.0.0.5 alpine ping myservice

# extra hosts in compose
# extra_hosts:
#   - "myservice:10.0.0.5"

ネットワークの検査と管理

network connect/disconnect は、再起動せずに稼働中のコンテナを追加のネットワークへ参加させます — サイドカーに有用です。inspect で接続中のコンテナ、サブネット、ドライバが分かります。prune はどのコンテナからも使われていないネットワークを削除します。

docker
# list all networks
docker network ls

# inspect a network (containers, IPAM, driver)
docker network inspect mynet

# see which containers are on a network
docker network inspect --format '{{range .Containers}}{{.Name}} {{end}}' mynet

# connect a running container to another network
docker network connect mynet2 web

# disconnect a container from a network
docker network disconnect mynet web

# remove an unused network
docker network rm mynet
docker network prune
10

ポートマッピング

基本のポートマッピング

-p host:container がホストポートをコンテナポートへマッピングします。ホストポートを省略すると、Docker が選びます(docker port で探せます)。1 つのホストポートは 1 つのコンテナにしかマッピングできません — 複数インスタンスにはリバースプロキシか別のホストポートを使いましょう。

docker
# map host:container
docker run -d -p 8080:80 nginx

# map to a random host port
docker run -d -p 80 nginx
docker port $(docker ps -lq) 80   # find the assigned port

# map multiple ports
docker run -d -p 8080:80 -p 8443:443 nginx

# map the same port on host and container
docker run -d -p 80:80 nginx

# explicit protocol (default tcp)
docker run -d -p 53:53/udp dns

# long form
docker run -d --publish 8080:80 nginx

特定の IP への束縛

IP を接頭辞にすると、ポートがどのインターフェースに束縛されるかを制御できます。127.0.0.1 はサービスをローカル限定にします — 曝したくないデータベースには不可欠です。0.0.0.0(デフォルト)はすべてのインターフェースに束縛します。本番ではデータベースを常に localhost に束縛しましょう。

docker
# bind to a specific host IP
docker run -d -p 127.0.0.1:8080:80 nginx

# bind to localhost only (not exposed externally)
docker run -d -p 127.0.0.1:5432:5432 postgres

# bind to all interfaces (default)
docker run -d -p 0.0.0.0:8080:80 nginx

# bind to an IPv6 address
docker run -d -p [::1]:8080:80 nginx

# multiple bindings
docker run -d -p 127.0.0.1:8080:80 -p 0.0.0.0:8443:443 nginx

# compose: specify IP
# ports:
#   - "127.0.0.1:5432:5432"

UDP と SCTP のポート

/udp や /sctp 接尾辞がプロトコルを選択します(デフォルトは TCP)。DNS のように両方必要なサービスでは、両方のマッピングを宣言しましょう。ポート範囲はホストとコンテナ間で 1:1 にマッピングされます — WebRTC、RTP、パッシブ FTP に有用です。ファイアウォールのルールをプロトコルに合わせましょう。

docker
# UDP port (DNS, syslog, statsd)
docker run -d -p 53:53/udp coredns

# both TCP and UDP
docker run -d -p 53:53/tcp -p 53:53/udp coredns

# SCTP (e.g. telecom signaling)
docker run -d -p 3868:3868/sctp myapp

# range of ports (host range maps to container range)
docker run -d -p 8000-8100:8000-8100 myapp

# UDP range
docker run -d -p 50000-50010:50000-50010/udp myapp

# compose with protocol
# ports:
#   - "53:53/udp"

ポートの範囲

ポート範囲は 1:1 でマッピングされます(ホスト 8000-8005 をコンテナ 8000-8005 へ)。-P(大文字)は EXPOSE されたすべてのポートをランダムな高番号のホストポートへ自動公開します — 手軽なテストに便利です。ポートがランダムなときは docker ps で実際のマッピングを確認しましょう。

docker
# map a range of host ports to container ports
docker run -d -p 8000-8005:8000-8005 myapp

# map host range to a single container port (NOT supported)
# this maps range-to-range only

# random port for each (useful for testing)
docker run -d -p 80 -p 443 nginx
docker port $(docker ps -lq)

# expose a range with EXPOSE (documentation only)
# EXPOSE 8000-8005

# publish all exposed ports at once
docker run -d -P nginx   # capital P publishes all EXPOSE ports

# view the random mappings
docker ps --format '{{.Names}} {{.Ports}}'

Exposing と Publishing の違い

EXPOSE は意図を文書化し、-p が実際に公開します。Compose では、expose は同じネットワーク上の他のサービスとだけポートを共有し、ports はホストへ公開します。この区別はデータベースで重要です:内部では expose し、本番ではホストへ決して publish しないこと。

docker
# Dockerfile: EXPOSE is documentation, NOT a publish
EXPOSE 80 443

# runtime: -p PUBLISHES the port to the host
docker run -d -p 8080:80 nginx

# -P publishes all EXPOSE ports to random host ports
docker run -d -P nginx

# compose: expose vs ports
services:
  web:
    image: nginx
    expose:
      - "80"      # only to linked services, NOT to host
    ports:
      - "8080:80" # published to the host

# view exposed (not published) ports
docker inspect --format '{{json .Config.ExposedPorts}}' nginx

ランダムポートマッピング

ホストポートを省略すると、Docker がランダムなエフェメラルポートを選びます(デフォルト 32768〜60999)。見つけるには docker port か docker ps を使いましょう。1 台のホスト上で同一サービスをスケールするときに有用です。Linux では /proc/sys/net/ipv4/ip_local_port_range でエフェメラル範囲を調整できます。

docker
# publish to a random high host port
docker run -d -p 80 nginx

# publish all EXPOSE ports randomly
docker run -d -P nginx

# find the assigned port
docker port <container> 80
docker port <container>

# see mappings in ps output
docker ps --format 'table {{.Names}}	{{.Ports}}'

# prefer a range for random allocation
docker run -d -p 30000-40000:80 nginx

# compose: random host port
# ports:
#   - "80"   # random host port, container port 80
11

環境変数

環境変数の設定

-e(または --env)がコンテナの環境変数を設定します。-e VAR(値なし)はホストシェルから変数を継承します。機密性の高い値には、docker inspect やプロセス一覧で見える素の -e より、--env-file や Docker secrets を推奨します。

docker
# single variable
docker run -d -e MYSQL_ROOT_PASSWORD=secret mysql

# multiple variables
docker run -d \
  -e MYSQL_ROOT_PASSWORD=secret \
  -e MYSQL_DATABASE=mydb \
  -e MYSQL_USER=app \
  mysql

# pass from the host environment
docker run -d -e HOST_PWD mysql
# HOST_PWD in the container = $HOST_PWD on host

# set a variable without a value (passes host value or empty)
docker run -e DEBUG alpine env

# long form
docker run --env MYSQL_ROOT_PASSWORD=secret mysql

Env ファイル

--env-file はファイルから変数を読み込み、run コマンドがきれいに保たれ、シークレットがシェルの履歴から離れます。Compose は compose ファイル自体での変数置換のために、トップレベルの .env を自動読み込みします。コメント(#)と空行は無視され、引用符はリテラルとして保持されます。

docker
# .env file
# DB_HOST=db
# DB_USER=app
# DB_PASSWORD=secret

# load variables from a file
docker run --env-file .env myapp

# load multiple env files
docker run --env-file .env --env-file .env.local myapp

# Compose reads .env automatically for variable substitution
# and supports env_file per service:
# services:
#   web:
#     env_file:
#       - .env
#       - .env.local

# env file with comments and blank lines
docker run --env-file config.env myapp

Dockerfile の環境変数

ENV は変数をイメージに焼き込み、ビルド時と実行時に見えます。ARG はビルド時専用です — 実行時が必要なら ENV へ変換しましょう。焼き込まれた値は実行時に -e で上書きできます。注意:環境変数は docker inspect で見えるため、シークレットを置かないでください。

docker
# ENV sets a persistent variable
ENV NODE_ENV=production
ENV PATH=/app/bin:$PATH

# use ARG for build-time only, ENV for runtime
ARG BUILD_VERSION=1.0
ENV APP_VERSION=${BUILD_VERSION}

# view all env vars
docker exec web env

# inspect a specific variable
docker exec web printenv NODE_ENV

# override at runtime
docker run -e NODE_ENV=development myapp

# set via Compose
# environment:
#   - NODE_ENV=development
#   - DEBUG=true

動的な環境変数と置換

シェル展開($(...) や ${VAR})は、Docker が値を見る前にホスト上で起きます。Compose では ${VAR} が .env ファイルから置換されます。exec 形式の CMD では ${VAR} は展開されません — sh -c で包みましょう。bind マウントでの正しいファイル所有権のため、ホストの UID を渡しましょう。

docker
# pass a computed value at runtime
docker run -e STARTUP_TIME=$(date +%s) myapp

# use host shell expansion
docker run -e USER_ID=$(id -u) myapp

# Compose variable substitution from .env
# services:
#   web:
#     environment:
#       DB_HOST: ${DB_HOST}
# .env file:
#   DB_HOST=db

# Compose with default values
#   DB_HOST: ${DB_HOST:-localhost}

# pass the current user for permission matching
docker run -u $(id -u):$(id -g) -e HOME=/tmp myapp

# resolve env at runtime with sh -c (not in exec form)
ENV PORT=3000
CMD ["sh", "-c", "node server.js --port ${PORT}"]

Compose の環境

Compose の environment はリストかマップの構文を受け付けます。env_file が値をコンテナへ読み込み、.env(トップレベル)が compose ファイル自体の ${} 置換用の変数を提供します。変数が多いときは読みやすさのためマップ形式を使いましょう。

docker
# docker-compose.yml
services:
  web:
    image: myapp
    environment:
      - NODE_ENV=production
      - DEBUG=false
      - DB_HOST=db
    # map form (cleaner for many vars)
    environment:
      NODE_ENV: production
      DB_HOST: db

  db:
    image: postgres
    env_file:
      - .env.db
    environment:
      POSTGRES_DB: ${DB_NAME}   # from .env

# top-level .env for substitution
# DB_NAME=mydb

シークレットの管理

シークレットは /run/secrets の下のファイルとしてマウントされ、環境変数としては決して渡されず、Swarm では転送中も保存時も暗号化されます。シークレットをイメージ(ENV)へ焼き込んだり -e で渡したりするのは避けましょう — どちらも docker inspect とイメージレイヤー経由で漏れます。BuildKit のシークレットマウントならビルド時の認証情報がレイヤーに入りません。

docker
# Docker Swarm secrets (encrypted, mounted as files)
echo "supersecret" | docker secret create db_password -
docker service create --secret db_password myapp

# read in the app
# cat /run/secrets/db_password

# Compose secrets (v3.1+)
# services:
#   web:
#     secrets:
#       - db_password
# secrets:
#   db_password:
#     file: ./secrets/db_password.txt

# BuildKit secret mount (build-time, not in layers)
# RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci

# avoid: baking secrets in ENV or -e (visible in inspect)
docker run -e API_KEY=xxx myapp  # NOT recommended
12

Docker Compose の基本

基本の docker-compose.yml

Compose は 1 つの YAML ファイルでマルチコンテナのアプリを定義します。services が各コンテナを記述し、volumes と networks はトップレベルで宣言します。depends_on が起動順序を制御します。docker compose up -d ですべてがバックグラウンドで起動します。

docker
# docker-compose.yml (Compose spec v2)
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - dbdata:/var/lib/postgresql/data

volumes:
  dbdata:

# run: docker compose up -d

Compose コマンド

up が作成して起動し、down が停止して削除します。down に -v を加えるとボリュームが削除されます(データ喪失)。exec は稼働中のサービスでコマンドを実行し、run は 1 回限りのタスクのために新しいコンテナを起動します。--scale は同じホスト上でサービスのレプリカを複数起動します。

docker
# start all services (foreground)
docker compose up

# start in background (detached)
docker compose up -d

# rebuild images before starting
docker compose up -d --build

# stop and remove containers (keeps volumes)
docker compose down

# also remove volumes (data loss)
docker compose down -v

# view logs (all services)
docker compose logs -f

# scale a service
docker compose up -d --scale worker=3

# run a one-off command in a service
docker compose exec web sh
docker compose run --rm web python manage.py migrate

サービスの依存関係

depends_on が起動順序を制御しますが、依存先が「準備完了」とは限りません — healthcheck 付きの condition: service_healthy で、データベースが接続を受け付けるまで待ちましょう。service_completed_successfully は init コンテナを待ちます。アプリ側も接続の再試行はすべきです。

docker
services:
  web:
    image: myapp
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    restart: on-failure

  db:
    image: postgres
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 5s
      retries: 5

  redis:
    image: redis

# conditions: service_started | service_healthy | service_completed_successfully

Compose でのビルド

build がソースからイメージをビルドする方法を定義し、image が結果にタグを付けます。context はビルダーへ送られます(小さく保ちましょう)。target がマルチステージのステージを選び、--build で up 時の再ビルドを強制します。ビルド引数がビルド時に値を渡します。

docker
services:
  web:
    build:
      context: ./app
      dockerfile: Dockerfile.prod
      args:
        VERSION: 1.0
      target: final
    image: myapp:1.0
    ports:
      - "8080:80"

  worker:
    build: ./worker   # shorthand: context only
    image: myworker:1.0

# build and tag
docker compose build
docker compose build --no-cache web
docker compose up -d --build

Compose のボリューム

相対パス(./html)は bind マウントで、トップレベルの volumes: で宣言された名前(logs)は名前付きボリューム、素のパス(/cache)は匿名です。名前付きボリュームはドライバとオプション(NFS など)を指定できます。Compose はボリューム名にプロジェクト名の接頭辞を付けます。

docker
services:
  web:
    image: nginx
    volumes:
      # named volume
      - logs:/var/log/nginx
      # bind mount (relative path)
      - ./html:/usr/share/nginx/html:ro
      # anonymous volume
      - /cache

  db:
    image: postgres
    volumes:
      - dbdata:/var/lib/lib/postgresql/data

volumes:
  logs:
  dbdata:
    driver: local
    driver_opts:
      type: nfs
      device: ":/export/data"
      o: addr=10.0.0.5,rw

Compose のネットワーク

Compose は全サービスのためにデフォルトネットワークを作りますが、カスタムネットワークを定義すれば階層を分離できます。web がフロントエンドとバックエンドを橋渡しし、internal: true がバックエンドのインターネットアクセスをブロックします。同じネットワーク上のサービスは DNS 経由でサービス名により互いを解決します。

docker
services:
  web:
    image: nginx
    networks:
      - frontend
      - backend

  db:
    image: postgres
    networks:
      - backend

  proxy:
    image: traefik
    networks:
      - frontend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true   # no external access

# custom subnet
networks:
  backend:
    ipam:
      config:
        - subnet: 172.28.0.0/16
13

Docker Compose 応用

Compose プロファイル

プロファイルがオプションのサービスをグループ化します。プロファイルのないサービスは常に起動し、プロファイル付きのサービスは --profile でそのプロファイルが有効化されたときだけ起動します。1 つの compose ファイルが dev、test、本番を兼ねられます:環境ごとにプロファイルを選択的に有効化しましょう。

docker
services:
  web:
    image: nginx
    profiles: ["default", "prod"]

  debug:
    image: nginx
    profiles: ["debug"]
    ports:
      - "8080:80"

  test:
    image: myapp-test
    profiles: ["test"]

# start only default services
docker compose up -d

# start with the debug profile
docker compose --profile debug up -d

# run tests
docker compose --profile test run test

# start multiple profiles
docker compose --profile prod --profile debug up -d

Compose のオーバーライド

Compose はローカル開発のカスタマイズのため、docker-compose.yml の上に docker-compose.override.yml を自動読み込みします。他の環境には、-f を複数順に渡しましょう — 後のファイルが前のファイルを上書きします。これでベース設定と環境固有の調整がきれいに分離されます。

docker
# docker-compose.yml (base)
services:
  web:
    image: myapp:latest
    environment:
      NODE_ENV: production

# docker-compose.override.yml (auto-loaded for dev)
services:
  web:
    build: ./app
    environment:
      NODE_ENV: development
      DEBUG: "true"
    volumes:
      - ./src:/app/src
    command: npm run dev

# explicit override file
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# merge order: later files override earlier ones
# docker compose -f base.yml -f dev.yml -f local.yml up

Compose のヘルスチェック

Compose のヘルスチェックは Dockerfile の HEALTHCHECK を反映します。start_period が起動中の猶予時間を与えます。healthcheck を depends_on: condition: service_healthy と組み合わせれば、サービスは依存先が単に起動しただけでなく実際に準備完了するまで待ちます。

docker
services:
  web:
    image: nginx
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  db:
    image: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  app:
    image: myapp
    depends_on:
      db:
        condition: service_healthy

スケールとレプリカ

--scale は 1 台のホスト上で N 個の同一コンテナを起動します — サービスは固定のホストポートを束縛してはいけません(ランダムポートかホストマッピングなしに)。deploy.replicas キーは Swarm が尊重します。素の Compose では --scale を使いましょう。スケールしたサービスの前面にはロードバランサーを置きます。

docker
# scale at startup (single host)
docker compose up -d --scale worker=4

# docker-compose.yml with replicas (Compose spec)
services:
  worker:
    image: myworker
    deploy:
      replicas: 4
      resources:
        limits:
          cpus: "0.5"
          memory: 512M

  web:
    image: nginx
    deploy:
      replicas: 2
      update_config:
        parallelism: 1
        delay: 10s

# note: replicas deploy key is for Swarm;
# plain Compose uses --scale

# prevent port conflicts when scaling
docker compose up -d --scale web=3   # web must use random ports

Compose の config と検証

config はマージされた compose ファイル(オーバーライドと .env の置換を含む)を検証して描画します — デバッグに非常に有用です。--services、--images、--volumes がリソースを一覧します。CI では -q を使い、不正な compose ファイルで早く失敗させましょう。

docker
# validate and print the merged compose file
docker compose config

# check for errors only
docker compose config -q

# list all services
docker compose config --services

# list all images used
docker compose config --images

# list all volumes
docker compose config --volumes

# render with variable substitution (resolve .env)
docker compose config > rendered.yml

# validate before deploying
docker compose config -q && docker compose up -d

複数の Compose ファイル

compose ファイルを積み重ねると関心が分離されます:ベース設定、環境の上書き、ローカルの調整。COMPOSE_FILE(Linux/Mac ではコロン区切り、Windows ではセミコロン)が -f の繰り返しを避けます。ports のようなリストは追加され、environment のようなマップはキーでマージされます。

docker
# base, dev, and prod files
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# COMPOSE_FILE env var (avoids -f repetition)
export COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml
docker compose up -d

# docker-compose.prod.yml
services:
  web:
    image: registry.com/myapp:${TAG}
    environment:
      NODE_ENV: production
    deploy:
      replicas: 3

# difference files: add/override specific keys
# lists (ports, volumes) are merged; maps (environment) are merged
14

Docker レジストリ

ローカルレジストリの実行

registry:2 イメージはポート 5000 でプライベートレジストリを実行します。イメージを永続化するにはボリュームをマウントしましょう。リモートホストや HTTPS のためには、TLS 証明書を設定するか、/etc/docker/daemon.json の insecure-registries にレジストリを加えます。v2 API で curl 経由でリポジトリのカタログが取得できます。

docker
# run the official registry image
docker run -d -p 5000:5000 --name registry \
  -v registrydata:/var/lib/registry \
  --restart always \
  registry:2

# tag and push to it
docker tag myapp:1.0 localhost:5000/myapp:1.0
docker push localhost:5000/myapp:1.0

# pull from it
docker pull localhost:5000/myapp:1.0

# list repositories in the registry
curl http://localhost:5000/v2/_catalog

# list tags for a repository
curl http://localhost:5000/v2/myapp/tags/list

プライベートレジストリへの push

push の前に、イメージにレジストリホストのタグが必要です。自己署名証明書のレジストリでは、ホストを insecure-registries に加えてデーモンを再起動します(本番には非推奨 — 正式な CA か内部 CA を使いましょう)。push -a がリポジトリ内のすべてのタグをアップロードします。

docker
# tag with the registry URL
docker tag myapp:1.0 registry.local:5000/myapp:1.0

# login
docker login registry.local:5000

# push
docker push registry.local:5000/myapp:1.0

# push all tags
docker push -a registry.local:5000/myapp

# verify it landed
curl http://registry.local:5000/v2/myapp/tags/list

# self-signed cert: configure the daemon
# /etc/docker/daemon.json:
# { "insecure-registries": ["registry.local:5000"] }
# then: systemctl restart docker

プライベートレジストリからの pull

プライベートレジストリからは完全なイメージ名を指定して pull します。ログイン資格情報は ~/.docker/config.json に保存されます(セキュリティのため credential helper を使いましょう)。CI/CD では、資格情報をシークレットとして保存し、pull の前にログインしましょう。再現可能なデプロイのためダイジェストで固定します。

docker
# login first (credentials cached in ~/.docker/config.json)
docker login registry.local:5000

# pull by full name
docker pull registry.local:5000/myapp:1.0

# pull by digest (immutable)
docker pull registry.local:5000/myapp@sha256:abc123...

# use in Compose
# services:
#   web:
#     image: registry.local:5000/myapp:1.0

# logout
docker logout registry.local:5000

# check stored credentials
cat ~/.docker/config.json

レジストリの認証

レジストリは htpasswd の basic 認証かトークン(OAuth)サーバーで保護します。TLS のためには証明書をマウントし 443 で listen しましょう。credential helper(credsStore)はパスワードを平文の config.json ではなく OS のキーチェーンに保存します — 共有マシンや CI マシンでは不可欠です。

docker
# htpasswd-based auth
mkdir -p auth
docker run --entrypoint htpasswd httpd:2 -Bbn user password > auth/htpasswd

# run registry with auth
docker run -d -p 5000:5000 --name registry \
  -v $(pwd)/auth:/auth \
  -e REGISTRY_AUTH=htpasswd \
  -e REGISTRY_AUTH_HTPASSWD_REALM=Registry \
  -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
  registry:2

# login now required
docker login localhost:5000

# token-based auth (OAuth, JWT) for enterprise
# configure REGISTRY_AUTH=token with an auth server

# credential helpers (avoid storing in config.json)
# "credsStore": "secretservice" (Linux)
# "credsStore": "osxkeychain" (Mac)
# "credsStore": "wincred" (Windows)

レジストリ API

Registry HTTP API v2 でレジストリ管理をスクリプト化できます。_catalog がリポジトリを一覧し、manifests がイメージレイヤーを記述します。削除には REGISTRY_STORAGE_DELETE_ENABLED=true が必要で、manifests を削除します — blob はガベージコレクション(registry garbage-collect)で片付けられます。

docker
# list all repositories
curl http://localhost:5000/v2/_catalog

# list tags for a repo
curl http://localhost:5000/v2/myapp/tags/list

# get a manifest
curl -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
  http://localhost:5000/v2/myapp/manifests/1.0

# delete a manifest (by digest)
curl -X DELETE \
  http://localhost:5000/v2/myapp/manifests/sha256:abc123...

# enable delete API
# -e REGISTRY_STORAGE_DELETE_ENABLED=true

# check if a blob exists
curl -I http://localhost:5000/v2/myapp/blobs/sha256:abc...

ガベージコレクション

manifest を削除すると、ガベージコレクションが走るまで孤立した blob が残ります。使用中のレイヤーを回収しないよう、レジストリを停止するか(または --dry-run)使いましょう。本番では、削除・置き換えられたイメージからディスクを取り戻すため、GC を定期的にスケジュールしましょう。config.yml のパスがレジストリの設定ファイルです。

docker
# run garbage collection on a registry
docker exec -it registry \
  garbage-collect --dry-run /etc/docker/registry/config.yml

# actual collection (stop the registry first for consistency)
docker stop registry
docker run --rm -v registrydata:/var/lib/registry \
  -v /path/config.yml:/etc/docker/registry/config.yml \
  registry:2 garbage-collect /etc/docker/registry/config.yml
docker start registry

# delete unreferenced blobs after manifest deletion
# schedule GC as a cron job for production registries

# view disk usage
docker exec registry du -sh /var/lib/registry
15

Docker Hub

ログインとログアウト

パスワードよりアクセストークンを推奨します — 取り消し可能でスコープ付きです。--password-stdin は stdin から読み込み、シェルの履歴やプロセス一覧にパスワードが現れません。credential helper を設定し、平文の config.json ではなく OS のキーチェーンに資格情報を保存しましょう。

docker
# interactive login (prompts for username/password)
docker login

# login with a token (recommended over password)
docker login -u username -p dckr_pat_xxxxx

# login via stdin (avoids shell history)
echo "dckr_pat_xxxxx" | docker login -u username --password-stdin

# logout
docker logout

# credentials stored in ~/.docker/config.json
# or OS keychain via credential helper

# create an access token on Docker Hub
# Account Settings -> Security -> New Access Token

イメージの検索

docker search は CLI から Docker Hub をクエリし、スター、公式状態、自動ビルドのフィルタがあります。公式イメージ(library/nginx)は Docker が検証しています — ベースにはこれらを推奨します。Web UI では OS、アーキテクチャ、カテゴリによるより豊富なフィルタが使えます。

docker
# search Docker Hub from the CLI
docker search nginx

# filter by stars
docker search --filter stars=100 nginx

# only official images
docker search --filter is-official nginx

# only automated builds
docker search --filter is-automated nginx

# limit results
docker search --limit 5 nginx

# show full description (no truncation)
docker search --no-trunc nginx

# search on the web for richer filtering
# https://hub.docker.com/search?q=nginx

Docker Hub への push

username/repo:tag としてイメージにタグを付け、push で Docker Hub へ公開します。リポジトリは初回 push で自動作成されます(デフォルトは公開)。push -a がすべてのタグをアップロードします。無料アカウントは 1 つのプライベートリポジトリ、有料プランはそれ以上です。リポジトリの可視性は Hub の Web UI で設定します。

docker
# tag with your username
docker tag myapp:1.0 username/myapp:1.0

# also tag as latest
docker tag username/myapp:1.0 username/myapp:latest

# login
docker login

# push (creates the repo if it doesn't exist)
docker push username/myapp:1.0
docker push username/myapp:latest

# push all tags
docker push -a username/myapp

# make the repo private on Docker Hub
# (Hub web UI -> Repository -> Settings -> Make Private)

自動ビルド

Docker Hub の autobuild は git リポジトリをリンクし、push のたびにビルドします。モダンなワークフローでは、より多くの制御、キャッシュ、マルチアーキテクチャビルドを提供する buildx と push を使った GitHub Actions が推奨です。Hub の autobuild はシンプルなプロジェクトには手軽な選択肢として残ります。

docker
# connect a GitHub/Bitbucket repo to Docker Hub
# Hub web UI -> Create -> Build Rule

# build rule examples:
# Source: github.com/me/myapp  Branch: main
# Dockerfile location: /Dockerfile
# Image tag: latest

# trigger a build via webhook
curl -H "Content-Type: application/json" \
  --data '{"build": true}' \
  https://hub.docker.com/api/build/v1/source/.../trigger/.../call/

# build context with multiple tags and stages
# Source: Branch main  -> Tag: branch-main
# Source: Tag v1.0     -> Tag: 1.0, latest

# Autobuild triggers on git push
# (deprecated in favor of GitHub Actions)

Organization と Team

Organizations はロールベースのアクセスでリポジトリをチームで共有します。Teams はリポジトリごとの権限(read、write、admin)を持ちます。サービスアカウントは CI/CD 用の非個人のトークンを提供し、個人に影響なく取り消しとローテーションができます。orgname/repo の名前空間を使いましょう。

docker
# create an organization on Docker Hub
# (web UI: Create Organization)

# create a team and add members
# Org -> Teams -> Create Team -> Add Members

# assign repository permissions per team
# Repository -> Permissions -> Add Team
#   Read-only, Read-write, Admin

# create a service account token for CI
# Org -> Service Accounts -> New Service Account
# use the token in CI: docker login -u tokenname -p token

# team namespaces: orgname/repo
docker tag myapp orgname/myapp:1.0
docker push orgname/myapp:1.0

イメージの信頼(DCT)

Docker Content Trust(DCT)は Notary でイメージタグに署名し、pull したイメージが公開者が push したものだと保証します。DOCKER_CONTENT_TRUST=1 で有効化します。DCT 有効時は、署名されたイメージしか pull/push できません。署名鍵は慎重に管理しましょう — 失うとイメージから締め出されることがあります。

docker
# enable Docker Content Trust (signing)
export DOCKER_CONTENT_TRUST=1

# push signs the image automatically
docker push username/myapp:1.0

# pull refuses unsigned images when DCT is on
docker pull username/myapp:1.0

# disable for a single command
DOCKER_CONTENT_TRUST=0 docker pull unsigned/myapp:1.0

# generate delegation keys
docker trust key generate alice

# add a signer to a repository
docker trust signer add --key alice.pub alice username/myapp

# view signatures
docker trust inspect username/myapp:1.0

# revoke and rotate keys via the notary CLI
16

ヘルスチェック

基本のヘルスチェック

ヘルスチェックは定期的にコマンドを実行し、終了コード 0 が健全、非ゼロが不健全です。コンテナは 'starting' で始まり、リトライが成功すると 'healthy' に、失敗し続けると 'unhealthy' になります。start_period が起動中の猶予時間を与えます。ヘルスは Swarm の再起動判断を駆動します。

docker
# add a healthcheck at runtime
docker run -d --name web \
  --health-cmd="curl -f http://localhost/ || exit 1" \
  --health-interval=30s \
  --health-timeout=5s \
  --health-retries=3 \
  --health-start-period=10s \
  nginx

# check health status
docker inspect --format '{{.State.Health.Status}}' web

# view health check log (last 5 results)
docker inspect --format '{{json .State.Health.Log}}' web | jq

# states: starting | healthy | unhealthy | none

Dockerfile のヘルスチェック

Dockerfile の HEALTHCHECK はチェックをイメージに焼き込みます。アプリが実際に提供していることを確認する最も軽いチェックを使いましょう — HTTP には curl -f か wget --spider、Postgres には pg_isready。HEALTHCHECK NONE が継承したチェックを無効化します。広すぎるチェックは誤った 'unhealthy' のフラップを招きます。

docker
FROM nginx:alpine

# basic healthcheck (exec form)
HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=10s \
  CMD curl -f http://localhost/ || exit 1

# using wget (alpine)
HEALTHCHECK CMD wget --spider -q http://localhost/ || exit 1

# postgres ships a ready check
HEALTHCHECK CMD pg_isready -U postgres

# disable a healthcheck inherited from the base image
HEALTHCHECK NONE

# verify
docker inspect --format '{{.Config.Healthcheck}}' myapp

ヘルスチェックのオプション

interval がチェック頻度、timeout が各チェックの上限、retries が連続失敗のしきい値です。start_period は起動中の失敗を無視し、アプリが温まっている間の誤った 'unhealthy' を防ぎます。負荷下でフラップせずに実際の停止をすばやく捉えるよう調整しましょう。

docker
# full set of options
HEALTHCHECK \
  --interval=30s      \  # time between checks (default 30s)
  --timeout=5s        \  # max time per check (default 30s)
  --retries=3         \  # failures to mark unhealthy (default 3)
  --start-period=30s  \  # boot grace period (default 0s)
  CMD curl -f http://localhost/

# interval: how often to run
# timeout: if a check exceeds this, it's a failure
# retries: consecutive failures before unhealthy
# start-period: failures during this don't count

# compose form
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 30s

ヘルス状態の検査

ps はステータスの隣に (healthy)/(unhealthy) を表示します。Health.Log が直近 5 回のチェックの出力を記録します — チェックがなぜ失敗するかのデバッグに非常に有用です。exec でチェックコマンドを手動実行すれば実際のエラーが見えます。ps を health でフィルタすれば、不調なコンテナを素早く見つけられます。

docker
# current status
docker inspect --format '{{.State.Health.Status}}' web

# last 5 check results
docker inspect --format '{{range .State.Health.Log}}\
{{.ExitCode}} {{.Output}}{{end}}' web

# show in ps (status column shows (healthy)/(unhealthy))
docker ps

# filter containers by health
docker ps --filter "health=unhealthy"

# troubleshoot a failing check
docker inspect --format '{{json .State.Health.Log}}' web | jq

# run the check command manually
docker exec web curl -f http://localhost/

Compose のヘルスチェック

Compose のヘルスチェックは Dockerfile を反映します。test は配列(exec 形式)か CMD-SHELL 文字列を受け付けます。disable: true が継承したチェックを取り除きます。healthcheck を depends_on: condition: service_healthy とペアにすれば、サービスは依存先が単に起動しただけでなく実際に準備完了するのを待ちます。

docker
services:
  web:
    image: nginx
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  db:
    image: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      retries: 5

  app:
    image: myapp
    depends_on:
      db:
        condition: service_healthy
      web:
        condition: service_healthy

# disable a healthcheck
  debug:
    image: nginx
    healthcheck:
      disable: true

ヘルスチェックのベストプラクティス

重要な依存(DB、キャッシュ)を確認する本物の /healthz エンドポイントをチェックしましょう — 素の TCP チェックはアプリが壊れていても通ってしまいます。チェックは軽量で速く保ちましょう。interval ごとに動きます。ゆっくり起動するランタイム(JVM、Rails)には start_period を使えば、起動中に unhealthy とされません。

docker
# check the actual app endpoint, not just TCP
HEALTHCHECK CMD curl -f http://localhost/healthz || exit 1

# include a /healthz endpoint in your app
# that verifies DB and cache connectivity

# keep checks fast (under timeout)
HEALTHCHECK --timeout=3s CMD curl -f http://localhost/healthz

# avoid heavy checks — they run every interval
# don't run migrations or full DB queries

# use start-period for slow starters (Java, Rails)
HEALTHCHECK --start-period=60s CMD ...

# for Swarm, health enables auto-restart of unhealthy tasks
# combine with restart policies and update_config

# example app endpoint (Express)
# app.get('/healthz', (req, res) => res.send('ok'))
17

リソース制限

メモリの制限

--memory がハード上限を設定し、超えると OOM kill が起きます。--memory-swap はメモリ + スワップの合計を上限とし、memory と同じ値にするとスワップが無効になります。--memory-reservation はカーネルへのソフトなヒントです。レイテンシ重視のワークロードでは予測可能なパフォーマンスのためスワップを無効化しましょう。

docker
# limit to 512MB of memory
docker run -d --memory="512m" nginx

# memory + swap (swap = memory + swap allowance)
docker run -d --memory="512m" --memory-swap="1g" nginx

# soft limit (hint to the kernel, may be exceeded)
docker run -d --memory-reservation="256m" nginx

# disable swap (swap = memory, no extra)
docker run -d --memory="512m" --memory-swap="512m" nginx

# OOM behavior: kill the container (default)
docker run -d --memory="512m" --oom-kill-disable nginx

# verify limits
docker inspect --format '{{.HostConfig.Memory}}' <container>

CPU の制限

--cpus は CPU 制限をコアの割合で設定します(1.5 = 1.5 コア)。--cpu-shares は競合時に使われる相対的な重みで、ハードな上限ではありません。--cpuset-cpus はコンテナを特定のコアに固定し、パフォーマンスの分離に有用です。quota/period は低レベルの cgroup 形式です。

docker
# limit to 1 CPU (1.0 = one full core)
docker run -d --cpus="1.0" nginx

# limit to 1.5 CPUs
docker run -d --cpus="1.5" nginx

# CPU shares (relative weight, default 1024)
docker run -d --cpu-shares=512 nginx

# pin to specific CPU cores (0,1)
docker run -d --cpuset-cpus="0,1" nginx

# pin to cores 0-3
docker run -d --cpuset-cpus="0-3" nginx

# quota/period form (100000us per 100000us = 1 CPU)
docker run -d --cpu-quota=50000 --cpu-period=100000 nginx

メモリとスワップの挙動

memory-swap はメモリ + スワップの合計です。memory と同じ値にするとスワップが無効になり、-1 は無制限のスワップを許します。swappiness(0〜100)はカーネルがスワップする傾向を制御し、低い値は RAM にページを保持することを優先します。カーネルメモリの制限は高度で、必要になることはまれです。

docker
# memory limit, swap disabled
docker run -d -m 512m --memory-swap 512m nginx

# memory limit, 512m extra swap
docker run -d -m 512m --memory-swap 1g nginx

# unlimited swap (limited memory)
docker run -d -m 512m --memory-swap -1 nginx

# swappiness (0-100, lower = less swapping)
docker run -d -m 512m --memory-swappiness=10 nginx

# kernel memory limit (advanced, rarely needed)
docker run -d --kernel-memory="100m" nginx

# verify swap settings
docker inspect --format '{{.HostConfig.MemorySwap}}' <container>

Compose のリソース制限

deploy.resources.limits がハード上限、reservations がソフトな保証(スケジューリングに使われる)を設定します。Swarm はこれらをネイティブに尊重します。素の Compose(非 Swarm)では、v2 形式のトップレベルの mem_limit と cpus を使いましょう。reservations があれば、アイドルでもコンテナは最低限を確保できます。

docker
services:
  web:
    image: nginx
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 256M

  worker:
    image: myworker
    mem_swappiness: 10
    memswap_limit: 1g
    cpus: 2.0

# limits = hard caps; reservations = soft guarantees
# Swarm honors deploy.resources
# plain Compose: use top-level mem_limit, cpus (v2 compat)

OOM と再起動の挙動

メモリが尽きると、カーネルの OOM キラーが犠牲者を選びます。oom-kill-disable はコンテナを守りますがホストをクラッシュさせ得ます — ホストのメモリ制限と一緒にだけ使いましょう。oom-score-adj が選択を偏向させます:正 = 最初に殺される、負 = 保護される。再起動の診断には OOMKilled を確認しましょう。

docker
# default: OOM kills the container, restart policy restarts it
docker run -d --memory=512m --restart unless-stopped nginx

# disable OOM kill for this container (risky)
docker run -d --memory=512m --oom-kill-disable nginx

# set OOM score adjustment (higher = killed first)
docker run -d --oom-score-adj=500 nginx

# protect a critical container (killed last)
docker run -d --oom-score-adj=-500 nginx

# verify restart count
docker inspect --format '{{.RestartCount}}' <container>

# check if OOM-killed
docker inspect --format '{{.State.OOMKilled}}' <container>

リソース使用量の検査

docker stats はコンテナごとの CPU、メモリ、ネットワーク、ディスク IO をリアルタイムに流します — 手軽なトリアージの頼みの綱です。--no-stream でスクリプト用の 1 回のスナップショットになります。より深い分析には、/sys/fs/cgroup を収集するか、cAdvisor で Prometheus メトリクスを公開しましょう。制限と使用量を比較して適正サイズを見極めます。

docker
# live resource stats (CPU, memory, network, IO)
docker stats

# specific container
docker stats web

# one snapshot (no streaming)
docker stats --no-stream

# custom format
docker stats --format "table {{.Name}}	{{.CPUPerc}}	{{.MemUsage}}"

# container cgroup details
docker exec web cat /sys/fs/cgroup/memory/memory.usage_in_bytes
docker exec web cat /sys/fs/cgroup/cpu/cpu.stat

# inspect configured limits
docker inspect --format '{{.HostConfig.Memory}} {{.HostConfig.NanoCpus}}' web
18

セキュリティ

非 root ユーザー

非 root での実行は、アプリが侵害された場合の被害範囲を限定します。Dockerfile で専用ユーザーを作り、USER で切り替えましょう。特権ポートを束縛する必要があるなら、root で実行するのではなく、リバースプロキシ(nginx)を使うか NET_BIND_SERVICE ケイパビリティを付与しましょう。

docker
# Dockerfile: create and use a non-root user
FROM node:20-alpine
RUN addgroup -S app && adduser -S app -G app
USER app
WORKDIR /app
COPY --chown=app:app . .
CMD ["node", "server.js"]

# at runtime, override the user
docker run -u 1000:1000 myapp

# verify the current user
docker exec web id

# bind to privileged ports? Use capabilities or a reverse proxy
# non-root cannot bind to ports < 1024 without NET_BIND_SERVICE

# distroless images ship a non-root user by default
FROM gcr.io/distroless/nodejs20
USER nonroot

読み取り専用のルートファイルシステム

読み取り専用のルートファイルシステムは、侵害された場合に攻撃者がマルウェアを書き込んだり設定を改ざんするのを防ぎます。作業ディレクトリ(/tmp、/cache)には tmpfs を、永続データにはボリュームを組み合わせましょう。アプリはこれを前提に設計する必要があります — 予想外のパスに書き込むフレームワークには tmpfs マウントが必要です。

docker
# make the root filesystem read-only
docker run --read-only nginx

# allow writes only to specific dirs via tmpfs
docker run --read-only --tmpfs /tmp --tmpfs /var/cache nginx

# combine with a writable volume for persistent data
docker run --read-only -v appdata:/data --tmpfs /tmp myapp

# compose form
services:
  web:
    image: nginx
    read_only: true
    tmpfs:
      - /tmp
      - /var/cache/nginx

# apps must be designed to not write outside allowed paths

Linux ケイパビリティ

デフォルトで Docker は限られた Linux ケイパビリティのセットを付与します。ALL を取り落とし、アプリが必要とするものだけを戻しましょう — 最小特権の原則です。--privileged はすべてのケイパビリティとホストデバイスアクセスを与えます。信頼できるコンテナランタイム以外では完全に避けましょう。NET_RAW はデフォルトで落としましょう。

docker
# drop all capabilities, add only what's needed
docker run --cap-drop=ALL --cap-add=NET_BIND_SERVICE nginx

# add a specific capability
docker run --cap-add=SYS_PTRACE myapp

# common capabilities to drop (rarely needed by apps)
# CHOWN, DAC_OVERRIDE, FOWNER, KILL, NET_RAW, SETGID, SETUID

# NET_RAW is often safe to drop (prevents raw sockets/ping)
docker run --cap-drop=NET_RAW myapp

# privileged = all capabilities + host access (AVOID)
docker run --privileged myapp  # DANGEROUS

# inspect capabilities
docker inspect --format '{{json .HostConfig.CapAdd}}' <container>

Seccomp と AppArmor

Seccomp はコンテナが呼べるシステムコールをフィルタします — デフォルトプロファイルは約 44 の危険なシステムコールをブロックします。AppArmor はファイルとケイパビリティのアクセスを制限します。no-new-privileges は setuid バイナリが新しい特権を得るのを防ぎます — どんなコンテナにも安価で高価値な強化です。

docker
# default seccomp profile blocks dangerous syscalls
docker run --security-opt seccomp=default.json nginx

# custom seccomp profile
docker run --security-opt seccomp=/path/to/profile.json nginx

# disable seccomp (NOT recommended)
docker run --security-opt seccomp=unconfined nginx

# AppArmor profile
docker run --security-opt apparmor=docker-default nginx

# custom AppArmor profile
docker run --security-opt apparmor=myprofile nginx

# no-new-privileges (prevents setuid escalation)
docker run --security-opt no-new-privileges nginx

イメージのスキャン

push の前に既知の脆弱性(CVE)をスキャンしましょう。docker scout(旧 snyk ベースの docker scan)が組み込みです。Trivy と Grype が人気の代替です。CI にスキャンを組み込み、高深刻度の CVE を持つイメージをブロックしましょう。新しい CVE の公開に合わせ、ベースイメージを定期的に再スキャンします。

docker
# docker scout (built-in, replaces docker scan)
docker scout cves myapp:1.0

# scan a local image
docker scout cves --format json myapp:1.0

# compare two images
docker scout compare myapp:1.0 --to myapp:1.1

# Trivy (third-party, popular)
trivy image myapp:1.0

# Grype (third-party)
grype myapp:1.0

# scan a Dockerfile for bad practices
docker scout policy myapp --only-stream-default

# integrate scanning in CI
# - build image
# - scan
# - fail the pipeline on HIGH/CRITICAL CVEs

Docker Content Trust と強化

Content Trust は署名されたイメージを pull させることを保証します。デーモンを強化しましょう:コンテナ間通信を無効化し(icc=false)、live-restore を有効化してデーモン再起動時にコンテナを生き延びさせ、user namespaces(userns-remap)を有効化してコンテナの root を非 root のホスト UID にマッピングし、より強い分離を実現します。

docker
# enable content trust (image signing)
export DOCKER_CONTENT_TRUST=1
docker pull myapp:1.0   # refuses unsigned

# sign on push
docker push myapp:1.0   # signs with your key

# daemon hardening in /etc/docker/daemon.json
# {
#   "userland-proxy": false,
#   "live-restore": true,
#   "no-new-privileges": true,
#   "icc": false   # disable inter-container communication on default bridge
# }

# restrict registry access
# "registry-mirrors": [],
# "insecure-registries": []

# audit the daemon
docker info --format '{{json .SecurityOptions}}'

# use user namespaces for host UID isolation
# /etc/docker/daemon.json: "userns-remap": "default"
19

ロギングとモニタリング

ログの表示

docker logs はロギングドライバが取り込んだ stdout/stderr を読みます。アプリはファイルではなく stdout へログを書くべきです — そうすれば docker logs と統合できます。--tail と --since が出力を制限します。Compose の logs はサービスをまたいで集約します。デフォルトの json-file ドライバは上限を設けないと際限なく大きくなります。

docker
# follow logs
docker logs -f web

# last 100 lines
docker logs --tail 100 web

# since a timestamp
docker logs --since 30m web

# with timestamps
docker logs -t web

# a specific time range
docker logs --since 1h --until 30m web

# write logs to a file
docker logs web > web.log 2>&1

# logs for all containers (compose)
docker compose logs -f
docker compose logs -f web db

ログドライバ

json-file ドライバはローテーションなしで際限なく大きくなります — ディスクの枯渇を防ぐため max-size と max-file を設定しましょう。本番では、ログを中央のシステムへ送ります(fluentd、splunk、awslogs、gelf)。daemon.json でグローバルデフォルトを設定すれば、すべてのコンテナがデフォルトでローテーションされます。

docker
# default: json-file
docker run -d --log-driver=json-file nginx

# cap log size and rotate (json-file)
docker run -d \
  --log-driver=json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  nginx

# syslog
docker run -d --log-driver=syslog nginx

# journald
docker run -d --log-driver=journald nginx

# fluentd / splunk / gelf / awslogs
docker run -d --log-driver=fluentd nginx

# global default in /etc/docker/daemon.json
# { "log-driver": "json-file",
#   "log-opts": { "max-size": "10m", "max-file": "3" } }

ログのタグ付けと属性

tag テンプレートがログの識別子をカスタマイズします — {{.Name}} を使うと切り詰められた ID ではなく読みやすいコンテナ名になります。fluentd/splunk 向けに、ラベルと環境変数がログレコードに付与されフィルタリングに使えます。デーモンレベルのタグテンプレートを設定すれば、すべてのコンテナが一貫してタグ付けされます。

docker
# tag logs with container name instead of ID
docker run -d \
  --log-driver=json-file \
  --log-opt tag="{{.Name}}" \
  nginx

# tag with image name and tag
--log-opt tag="{{.ImageName}}/{{.Name}}"

# fluentd: add labels and attributes
docker run -d \
  --log-driver=fluentd \
  --log-opt fluentd-address=localhost:24224 \
  --log-opt tag="docker.{{.Name}}" \
  --log-opt labels=app,env \
  --label app=web --label env=prod \
  nginx

# syslog with facility
docker run -d --log-driver=syslog \
  --log-opt syslog-facility=daemon nginx

Stats とリソースモニタリング

stats が CPU、メモリ、ネットワーク、ブロック IO をストリーミングします。docker events はデーモンイベントのリアルタイムストリームです — アラートスクリプトに有用です。docker top はコンテナ内のプロセスを示し、docker diff はイメージ作成以後のファイルシステムの変更を示します(A = 追加、C = 変更、D = 削除)。

docker
# live stats for all containers
docker stats

# specific container, one snapshot
docker stats --no-stream web

# custom format
docker stats --format "table {{.Name}}	{{.CPUPerc}}	{{.MemUsage}}	{{.NetIO}}"

# events stream (start, stop, die, etc.)
docker events

# filter events
docker events --filter type=container --filter event=die

# container process list (like top)
docker top web

# container file changes since creation
docker diff web

Docker Events

docker events はライフサイクルイベント(create、start、stop、pause、die、destroy、加えてイメージとネットワークのイベント)のリアルタイムストリームです。type、event、container でフィルタできます。コンテナの死に反応したり失敗したサービスを自動再起動するアラートスクリプトの基礎です。

docker
# stream all events
docker events

# container events only
docker events --filter type=container

# specific event types
docker events --filter event=start --filter event=die

# events for a specific container
docker events --filter container=web

# events since a timestamp
docker events --since 1h

# format output
docker events --format '{{.Time}} {{.Action}} {{.Actor.Attributes.name}}'

# pipe to a monitoring script
docker events --filter event=die | while read event; do
  echo "Container died: $event"
done

Prometheus と Grafana スタック

cAdvisor は Prometheus 形式でコンテナごとのメトリクス(CPU、メモリ、ネットワーク、ファイルシステム)を公開します。Prometheus がそれを収集して保存し、Grafana が可視化します。これが Docker の事実上のオープンソース監視スタックです。ホストのメトリクスには node-exporter、アラートには alertmanager を加えましょう。

docker
# run cAdvisor (container metrics exporter)
docker run -d --name cadvisor \
  -v /:/rootfs:ro -v /var/run:/var/run:ro \
  -v /sys:/sys:ro -v /var/lib/docker/:/var/lib/docker:ro \
  -p 8080:8080 gcr.io/cadvisor/cadvisor

# run Prometheus
docker run -d -p 9090:9090 \
  -v ./prometheus.yml:/etc/prometheus/prometheus.yml \
  prom/prometheus

# run Grafana
docker run -d -p 3000:3000 grafana/grafana

# scrape cAdvisor in prometheus.yml
# scrape_configs:
#   - job_name: cadvisor
#     static_configs:
#       - targets: ['cadvisor:8080']

# view dashboards in Grafana at http://localhost:3000
20

Docker Swarm

Swarm の初期化

swarm init が Docker ホストを Swarm マネージャーに変えます。join トークンでワーカーと追加のマネージャーが参加します。マネージャートークンは秘密にしましょう — クラスタを制御できてしまいます。Raft の合意耐性のため、マネージャーは奇数(3 か 5)で運用します。ワーカーがタスクを実行し、マネージャーがスケジュールします。

docker
# initialize a Swarm (this node becomes a manager)
docker swarm init --advertise-addr 10.0.0.5

# get a join token for workers
docker swarm join-token worker

# get a join token for managers
docker swarm join-token manager

# on a worker node
docker swarm join --token SWMTKN-... 10.0.0.5:2377

# list nodes
docker node ls

# promote a worker to manager
docker node promote <node>

# demote a manager
docker node demote <node>

# leave the Swarm (worker)
docker swarm leave

サービスのデプロイ

サービスは Swarm におけるコンテナの抽象化です。replicated サービスは N 個の同一タスクを実行し、global サービスはノードごとに 1 タスクを実行します。update はデフォルトでダウンタイムゼロで新しいイメージをロールアウトします。scale がレプリカ数をライブで変えます。ノードが落ちたら Swarm が再スケジュールします。

docker
# deploy a service
docker service create --name web -p 80:80 nginx

# with replicas
docker service create --name web --replicas 3 -p 80:80 nginx

# with a constraint (e.g. only on worker nodes)
docker service create --name web --replicas 3 \
  --constraint node.role==worker nginx

# with a global service (one per node)
docker service create --name log --mode global fluentd

# update the image
docker service update --image nginx:1.25 web

# scale a service
docker service scale web=5

# remove a service
docker service rm web

スケールと更新

scale がレプリカ数を即座に変えます。update がローリングアップデートを行います — parallelism が一度に更新するタスク数を、delay が間隔を制御し、failure-action=rollback がエラー時に自動で巻き戻します。Swarm は新しいタスクが健全になるまで古いタスクを動かし続け、ダウンタイムゼロのデプロイを可能にします。

docker
# scale up
docker service scale web=10

# scale multiple services
docker service scale web=5 worker=8

# rolling update
docker service update --image myapp:2.0 web

# update with parallelism and delay
docker service update \
  --image myapp:2.0 \
  --update-parallelism 2 \
  --update-delay 30s \
  --update-failure-action rollback \
  web

# environment or port update without redeploy
docker service update --env-add DEBUG=true web
docker service update --publish-rm 80:80 --publish-add 8080:80 web

# rollback to previous version
docker service rollback web

Stack のデプロイ

スタックは Swarm にデプロイされた Compose ファイルです。deploy: キーがレプリカ、更新/ロールバックポリシー、配置の制約、リソースを設定します — すべて Swarm 固有です。docker stack deploy が宣言的に仕様を適用します。スタックが関連するサービス、ネットワーク、シークレットをグループ化します。

docker
# docker-compose.yml as a Swarm stack
docker stack deploy -c docker-compose.yml mystack

# the compose file uses deploy: for Swarm config
services:
  web:
    image: nginx
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure
      placement:
        constraints: [node.role == worker]
    ports:
      - "80:80"

# list stacks and services
docker stack ls
docker stack services mystack

# remove a stack
docker stack rm mystack

ノードの管理

メンテナンス前にノードを drain しましょう — そのノードのタスクが他へ優雅に再スケジュールされます。active/pause/drain がスケジューリングを制御します。ラベルで配置の制約が可能です(例:tier=db とラベル付けされたノードでだけ DB を動かす)。ノードは docker swarm leave で Swarm から離脱した後にだけ削除しましょう。

docker
# list nodes
docker node ls

# node details (status, role, labels, resources)
docker node inspect <node>

# drain a node (reschedule tasks off it, for maintenance)
docker node update --availability drain <node>

# activate a drained node
docker node update --availability active <node>

# pause a node (no new tasks, existing stay)
docker node update --availability pause <node>

# add a label (for placement constraints)
docker node update --label-add tier=db <node>

# remove a node from the Swarm
docker node rm <node>
# (node must have left via 'docker swarm leave' first)

Secrets と Config

シークレットは保存時も転送時も暗号化され、/run/secrets の下のファイルとしてマウントされ、イメージレイヤーや環境変数には決して書き込まれません。不変です — ローテーションするには、新しいシークレットを作りサービスを更新します。Configs は似ていますが、設定ファイルのような機密でないデータ向けです。どちらも Swarm 専用です。

docker
# create a secret from a file
docker secret create db_password ./db_password.txt

# create from stdin
echo "supersecret" | docker secret create db_password -

# use in a service
docker service create --name app --secret db_password myapp

# read in the app
# cat /run/secrets/db_password

# update a secret (immutable — create a new one)
echo "newsecret" | docker secret create db_password_v2 -
docker service update --secret-rm db_password --secret-add source=db_password_v2 app

# configs (non-sensitive, e.g. nginx.conf)
echo "server {...}" | docker config create nginx_conf -
docker service create --config nginx_conf nginx

# list and remove
docker secret ls
docker config ls

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.