Dockerは非常に便利な仮想化ツールですが、その反面、初心者がつまずきやすいポイントも数多く存在します。

この記事では「Dockerでよくやりがちな失敗例とその解決法10選」と題し、開発現場や本番運用で実際によく発生するトラブルと、それを防ぐための具体的な対処法について詳しく解説いたします。

実際のコード例を交えながら、丁寧に順を追ってご紹介します。

1. イメージサイズが巨大になる

Docker初心者が最初に直面しがちな問題のひとつが、イメージサイズの肥大化です。

例えば以下のようなDockerfileは一見シンプルですが、無駄なファイルまで含まれてしまい、不要にサイズが大きくなってしまいます。

DockerfileCopy codeFROM node:18
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "index.js"]

原因

• .git や node_modules、.env など、不要なファイルやフォルダを除外していない
• マルチステージビルドを使わず、開発用と本番用を混在させている

解決策

• .dockerignore ファイルを活用
• ビルドと実行を分離したマルチステージビルドを使用

dockerfileCopy code# .dockerignore
node_modules
dist
.env
.git
.DS_Store
coverage

# Dockerfile
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:18
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]

こうすることで、依存関係やビルド結果のみを本番環境に含められ、サイズの最小化とセキュリティ向上の両方を実現できます。

詳細は公式ドキュメントをご参照ください。

2. キャッシュの活用を無視して毎回フルビルド

Dockerでは、レイヤーキャッシュを適切に活用することで、ビルド時間を大幅に短縮できます。

以下のような記述は、毎回 npm install が再実行されてしまう典型例です。

DockerfileCopy codeCOPY . .
RUN npm install

コード変更のたびにキャッシュが無効化され、node_modulesの再構築が発生してしまいます。

解決策

依存関係の変更が無い限りキャッシュを利用できるよう、package.json などを先にコピーしましょう。

DockerfileCopy codeCOPY package*.json ./
RUN npm install
COPY . .

実行例：

bashCopy codedocker build -t my-app .

この方法により、package.jsonに変更がない限り、キャッシュされたレイヤーが使われます。

キャッシュの詳細もぜひご確認ください。

3. コンテナ内にデータを保存してしまい永続化できない

MySQLやPostgreSQLなどのデータベースをDockerで動かす際、コンテナ削除でデータが失われるトラブルは非常に多いです。

bashCopy codedocker run -d --name mysql -e MYSQL_ROOT_PASSWORD=root mysql:8

このままだと、コンテナを削除するとDBのデータもすべて消えてしまいます。

解決策

Docker Volumeを使って、永続化領域を分離します。

bashCopy codedocker volume create mysql-data

docker run -d \
  --name mysql \
  -v mysql-data:/var/lib/mysql \
  -e MYSQL_ROOT_PASSWORD=root \
  mysql:8

また、docker-compose.ymlを使用する場合は以下のように設定します：

yamlCopy codeversion: '3.9'
services:
  db:
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: root
    volumes:
      - mysql-data:/var/lib/mysql

volumes:
  mysql-data:

Volumeの使い方はこちら。

4. コンテナをrootユーザーで実行してしまう

セキュリティの観点から、Dockerコンテナ内のプロセスをrootユーザーで動かすのは避けるべきです。

DockerfileCopy codeFROM node:18
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "index.js"]

このような設定では、すべてのコマンドがroot権限で実行されてしまいます。

解決策

非特権ユーザーを作成し、コンテナ内の実行ユーザーとして明示的に指定しましょう。

DockerfileCopy codeFROM node:18
RUN useradd --user-group --create-home --shell /bin/false appuser
WORKDIR /home/appuser/app
COPY --chown=appuser:appuser . .
USER appuser
CMD ["node", "index.js"]

これにより、本番環境におけるセキュリティリスクを低減できます。

USER命令の詳細はこちら。

5. latestタグに依存してバージョンを固定しない

Dockerイメージのタグにlatestを使い続けると、予期せぬバージョンアップによりアプリケーションの動作が不安定になる可能性があります。

DockerfileCopy codeFROM node:latest

このように書かれたDockerfileでは、次回ビルド時に取得されるイメージが異なっている場合があり、想定外の不具合につながります。

解決策

明示的に安定したバージョンを指定しましょう。

DockerfileCopy codeFROM node:18.19.1

CI/CDパイプラインでは、イメージのバージョンが常に固定されていることで、再現性のあるビルドが可能になります。

yamlCopy codeimage: node:18.19.1

イメージのバージョン指定については、Docker Hubでタグ一覧を確認できます。

6. マルチコンテナ構成をdocker runで構築してしまう

複数のサービス（アプリケーション＋DBなど）を構成する場合、docker runでそれぞれ立ち上げるのは煩雑で非効率です。

bashCopy codedocker run -d --name db postgres

docker run -d --name app --link db my-app

このように手動で個別に起動すると、管理が煩雑になり、環境ごとの差異も発生しやすくなります。

解決策

docker-compose.ymlを使用して、マルチコンテナを一元的に管理します。

yamlCopy codeversion: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: example

以下のコマンドで起動できます：

bashCopy codedocker-compose up -d

Composeの基本を参考にしてください。

7. ネットワーク設定の理解不足による通信トラブル

コンテナ間通信やホストからのアクセスがうまくいかない原因は、Dockerネットワークのモード設定の理解不足によることが多いです。

例：bridgeモードで通信できない

bashCopy codedocker run --rm alpine ping my-db

このときmy-dbが同じネットワークに属していないと名前解決されません。

解決策

カスタムネットワークを作成し、コンテナを同一ネットワークに配置します。

bashCopy codedocker network create app-net

docker run -d --name db --network app-net postgres

docker run -it --rm --network app-net alpine ping db

Dockerのネットワーク詳細は公式解説を参照してください。

8. ログ管理を疎かにしてトラブル対応が困難になる

Dockerコンテナのログが消えてしまったり、確認しにくくなるのは、ログ戦略が設計されていない場合です。

よくある失敗

bashCopy codedocker logs my-app

この方法では、コンテナ削除時にログも失われます。

解決策

ログドライバを使った保存設定や、ログ集約サービスへの連携を行いましょう。

bashCopy codedocker run \
  --log-driver json-file \
  --log-opt max-size=10m \
  --log-opt max-file=5 \
  my-app

また、FluentdやCloudWatch、ELKスタックとの連携も推奨されます。

ログドライバの詳細

9. シークレット情報をDockerfileに直書きしてしまう

APIキーやパスワードをENV命令でDockerfileに記述するのは重大なセキュリティリスクです。

DockerfileCopy codeENV API_KEY=my-secret-key

この情報は、イメージの中に永続的に保存され、誰でも閲覧できる状態になります。

解決策

ビルド引数やDocker Secretsの使用を検討しましょう。

DockerfileCopy codeARG API_KEY
RUN echo "API_KEY=${API_KEY}" >> /tmp/key.txt

ビルド時に値を渡す：

bashCopy codedocker build --build-arg API_KEY=abcdef .

本番用途では、SwarmやKubernetesと連携したDocker Secretsを活用するとより安全です。

10. Docker Composeでのベストプラクティスを無視

docker-compose.ymlファイルにおいて、複数環境の設定を直書きしたり、起動順の依存だけに頼った構成は保守性を下げます。

よくある問題

• .envの未使用
• depends_onで起動順だけを保証（完了は保証されない）

解決策

• .envファイルを使った環境変数の分離
• healthcheckを使って起動の完了を明示
• overrideファイルを使った環境ごとの分割

yamlCopy codeservices:
  db:
    image: mysql
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_PASSWORD}
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 5s
      retries: 3

詳細：Composeファイルベストプラクティス。

まとめ

Dockerは柔軟でパワフルなツールですが、基礎的な設計ミスや運用上の盲点によって、トラブルや非効率な状態に陥ることが多々あります。

本記事では特に発生頻度の高い失敗例を10項目に整理し、それぞれに対する具体的な解決策を提示してきました。

No.	よくある失敗例	推奨される解決策
1	イメージが肥大化する	.dockerignoreやマルチステージビルドを活用
2	キャッシュを無視したビルド	依存関係の先読みによるキャッシュ利用
3	データ永続化を考慮しない	VolumeやBind Mountを活用
4	rootユーザーでの実行	非特権ユーザーを明示的に設定
5	latestタグへの依存	明示的にイメージバージョンを指定
6	マルチコンテナを手動で管理	docker-composeによる定義と一括起動
7	ネットワーク設定の誤解	カスタムネットワークの明示的な活用
8	ログ管理を疎かにする	ログドライバと外部連携を併用
9	シークレット情報の直書き	build-argやsecretsで安全に管理
10	Compose設計のベストプラクティスを無視	.env/healthcheck/overrideの活用

これらのベストプラクティスを順守することで、開発効率が向上するだけでなく、セキュリティや可搬性、保守性といった本番環境で求められる要件にも対応できます。

Dockerを安全かつ効果的に運用するためには、公式ドキュメントの確認と、小さなミスを見逃さない設計意識が重要です。

公式情報の継続的なチェックも習慣にしながら、実践と改善を繰り返していきましょう。