Docker compose upエラーの原因と解決方法【初心者向け完全ガイド】

Dockerを使用した開発環境の構築時に、docker compose upコマンドを実行したら予期しないエラーが発生した経験はありませんか？このコマンドはマルチコンテナアプリケーションを起動する際に頻繁に使用されますが、様々な原因でエラーが発生します。本記事では、Docker compose upエラーの原因と具体的な解決手順を、初心者向けにわかりやすく解説します。

Docker compose upエラーが発生する主な原因
Docker compose upエラーの解決手順
docker-compose.ymlの正しい記述例とコード
よくある間違いと対処法
トラブルシューティングの実践例
1. 実際のエラーケースと解決策
Docker Composeの便利なデバッグコマンド
パフォーマンス最適化とベストプラクティス
まとめ

Docker compose upエラーが発生する主な原因

Docker compose upコマンドで発生するエラーには、複数の原因が存在します。それぞれの原因を理解することで、トラブルシューティングがより効率的になります。

1. docker-compose.ymlファイルの構文エラー

最も一般的なエラー原因は、YAMLファイルの構文の誤りです。YAMLはインデント（スペース）に非常に敏感な形式であり、タブ文字やスペース数の誤りが容易にエラーを引き起こします。

2. イメージが見つからない

指定したDockerイメージが存在しない場合や、ローカルに保存されていない場合にエラーが発生します。特に、イメージ名やバージョンタグの誤りがこの原因となります。

3. ポート競合エラー

複数のコンテナが同じポート番号を使用しようとする場合や、ホストマシン上で既に別のプロセスがそのポートを使用している場合にエラーが発生します。

4. ボリュームマウントの問題

指定されたボリュームパスが存在しない、またはアクセス権限がない場合にエラーが発生します。

5. ネットワーク設定の不備

Dockerネットワークの設定が不正な場合や、コンテナ間の通信が正しく設定されていない場合にエラーが発生します。

Docker compose upエラーの解決手順

ステップ1: エラーメッセージを詳しく確認する

最初のステップは、出力されたエラーメッセージを注意深く読むことです。エラーメッセージには問題の原因に関する重要な情報が含まれています。

docker compose up --verbose

--verboseフラグを使用することで、より詳細なログ情報を取得できます。

ステップ2: docker-compose.ymlファイルの検証

YAMLの構文を検証するツールを使用するか、Dockerが提供する検証機能を使用します。

docker compose config

このコマンドは、docker-compose.ymlファイルの構文をチェックし、有効な場合は解析結果を表示します。

ステップ3: Dockerイメージの確認

使用するイメージがローカルに存在するか確認します。

docker images

必要なイメージが存在しない場合は、明示的にプルする必要があります。

docker pull イメージ名:タグ

ステップ4: ポート設定の確認

既に使用されているポートを確認します。

netstat -tuln | grep LISTEN

ステップ5: ボリュームパスの確認

マウントするパスが存在し、アクセス可能であることを確認します。

ls -la /パス/へ/ディレクトリ

ステップ6: Dockerデーモンの再起動

キャッシュやその他の問題を解決するため、Dockerデーモンを再起動します。

docker compose down
docker system prune
docker compose up

docker-compose.ymlの正しい記述例とコード

基本的な構成例

version: '3.8'

services:
  web:
    image: nginx:latest
    container_name: web_container
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
    networks:
      - app_network

  db:
    image: mysql:8.0
    container_name: db_container
    environment:
      MYSQL_ROOT_PASSWORD: root_password
      MYSQL_DATABASE: app_db
    volumes:
      - db_data:/var/lib/mysql
    networks:
      - app_network

volumes:
  db_data:

networks:
  app_network:
    driver: bridge

エラーが起こりやすい誤った例

version: '3.8'
services:
  web:
    image: nginx
    ports:
      - "80:80"
    # インデントが誤っている場合
   volumes:  # このインデントが間違っている
      - ./html:/usr/share/nginx/html

正しい修正例

version: '3.8'
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
    environment:
      - NGINX_HOST=example.com
      - NGINX_PORT=80

より実践的な例：複数コンテナの連携

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: app_container
    ports:
      - "8000:8000"
    environment:
      - DB_HOST=db
      - DB_PORT=5432
      - DB_NAME=myapp
      - DB_USER=postgres
      - DB_PASSWORD=password
    volumes:
      - ./src:/app/src
      - ./logs:/app/logs
    depends_on:
      - db
    networks:
      - backend_network
    restart: unless-stopped

  db:
    image: postgres:13
    container_name: db_container
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
    networks:
      - backend_network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: cache_container
    ports:
      - "6379:6379"
    networks:
      - backend_network
    restart: unless-stopped

volumes:
  postgres_data:

networks:
  backend_network:
    driver: bridge

よくある間違いと対処法

間違い1: インデント不正によるYAML構文エラー

症状: “mapping values are not allowed here”というエラーが表示される。

原因: YAMLでタブ文字を使用している、またはスペース数が不正。

対処法: YAMLファイルはスペース2個または4個で統一し、タブ文字を使用しない。

# 正しい: スペース2個でインデント
services:
  web:
    image: nginx

# 間違い: タブ文字を使用
services:
	web:  # タブ文字がある
		image: nginx

間違い2: ポート番号の競合

症状: “Bind for 0.0.0.0:80 failed”というエラーが表示される。

原因: 指定したポートが既に使用されている。

対処法: 別のポート番号を使用するか、既に使用しているプロセスを停止する。

services:
  web:
    ports:
      - "8080:80"  # ホストの8080をコンテナの80にマップ

間違い3: イメージが見つからない

症状: “pull access denied for IMAGE_NAME”というエラーが表示される。

原因: イメージ名またはタグが誤っている、またはプライベートレジストリへのアクセス権限がない。

対処法: イメージ名を確認し、必要に応じてタグを指定する。

docker search nginx
docker pull nginx:latest

# docker-compose.ymlで正しいバージョンを指定
image: nginx:latest

間違い4: ボリュームパスが存在しない

症状: “volume not found”またはマウント関連のエラーが発生。

原因: 指定されたホストパスが存在しない。

対処法: パスを確認して作成する。

mkdir -p ./data
mkdir -p ./logs

# docker-compose.ymlで相対パスを使用
volumes:
  - ./data:/app/data
  - ./logs:/app/logs

間shortcuts 5: depends_onの使用誤り

症状: サービスの起動順序が不正で、接続エラーが発生。

原因: depends_onは起動順序のみを制御し、起動完了を待たない。

対処法: healthcheckとwait-for-itスクリプトを使用する。

services:
  app:
    depends_on:
      db:
        condition: service_healthy

  db:
    healthcheck:
      test: ["CMD", "mysql", "-h", "localhost", "-u", "root"]
      interval: 5s
      timeout: 5s
      retries: 10

間違い6: 環境変数の設定不正

症状: アプリケーションが正しく起動しない、設定値が反映されない。

原因: 環境変数の形式が誤っている。

対処法: リスト形式またはdictionary形式で正しく記述する。

services:
  app:
    # リスト形式
    environment:
      - DB_HOST=localhost
      - DB_PORT=5432
    
    # またはdictionary形式
    # environment:
    #   DB_HOST: localhost
    #   DB_PORT: 5432

トラブルシューティングの実践例

実際のエラーケースと解決策

ケース1: YAMLの構文エラー

# エラーメッセージ
error while parsing 'docker-compose.yml': yaml: line 10: mapping values are not allowed here

# 検証コマンド実行
$ docker compose config
# 問題箇所を確認

# 問題を修正後、再度実行
$ docker compose up -d

ケース2: ポート競合エラー

# エラーメッセージ
error while creating mount source path '.../data': mkdir: permission denied

# 既に使用中のポート確認
$ lsof -i :80

# 別のポートで実行するか、既存プロセスを停止
$ docker compose up -d

Docker Composeの便利なデバッグコマンド

エラー解決に役立つコマンドをいくつか紹介します。

# 詳細なログを表示
docker compose logs -f

# 特定のサービスのログを表示
docker compose logs web

# コンテナの状態を確認
docker compose ps

# 設定ファイルを検証
docker compose config

# すべてのリソースを削除
docker compose down -v

# イメージを再ビルド
docker compose up --build

パフォーマンス最適化とベストプラクティス

エラーを防ぐためのベストプラクティスを実装することが重要です。

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      # イメージのキャッシュを活用
    image: myapp:latest
    container_name: app
    
    # 環境ファイルの使用
    env_file:
      - .env
    
    # 自動再起動の設定
    restart: unless-stopped
    
    # リソース制限
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M
    
    # ヘルスチェック
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s