Docker を使いこなす

実務では、手元のサービスも依存も、ほぼすべてコンテナで動きます。

docker compose up は毎日打つことになりますが、 その裏で何が起きているかを知らないと、詰まった時に何もできません。

「コンテナが起動しない」
「ビルドが10分かかる」
「保存したファイルが消えた」
「ポートに繋がらない」
「ディスクが足りない」

この章では、コンテナとは何かを理解した上で、Docker を道具として使いこなすところまでやります。

そもそもコンテナとは何か

何を解決したかったのか

コンテナが無かった頃、こういうことが日常的に起きていました。

「私の環境では動きます」
   → 開発者は Node 20、本番サーバーは Node 18 だった

「新しいサービスを同じサーバーに載せたい」
   → 片方が要求する OpenSSL のバージョンが、もう片方を壊す

「サーバーを1台増やしたい」
   → 手順書が30ページあり、誰がやっても同じ結果にならない

原因は1つです。アプリケーションが、置かれたマシンの状態に依存していたこと。

これを解決する方法として、まず仮想マシンが広まりました。 OS ごと丸ごと1セット用意すれば、確かに独立します。 しかし OS が丸ごと入るので、起動に数分かかり、1台あたり数 GB を消費します。 サービスを10個動かすために、OS を10個起動するのは重すぎました。

そこで出てきた発想が、「OS は共有したまま、プロセスから見える世界だけを分ける」 です。

仮想マシンとの違い

仮想マシン                        コンテナ
┌──────────┬──────────┐          ┌──────────┬──────────┐
│  アプリ   │  アプリ   │          │  アプリ   │  アプリ   │
│ ライブラリ │ ライブラリ │          │ ライブラリ │ ライブラリ │
│  ゲストOS │  ゲストOS │  ← 重い  ├──────────┴──────────┤
├──────────┴──────────┤          │   コンテナランタイム   │
│   ハイパーバイザ      │          ├─────────────────────┤
├─────────────────────┤          │      ホストOS        │
│      ホストOS        │          │  （カーネルを共有）    │
└─────────────────────┘          └─────────────────────┘
     起動: 数十秒〜数分                 起動: 1秒未満
     容量: 数 GB                        容量: 数十〜数百 MB

コンテナはOS を丸ごと持ちません。ホストのカーネルをそのまま使い、 プロセスから見える世界だけを分離します。だから軽く、起動が速いのです。

正体は「隔離されたプロセス」

ここが最も大事なところです。

コンテナは、軽い仮想マシンではありません。ホスト上でそのまま動いている、ただのプロセスです。

docker run したコンテナは、ホストの ps を見れば普通のプロセスとして見えます。 仮想化されているのは「そのプロセスから何が見えるか」だけです。

Linux カーネルの2つの機能でできています。

「隔離」であって「別のマシン」ではない、という理解が実務では効いてきます。

イメージとコンテナ

最初に、この2つを区別してください。

イメージ    起動していない、読み取り専用のテンプレート（設計図）
コンテナ    イメージから起動した、動いているプロセス（実体）

1つのイメージから、コンテナは何個でも作れます。 そしてコンテナを消しても、イメージは残ります。

docker images         # 手元にあるイメージ一覧
docker ps             # 動いているコンテナ
docker ps -a          # 止まっているものも含める  ← 落ちた原因を調べる時はこれ

日常で使うコマンド

# 起動する（--rm で終了時に自動削除。試すだけならこれを付ける）
docker run --rm -it postgres:17 bash
 
# 名前を付けて、バックグラウンドで、ポートを公開して起動
docker run -d --name db -p 5432:5432 -e POSTGRES_PASSWORD=pw postgres:17
 
# ログを見る（-f で追従。コマンドラインで生きるの tail -f と同じ）
docker logs -f db
docker logs --tail 100 db
 
# 動いているコンテナの中でコマンドを実行する
docker exec -it db psql -U postgres
 
# 止める・消す
docker stop db
docker rm db
 
# イメージを作る
docker build -t myapp:dev .

調べる — ここが本題

コンテナのトラブルは、中を見る手段を知っているかどうかで解決速度が変わります。

# 1. まず状態を見る（Exited なら終了コードが出る）
docker ps -a
 
# 2. ログを見る（アプリのエラーはたいていここ）
docker logs <name>
 
# 3. 中に入って確認する
docker exec -it <name> sh        # bash が無いイメージも多いので sh を試す
 
# 4. 設定を丸ごと見る（環境変数・マウント・ネットワークが全部見える）
docker inspect <name>
 
# 5. リソース消費を見る
docker stats

# 起動コマンドを上書きして、シェルで起動する
docker run --rm -it --entrypoint sh myapp:dev
 
# 落ちたコンテナのログを見る
docker logs <name>

Dockerfile を書く

FROM golang:1.24 AS build
WORKDIR /src
 
# 依存の解決だけを先にやる。コードを直してもこの層のキャッシュが効く
COPY go.mod go.sum ./
RUN go mod download
 
COPY . .
RUN CGO_ENABLED=0 go build -o /out/server ./cmd/server
 
# 2段目: バイナリだけの最小イメージ
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/server /server
USER nonroot
EXPOSE 8080
CMD ["/server"]

レイヤーとキャッシュ

Dockerfile の各命令が1つのレイヤーになり、レイヤー単位でキャッシュされます。

ある行が変わると、その行以降のキャッシュがすべて無効になる

だから、変わりにくいものを先に、変わりやすいものを後に書きます。

# 悪い: ソースを1文字直すたびに、依存のインストールが走る
COPY . .
RUN pnpm install
 
# 良い: 依存ファイルだけ先にコピーする
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .

「ビルドが遅い」の原因は、ほぼこの順序です。

.dockerignore を必ず置く

node_modules
.git
*.log
.env
dist

無いと、COPY . . で巨大な node_modules や .git まで送られます。 ビルドが遅くなるだけでなく、.env がイメージに入る事故も起きます。

CMD は exec 形式で書く

CMD ["/server"]        # 良い（server が PID 1 になる）
CMD /server            # 避ける（/bin/sh が PID 1 になる）

shell 形式で書くと、PID 1 になるのは /bin/sh で、アプリはその子プロセスになります。 プロセスとメモリで扱ったとおり、 この時アプリに SIGTERM が届く保証がありません（shell の実装や書き方によって変わります）。

届かないと、Kubernetes は猶予時間を待った後に SIGKILL します。 処理中のリクエストが切られ、後始末も走りません。 どうしても起動スクリプトを挟みたい場合は、末尾を exec "$@" にしてアプリを PID 1 に置き換えます。

非 root で動かす

USER nonroot

コンテナを破られた時にできることを減らします。 本番イメージでは必ず設定してください。

ENV API_KEY=secret123        # 絶対に駄目。イメージに焼き込まれる
ARG TOKEN                    # 秘密情報を渡す手段ではない

RUN --mount=type=secret,id=npmrc \
    npm ci --userconfig /run/secrets/npmrc

docker history myapp:dev     # 誰でも見られる

データの永続化

コンテナを削除すると、中で書いたファイルは消えます。 これは仕様であって、故障ではありません。

# ボリューム: Docker が管理する領域。DB のデータはこれ
docker run -v pgdata:/var/lib/postgresql/data postgres:17
 
# バインドマウント: ホストのディレクトリを直接見せる。開発中のソースはこれ
docker run -v "$(pwd)":/app myapp:dev

docker run -u "$(id -u):$(id -g)" -v "$(pwd)":/app myapp:dev

ネットワーク

# コンテナ同士は、Compose のサービス名で通信できる
# アプリから DB へは localhost ではなく「db」
DATABASE_URL=postgres://user:pw@db:5432/app

アプリのコンテナから見た localhost = アプリのコンテナ自身
                                    （DB のコンテナではない）

Docker Compose

なぜ必要か

ここまでのコマンドは、コンテナ1つを動かすためのものでした。 しかし実際のサービスは1つでは終わりません。

API サーバー + PostgreSQL + Redis + メール受信用のダミー

これを docker run で立てると、こうなります。

docker network create myapp
docker run -d --name db --network myapp -e POSTGRES_PASSWORD=... -v pgdata:/var/lib/postgresql/data postgres:17
docker run -d --name redis --network myapp redis:7
docker run -d --name api --network myapp -p 8080:8080 -e DATABASE_URL=... myapp:dev

打つ順番も、オプションも、全員が同じにしなければ揃いません。 新人が入るたびに、この4行を口伝することになります。

Compose は、これを1つのファイルに宣言として書くものです。 やっていること自体は docker run の集合体で、魔法ではありません。

compose.yaml を読む

services:
  api:
    build: .                      # この場所の Dockerfile からビルドする
    ports:
      - '8080:8080'               # ホスト:コンテナ
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/app
      REDIS_URL: redis://cache:6379
    volumes:
      - .:/app                    # ソースを共有して、保存したら即反映する
      - /app/node_modules         # ここだけホスト側で上書きさせない
    depends_on:
      db:
        condition: service_healthy   # DB が受付可能になるまで待つ
      cache:
        condition: service_started
 
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data   # ここが無いと消える
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U app']
      interval: 5s
      retries: 10
    ports:
      - '5432:5432'               # 手元の GUI ツールから繋ぐために開ける
 
  cache:
    image: redis:7
 
volumes:
  pgdata:

読むべき点は4つです。

日常で使うコマンド

docker compose up -d           # 起動
docker compose up -d --build   # ビルドし直してから起動
docker compose ps              # 状態
docker compose logs -f api     # 特定サービスのログを追う
docker compose exec api sh     # 動いているコンテナに入る
docker compose run --rm api pnpm test   # 使い捨てのコンテナで1回だけ実行する
docker compose down            # 停止して削除
docker compose down -v         # ボリュームごと消す（DB のデータも消える）
docker compose config          # 変数を展開した最終形を表示する（デバッグ用）

□ DB が後から再起動したら？
□ ネットワークが一瞬切れたら？
□ 本番（Kubernetes）には、そもそもこの起動順の仕組みが無い

exec  今動いているコンテナの中で実行する    → ログ調査、DB に繋ぐ、状態を見る
run   新しいコンテナを立てて実行する        → テスト、マイグレーション、単発の処理

接続先はサービス名で書く

新人が最も詰まるのがここです。

✕ DATABASE_URL=postgres://app:secret@localhost:5432/app
○ DATABASE_URL=postgres://app:secret@db:5432/app

コンテナの中の localhost は、そのコンテナ自身を指します。 API コンテナから見た DB は別のマシンなので、localhost には居ません。

Compose は自動でネットワークを作り、サービス名を名前解決できるようにしてくれます （DNS・TCP・TLSで扱った名前解決が、ここでも効いています）。

一方、手元の GUI ツールやホストのアプリから繋ぐ時は localhost です。 ports: で開けた穴を通るためで、この2つは別の話です。

□ 台数を増やして負荷を分散する
□ 落ちたら別のマシンで立て直す
□ 無停止で新しい版に入れ替える

よくあるトラブル

docker inspect <image> | grep Architecture
 
# 明示的に指定する（遅いが動く）
docker run --platform linux/amd64 ...
 
# 本番向けに両対応のイメージを作る
docker buildx build --platform linux/amd64,linux/arm64 -t myapp:1.0 .

# ディスクの使用状況を見る
docker system df
 
# 使っていないものを消す（-a は使われていないイメージも全部）
docker system prune
 
# ボリュームも消す（DB のデータが消えるので、確認してから）
docker system prune -a --volumes

セキュリティと運用の作法

□ タグに latest を使わない（何が動いているか特定できなくなる）
□ ベースイメージは小さく、更新されているものを選ぶ（distroless / alpine / slim）
□ 非 root で動かす
□ シークレットをイメージに焼き込まない
□ イメージの脆弱性スキャンを CI に入れる（ライセンスと依存ライブラリ）
□ CMD は exec 形式

開発用: ソースをバインドマウントし、ホットリロードが効く。デバッガも入れる
本番用: マルチステージでビルドし、バイナリと最小限のファイルだけ

実務の落とし穴まとめ

1. -p の左右を逆にする — ホスト:コンテナの順
2. コンテナ内で 127.0.0.1 を listen — 外から繋がらない。0.0.0.0 を使う
3. コンテナ間で localhost を使う — サービス名で呼ぶ
4. COPY . . を先に書く — キャッシュが効かず、ビルドが遅い
5. .dockerignore が無い — 巨大なファイルが送られ、.env が混入する
6. CMD を shell 形式で書く — SIGTERM が届かない（プロセスとメモリ）
7. シークレットを ENV / ARG に書く — レイヤー履歴に残る
8. latest タグ — 何が動いているか特定できない
9. root で動かす — 破られた時の被害が大きい
10. docker compose down -v をうっかり打つ — DB のデータが消える
11. arch の不一致に気づかない — 極端に遅い / 動かない

まとめ

• イメージは設計図、コンテナは実体。コンテナを消してもイメージは残る
• 調べる順番は ps -a → logs → exec → inspect。 起動直後に落ちるなら --entrypoint sh で切り分ける
• Dockerfile は変わりにくいものを先に書く。これがビルド時間を決める
• .dockerignore は必ず置く
• CMD は exec 形式、非 root、シークレットは焼き込まない
• データはボリューム（永続化）とバインドマウント（開発時のソース）を使い分ける
• コンテナ内の localhost は自分自身。listen は 0.0.0.0
• ディスクは放っておくと埋まる。docker system df と prune
• Apple Silicon と本番の arch 差は「手元では動くのに」の定番原因

公式ドキュメント

迷ったら一次情報に戻ってください。

章末問題

次の章では、この Docker を使って手元に開発環境を組み立てる話に移ります。