セットアップガイド

【Docker/環境】Docker ComposeでAI開発環境を一括構築！よくあるエラーと解決法

· 17分で読めます · 2 閲覧

問題の概要：Docker ComposeによるAI環境構築で発生する典型的な課題

AI開発、特に機械学習や深層学習のプロジェクトでは、Pythonバージョン、CUDA/cuDNN、PyTorch/TensorFlowのバージョン、さらにはJupyter Labや各種ライブラリの依存関係など、環境構築が非常に複雑です。Docker Composeを使えば、これらを一括で定義・構築できますが、初心者から中級者にかけて以下のようなエラーに頻繁に遭遇します。

  • ERROR: Couldn't connect to Docker daemon at http+docker://localhost - is it running?
  • GPUがコンテナ内から認識されない（torch.cuda.is_available()がFalseを返す）
  • ビルド中のERROR: Failed to build PyTorch from sourceやメモリ不足エラー
  • ボリュームマウントのパーミッションエラー（Permission denied）
  • コンテナ間のネットワーク通信エラー（例：AppコンテナからDBコンテナに接続できない）

本記事では、これらの課題を解決し、再現性の高いAI開発環境をDocker Composeで確立する方法を解説します。

原因の解説：なぜエラーが発生するのか？

上記のエラーは、主に以下の4つの根本原因に起因しています。

1. Dockerデーモンの起動状態とユーザー権限

Couldn't connect to Docker daemonエラーは、Dockerサービスが起動していないか、実行ユーザーがdockerグループに属していないために発生します。Dockerはクライアント-サーバーアーキテクチャを採用しており、dockerコマンドはサーバー（デーモン）と通信する必要があります。

2. NVIDIA Dockerランタイムの未設定

コンテナ内でGPUを使用するには、ホストマシンにNVIDIAドライバ、NVIDIA Container Toolkitがインストールされ、Dockerの設定でnvidiaをデフォルトランタイムとして指定する必要があります。これが不足していると、CUDAデバイスを認識できません。

3. リソース（メモリ/ディスク）不足とDockerfileの非効率性

PyTorchなどの大型ライブラリをソースからビルドするDockerfileは、非常に多くのメモリとディスク容量を消費します。また、レイヤーキャッシュを効率的に使っていないDockerfileは、毎回のビルドに時間がかかり、その過程で失敗しやすくなります。

4. LinuxとDockerのユーザー/グループID不一致

ホストマシン（例えばUID 1000）で作成したファイルを、コンテナ内（例えばrootユーザー）でマウントすると、コンテナ内のプロセスがホストのファイルに書き込みできずPermission deniedエラーが発生します。これはデータセットの前処理やモデルの保存時に問題となります。

解決方法：ステップバイステップで堅牢な環境を構築

ステップ1: ホスト環境の前提条件を整える

まず、DockerとDocker Compose、そしてGPUを使う場合はNVIDIA Container Toolkitをインストール・設定します。

# Dockerサービスが起動しているか確認し、起動する
sudo systemctl status docker
sudo systemctl start docker
sudo systemctl enable docker

# 現在のユーザーをdockerグループに追加（要再ログイン）
sudo usermod -aG docker $USER

# NVIDIA Container Toolkitのインストール（GPU利用時）
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

# nvidiaランタイムが有効か確認
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

ステップ2: プロジェクト構成とdocker-compose.ymlの作成

プロジェクトルートに以下のような構成でファイルを作成します。ここでは、Jupyter Lab、PyTorch、PostgreSQL（実験管理用）を含む環境を想定します。

my_ai_project/
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── scripts/          # 初期化スクリプトなど
├── data/             # ボリュームマウント用（.gitignore対象）
└── notebooks/        # Jupyter Notebooks

docker-compose.yml

version: '3.8'

services:
  jupyter-lab:
    build: .
    container_name: ai_dev_jupyter
    ports:
      - "8888:8888"
    volumes:
      - ./notebooks:/workspace/notebooks
      - ./data:/workspace/data
      - ./src:/workspace/src
    environment:
      - JUPYTER_TOKEN=mysecuretoken123
      - TZ=Asia/Tokyo
    working_dir: /workspace
    command: jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root --NotebookApp.token=${JUPYTER_TOKEN}
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    # ホストと同じUID/GIDで実行するための設定（Linuxの場合）
    user: "${UID:-1000}:${GID:-1000}"
    networks:
      - ai-network

  postgres:
    image: postgres:15
    container_name: ai_dev_db
    environment:
      POSTGRES_USER: mlflowuser
      POSTGRES_PASSWORD: mlflowpassword
      POSTGRES_DB: mlflowdb
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    networks:
      - ai-network

volumes:
  postgres_data:

networks:
  ai-network:
    driver: bridge

ステップ3: 効率的でエラーに強いDockerfileの作成

ベースイメージの選択とレイヤーキャッシュを意識した記述が鍵です。

# Dockerfile
# 軽量で、必要なCUDAバージョンが公式で提供されているイメージを選択
FROM nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04

# ビルド引数でユーザー設定を可能に
ARG UID=1000
ARG GID=1000

# 非対話型インストールを設定し、タイムゾーンを設定
ENV DEBIAN_FRONTEND=noninteractive
ENV TZ=Asia/Tokyo

# キャッシュを効かせるため、パッケージ更新とPythonインストールを最初のレイヤーで
RUN apt-get update && apt-get install -y 
    python3.10 
    python3-pip 
    python3.10-venv 
    git 
    curl 
    wget 
    && ln -s /usr/bin/python3.10 /usr/bin/python 
    && rm -rf /var/lib/apt/lists/*

# ワークスペース作成とユーザー作成（パーミッション問題対策）
RUN groupadd -g ${GID} appuser && 
    useradd -m -u ${UID} -g appuser -s /bin/bash appuser
WORKDIR /workspace

# 依存関係ファイルをコピー（このレイヤーはrequirements.txtが変更された時のみ再実行）
COPY requirements.txt .
# pipキャッシュを使い、依存関係をインストール
RUN pip install --no-cache-dir --upgrade pip && 
    pip install --no-cache-dir -r requirements.txt

# 所有権を非rootユーザーに変更
RUN chown -R appuser:appuser /workspace
USER appuser

# デフォルトコマンド（compose.ymlで上書きされる）
CMD ["/bin/bash"]

requirements.txt (例)

torch==2.1.0
torchvision==0.16.0
torchaudio==2.1.0
--index-url https://download.pytorch.org/whl/cu121
jupyterlab==4.0.10
pandas==2.1.4
scikit-learn==1.3.2
matplotlib==3.8.2
seaborn==0.13.0
mlflow==2.9.2
psycopg2-binary==2.9.9

ステップ4: 環境変数ファイルと起動スクリプトの活用

.envファイルを作成し、UID/GIDをホスト環境に合わせます。これでパーミッションエラーを解消します。

# .env (ホストマシンで `id -u` と `id -g` の結果を記入)
UID=1000
GID=1000

起動用のシェルスクリプトup.shを作成すると便利です。

#!/bin/bash
# up.sh
echo "Starting AI Development Environment..."
echo "UID=$(id -u) GID=$(id -g)"

# ネットワークとボリュームを含めて起動
docker-compose up -d

# Jupyter Labのログを表示（Ctrl+Cで終了）
echo "Waiting for Jupyter Lab to start..."
sleep 3
docker-compose logs -f jupyter-lab

# 実行権限付与と起動
chmod +x up.sh
./up.sh

コード例・コマンド例：トラブルシューティングコマンド集

問題が発生した際に役立つコマンドです。

# 1. ビルドエラー時、キャッシュなしでクリーンビルド
docker-compose build --no-cache

# 2. コンテナ内でコマンドを実行（例：Pythonテスト）
docker-compose exec jupyter-lab python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

# 3. ログの詳細確認（エラー原因調査）
docker-compose logs --tail=50 jupyter-lab

# 4. ボリュームマウントのパーミッションを修正（ホスト側で実行）
sudo chown -R $USER:$USER ./data ./notebooks

# 5. 使用していないコンテナ、イメージ、ボリュームを一括削除（クリーンアップ）
docker-compose down -v
docker system prune -a -f

# 6. GPUがコンテナから見えているか確認
docker-compose run --rm jupyter-lab nvidia-smi

# 7. ネットワーク状態を確認
docker network ls
docker-compose exec postgres ping -c 2 jupyter-lab

まとめ・補足情報

Docker Composeを使ったAI開発環境の構築は、最初の設定に少し手間がかかりますが、一度テンプレートを作成してしまえば、異なるマシンや複数のプロジェクトで環境の一貫性と再現性を劇的に高めることができます。本記事で紹介したポイントを押さえることで、よくあるエラーを回避し、生産的な開発環境を手に入れることができます。

補足情報：

  • 開発と本番の分離： 開発用のdocker-compose.ymlと本番用のdocker-compose.prod.ymlを分けることをお勧めします。本番ではJupyterを公開せず、代わりにAPIサーバー（FastAPI等）のサービスを定義します。
  • ビルド時間の短縮： PyTorch/TensorFlowは可能な限り公式のプリビルド済みWheel（--index-url指定）を使い、ソースビルドは避けましょう。
  • セキュリティ： .envファイルにはパスワードやトークンを含めますが、絶対にGitリポジトリにコミットしないでください。.gitignoreに追加を忘れずに。
  • Windows/macOSユーザーへ： ファイルパスの扱い（ボリュームマウント）やGPUサポート（macOSは非対応）に違いがあります。Docker Desktopの設定を確認し、WSL2（Windows）を活用することをお勧めします。

このテンプレートをベースに、ご自身のプロジェクトに必要なツール（Redis、MLflow Tracking Server、Rayなど）をサービスとして追加し、カスタマイズしていってください。

この記事は役に立ちましたか？