問題の概要：Docker ComposeでAI環境構築時に発生する典型的なエラー
AI開発を始める際、Pythonバージョン、CUDA、cuDNN、各種ライブラリの依存関係を手動で整えるのは煩雑で、環境の不一致による「私のマシンでは動いたのに…」問題の原因となります。Docker Composeを使えば、Python、JupyterLab、PyTorch/TensorFlow、GPUサポートなどを含む完全なAI開発環境を一括で構築できます。しかし、特に初心者・中級者がこのテンプレートを使いこなす際には、いくつかの典型的なエラーに遭遇します。
主な問題は以下の通りです：
- ビルドエラー:
Dockerfile内のパッケージインストール失敗や、ベースイメージの取得エラー。 - GPU認識エラー:
nvidia-dockerの設定不足により、コンテナ内でGPUが利用できない。エラーメッセージ例:RuntimeError: No CUDA GPUs are availableやCould not load dynamic library 'libcudart.so.11.0'。 - ポート競合エラー: ホストマシンですでに使用されているポート（例: 8888, 6006）をコンテナが使おうとして起動失敗。エラーメッセージ例:
Bind for 0.0.0.0:8888 failed: port is already allocated。 - ボリュームマウントエラー: ホストのディレクトリをコンテナ内にマウントする際のパーミッション問題。エラーメッセージ例:
Permission deniedでファイルが書き込めない。 - メモリ不足エラー: コンテナに割り当てるメモリが不足し、学習中にプロセスがキルされる。
原因の解説
これらのエラーは、DockerとDocker Composeの基本的な仕組みや、ホストマシンとのリソース連携に対する理解不足から発生します。
1. ビルドエラーの原因
Dockerfile内のRUN pip installコマンドで指定したライブラリのバージョンが互換性がない、またはインターネット接続（プロキシ）の問題でダウンロードに失敗します。また、FROMで指定するベースイメージ（例: nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04）が存在しないか、プライベートレジストリの認証が必要な場合にも失敗します。
2. GPU認識エラーの根本原因
DockerコンテナはデフォルトではホストのGPUデバイスにアクセスできません。NVIDIA GPUをコンテナ内で利用するには、nvidia-container-toolkitがホストにインストールされていること、そしてdocker-compose.ymlファイルでruntime: nvidia（古い記法）またはdeploy.resources.reservations.devices（新しい記法）を正しく設定する必要があります。この設定が抜けている、またはNVIDIAドライバのバージョンとコンテナ内のCUDAバージョンが互換性がない場合にエラーが発生します。
3. ポート・ボリューム・リソース問題の原因
これらはホストOSとコンテナのリソースマッピング設定に起因します。ポート競合は単純に同じポートが使われているため、ボリュームマウントのパーミッションエラーはホストとコンテナ内のユーザーID（UID）不一致が主な原因です。メモリ不足は、Docker Desktop（Mac/Windows）やDocker Engineの設定でコンテナが利用できるメモリ上限が低すぎるために起こります。
解決方法：ステップバイステップガイド
以下に、実用的なdocker-compose.ymlテンプレートとその完全なセットアップ手順を示します。
ステップ1: 事前準備（ホストマシン）
1. Docker及びDocker Composeのインストール: 最新版をインストールしてください。
2. NVIDIA GPUユーザー向け: NVIDIAドライバ、nvidia-container-toolkitをインストールします。以下のコマンドで動作確認を。
# Dockerのインストール確認
docker --version
docker-compose --version
# NVIDIA Container Toolkitのインストール（Ubuntu例）
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-container-toolkit
sudo systemctl restart docker
# GPU動作確認コマンド
docker run --rm --gpus all nvidia/cuda:12.1.1-base-ubuntu22.04 nvidia-smi
ステップ2: プロジェクト構成とテンプレートファイル作成
プロジェクトルートに以下の3ファイルを作成します。
docker-compose.yml
version: '3.8'
services:
ai-lab:
build: .
container_name: my-ai-dev-container
runtime: nvidia # NVIDIA GPUを使用する場合。Docker Compose v2.4+では `deploy:` が推奨。
# deploy: # Compose v2.4+ での推奨記法
# resources:
# reservations:
# devices:
# - driver: nvidia
# count: all
# capabilities: [gpu]
ports:
- "8888:8888" # JupyterLab
- "6006:6006" # TensorBoard
volumes:
- ./workspace:/workspace # 開発用ディレクトリ
- ./data:/data # データセット格納用
environment:
- PYTHONPATH=/workspace
- NVIDIA_VISIBLE_DEVICES=all
working_dir: /workspace
tty: true
stdin_open: true
# メモリ制限を設定（必要に応じて）
# mem_limit: 8g
# mem_reservation: 4g
Dockerfile
# ベースイメージ（CUDA+Python）
FROM nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04
# 必要なシステムパッケージのインストール
RUN apt-get update && apt-get install -y
python3.10
python3-pip
git
wget
&& rm -rf /var/lib/apt/lists/*
# シンボリックリンクでpython3をpythonに
RUN ln -s /usr/bin/python3.10 /usr/bin/python
# 作業ディレクトリ作成
WORKDIR /workspace
# Pythonライブラリのインストール
COPY requirements.txt .
RUN pip install --no-cache-dir --upgrade pip &&
pip install --no-cache-dir -r requirements.txt
# JupyterLabの設定（任意）
RUN pip install jupyterlab
EXPOSE 8888
# デフォルトコマンド（コンテナ起動時にbashを実行）
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
# 上記はCUDA 12.1用。CPU版は `--index-url` 行を削除し、`torch`を`torch==2.1.0+cpu`などに。
tensorflow==2.14.0
jupyterlab
matplotlib
scikit-learn
pandas
numpy
opencv-python
# 必要に応じて追加
ステップ3: ビルドと起動、トラブルシューティング
1. ビルド実行:
docker-compose build
ここでERROR: Could not find a version that satisfies the requirement torch==x.x.xのようなエラーが出たら、requirements.txt内のバージョン互換性を確認し、適宜修正します。ネットワークエラーの場合はプロキシ設定を確認。
2. コンテナ起動:
docker-compose up -d
port is already allocatedエラーが出た場合、docker-compose.ymlのports:設定（例: "8899:8888"）を変更するか、ホストで使用中のポートを解放します。
3. 動作確認:
# コンテナ内でbashを実行
docker-compose exec ai-lab bash
# コンテナ内でPythonを起動し、GPUとライブラリを確認
python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"
python -c "import tensorflow as tf; print(tf.__version__); print(tf.config.list_physical_devices('GPU'))"
torch.cuda.is_available()がFalseを返す場合、docker-compose.ymlのruntime: nvidia設定とホストのnvidia-container-toolkitを再確認します。また、docker-compose downしてからdocker-compose up -dし直すと解決することがあります。
4. JupyterLabへの接続:
ブラウザでhttp://localhost:8888にアクセスします。トークンはdocker-compose logs ai-labで表示されるログ内に含まれています。
ステップ4: よくあるエラーへの対処
ボリュームマウントでPermission denied:
コンテナ内のユーザー（多くの場合root）とホストのユーザーでUIDが異なり、ホスト側ファイルの書き込み権限がない場合に発生。解決策は2つあります。
# 方法1: ホスト側ディレクトリの権限を緩和（セキュリティ注意）
sudo chmod -R 777 ./workspace
# 方法2: Dockerfileでホストと同じUID/GIDのユーザーを作成（推奨）
# Dockerfileに以下を追加（1000はホストのUIDに置き換え）
RUN groupadd -g 1000 myuser && useradd -m -u 1000 -g myuser myuser
USER myuser
WORKDIR /workspace
メモリ不足でプロセスがKilled:
Docker Desktopの場合は、設定画面の「Resources」→「Memory」スライダーを増やします（例: 8GB以上）。Linuxの場合は、docker-compose.ymlのmem_limit設定を確認・増加させます。
コード例・コマンド例まとめ
日常的に使用する便利なコマンド集です。
# ビルド（キャッシュを使わず再ビルド）
docker-compose build --no-cache
# 起動
docker-compose up -d
# 停止
docker-compose down
# ログ確認（-fでフォロー）
docker-compose logs -f ai-lab
# コンテナ内でコマンド実行（例: pip install）
docker-compose exec ai-lab pip install transformers
# コンテナ内のシェルに入る
docker-compose exec ai-lab bash
# イメージ・コンテナの一括削除（クリーンアップ）
docker-compose down --rmi all --volumes
docker system prune -a
まとめ・補足情報
Docker Composeを使ったAI開発環境のテンプレート化は、再現性の高い環境構築の強力な手段です。本ガイドで紹介したテンプレートとトラブルシューティング手順により、GPU認識、ビルドエラー、リソース競合といった主要な障壁を乗り越えられるはずです。
さらに発展させるには:
- マルチサービス構成:
docker-compose.ymlにPostgreSQL（データベース）、Redis（キャッシュ）、MLflow（実験管理）などのサービスを追加し、本格的なMLOps環境を構築できます。 - 開発用と本番用の分離:
docker-compose.ymlとdocker-compose.prod.ymlを分け、開発時はソースコードをマウント、本番用は最適化されたビルドイメージを使用するといった使い分けが可能です。 - 環境変数ファイル:
.envファイルを作成し、docker-compose.yml内で${変数名}として参照することで、ポート番号やパスワードなどの設定を外部化できます。
このテンプレートを出発点として、プロジェクト固有のライブラリや設定を追加し、チーム全体で共有できる「誰が使っても同じ環境」を構築してください。これにより、環境構築にかかる時間とストレスを大幅に削減し、本質的なAIモデル開発に集中できるようになります。