WSL 2、Docker、Miniconda3による統合開発環境の構築・運用ガイド(Windows上)

【概要】WSL 2 (Windows Subsystem for Linux 2) は、WindowsでLinux実行環境を提供するものである。また、Docker DesktopはWSL 2と連携して動作し、コンテナの管理やイメージの作成を視覚的に行う機能を持つ。Dockerfileは、UbuntuなどのLinuxをベースに環境構築の手順(例: Python環境の構築や開発ツールの導入など)を記述する設定ファイルである。Dockerfileを用いることで、開発環境の構築を容易に行うことができる。

【目次】

  1. 基本アーキテクチャ
  2. 特徴と利点
  3. 事前準備
  4. Docker DesktopのインストールとDockerエンジンの起動
  5. 環境の動作確認
  6. 基本機能の動作確認
  7. Miniconda3を使用したUbuntu開発環境の構築手順と解説
  8. 全般的なトラブルシューティング

【サイト内関連ページ】

1. 基本アーキテクチャ

[Windows OS]
    ↓
[WSL 2 Linuxカーネル]  ← wsl --updateの対象
    ↓
[Docker Desktop]       ←Docker Desktop の WSL 2統合機能を使用
    ↓
[Dockerコンテナ群]     ← Dockerイメージから生成される独立実行環境(例:Ubuntu 24.04 と Miniconda 3 環境を動作)

2. 特徴と利点

Dockerを使用することにより、環境構築をコマンド一つで実行できる。これにより、開発チームの全メンバーが同一の環境で開発することが可能になる。その結果、「特定の環境でのみ動作する」といった問題を回避できる。また、一台のPC上で複数の異なる環境を共存させることも可能である。ただし、Windows固有の機能を利用する開発には、Dockerは適していない場合がある。

コンテナの揮発性という特徴により、コンテナを停止するとコンテナ内での変更は原則として失われる。そのため、永続化が必要な設定や操作はDockerfileに記述し、それを用いて新しいイメージをビルドすることが推奨される。

2.1 環境構築の効率化

2.2 環境の分離

2.3 環境の再現性

2.4 メンテナンス性

3. 事前準備

WSL 2 (Windows Subsystem for Linux 2) が有効化されている必要がある。

WSL 2の有効化の手順は、次のページで説明する。

Windows上のLinux開発環境構築ガイド (WSL 2とUbuntuのインストール・設定・運用): 別ページ »で説明

  1. WSL 2の有効化状態の確認
    • コマンドプロンプトを起動する(例: Windowsキーを押し、「cmd」と入力)。
    • 以下のコマンドを実行する。
    wsl --status
    
  2. WSL 2が使用するLinuxカーネルの更新

    セキュリティパッチの適用や機能改善のため、定期的なアップデートが推奨される。

    wsl --update
    
  3. 仮想化機能の有効化確認
    • タスクマネージャーを開く(Ctrl + Shift + Esc)。
    • 「パフォーマンス」タブで仮想化が有効になっているか確認する。

4. Docker DesktopのインストールとDockerエンジンの起動

Docker Desktopにより、GUIを用いて視覚的にDockerコンテナ、Dockerイメージ、Dockerボリュームの一覧表示、状態確認、基本的な操作を行うことができる。

Docker Desktopは、Windowsのスタートメニューから起動する。Docker Desktopを起動すると、バックグラウンドでDockerエンジンも起動する。

4.1 インストール

Dockerエンジンを構成するDockerデーモンとクライアントを含むDocker Desktopのインストール手順を以下に示す。

インストールは、以下の2つの方法から選択できる。

A. winget (Windows Package Manager) を使用したインストール

  1. Windowsで、コマンドプロンプト管理者権限で起動する(手順: Windowsキーまたはスタートメニューで「cmd」と入力し、右クリックメニューなどから「管理者として実行」を選択)。
  2. winget (Windows Package Manager) が利用可能か確認する。
    winget --version
    
  3. Docker Desktopのインストール
    winget install --scope machine Docker.DockerDesktop
    

B. 手動でのインストール

  1. Docker Desktopのダウンロード
    • 公式サイト(https://docs.docker.com/desktop/features/wsl/#download)にアクセスする。
    • インストーラーをダウンロードする。
  2. インストールの実行
    • ダウンロードしたインストーラーを実行する。
    • 画面の指示に従ってインストールを完了する。

4.2 Dockerエンジンの起動とDocker Desktopの初期設定の確認

  1. Docker Desktopの起動
    • 手動で起動する場合

      Windowsのスタートメニューから起動する。

  2. 自動起動するように設定する場合

    コマンドプロンプト管理者権限で起動し(手順: Windowsキーまたはスタートメニューで「cmd」と入力し、右クリックメニューなどから「管理者として実行」を選択)、次のコマンドを実行する。

    reg add "HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run" /v "Docker Desktop" /t REG_SZ /d "\"C:\Program Files\Docker\Docker\Docker Desktop.exe\"" /f
    
  3. WSL 2の設定確認
    • 画面右上の設定(Settings)ボタンをクリックする。
    • 一般(General)タブを表示する。
    • 「Use WSL 2 based engine」のチェックボックスが有効になっていることを確認する。

5. 環境の動作確認

5.1 WSLの状態確認

インストール済みのLinuxディストリビューションの中に「docker-desktop」があることを確認する。

wsl -l -v

表示例:

  NAME              STATE           VERSION
* Ubuntu-24.04      Running         2
  docker-desktop    Running         2

表示内容の説明:

5.2 Docker Desktopの連携確認

WSL 2とDockerの連携状態を確認する。

docker info | findstr "Operating System"

期待される出力:

Operating System: Docker Desktop

この表示があれば、DockerがWSL 2と正しく連携できていることを示す。

6. 基本機能の動作確認

6.1 コンテナの作成と実行

次のコマンドは、公式リポジトリで提供されているUbuntu 24.04 LTSイメージを基に新しいコンテナを作成し、「cat /etc/os-release」コマンドを実行した後、自動的にコンテナを削除する(--rmオプション)操作である。

docker run --rm ubuntu:24.04 cat /etc/os-release

コマンドの説明:

6.2 基本的なDockerコンテナの操作

6.3 Windows上でUbuntu 24.04コンテナからX11アプリケーションを実行する方法

Docker上のLinuxコンテナからWindowsホスト上のX11サーバーに接続し、GUIアプリケーションを表示する方法を説明する。Docker Desktopの「host.docker.internal」機能とX11転送を組み合わせることで、コンテナの再起動後も継続的に利用可能である。

以下に、Docker上のUbuntu 24.04コンテナを作成後、X11アプリケーションの一例としてxeyesをインストールし、実行する手順を示す。同様の手順で他のX11アプリケーションも実行できる。

前提条件

コンテナの作成とx11-appsアプリケーションのインストール

停止したコンテナの再起動と実行

注意点: DISPLAY環境変数の設定

docker run時にDISPLAY環境変数を設定していない場合は、次のようにdocker execの実行時に指定する。

docker exec -e DISPLAY=host.docker.internal:0.0 ubuntu xeyes

6.4 セキュリティを考慮した発展的なオプション

ユーザー指定による権限制限

docker run -it --user 1000:1000 --name ubuntu ubuntu:24.04 /bin/bash

Linuxケーパビリティの制限

docker run -it --cap-drop=ALL --cap-add=NET_BIND_SERVICE --name webapp ubuntu:24.04 /bin/bash

6.5 ファイル共有機能のテスト

A. 名前付きボリュームの使用(推奨)

コンテナのライフサイクルから独立してデータを永続的に保持するDockerボリュームを作成し、使用する。

  1. データ永続化用のボリュームを作成する。
    docker volume create app-data
    

    コマンドの説明:

    • Dockerにおけるデータ永続化のための機能である。
    • このコマンドは新規ボリュームを作成する。
    • ボリュームはホストマシンの/var/lib/docker/volumes/配下に作成される。
    • コンテナを削除した場合でも、ボリューム内のデータは保持される。
  2. ボリュームを使用したコンテナの実行
    docker run --rm -v app-data:/data ubuntu:24.04 ls -al /data
    

    ボリュームは新規作成直後は空である。

    • -v app-data:/data: 作成したボリュームをコンテナの/dataディレクトリにマウントする。
    • このボリュームは他のコンテナでも再利用可能である。

B. ローカルディレクトリのマウント

Windows側のファイルを直接共有する方法を説明する。

mkdir data2
docker run --rm -v %cd%/windows-file:/data2 ubuntu:24.04 ls -al /data2

7. Miniconda3を使用したUbuntu開発環境の構築手順と解説

1. Dockerfileの作成

  1. コマンドプロンプトを起動する(例: Windowsキーを押し、「cmd」と入力)。
  2. 以下のコマンドを実行する。
  3. notepad Dockerfile
    
  4. Dockerfileを次のように作成して保存する。

    次のDockerfileは、Ubuntu 24.04 LTS (Long Term Support) イメージをベースとし、Python開発環境を構築するものである。Miniconda3を用いてPython 3.12環境を作成し、NumPyやPandasといった科学技術計算ライブラリを導入する。さらに、Jupyter Notebookをポート8888で起動するよう設定し、開発用の基本ツールとしてcmakeやgitなどもインストールする。

    FROM ubuntu:24.04
    
    # 環境変数の設定
    ENV PATH=/opt/conda/bin:$PATH \
        SHELL=/bin/bash \
        DEBIAN_FRONTEND=noninteractive \
        TZ=Asia/Tokyo
    
    # システムパッケージのインストール
    RUN apt-get update && apt-get upgrade -y && \
        apt-get install -y python3 python3-pip python3-dev wget curl git cmake gnupg software-properties-common build-essential
    
    # Miniconda3のインストール
    RUN wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh && \
        bash Miniconda3-latest-Linux-x86_64.sh -b -p /opt/conda && \
        rm Miniconda3-latest-Linux-x86_64.sh
    
    # condaの初期設定とdev環境の作成
    RUN /opt/conda/bin/conda init bash && \
        echo ". /opt/conda/etc/profile.d/conda.sh" >> /root/.bashrc
    
    RUN /opt/conda/bin/conda create -n dev python=3.12 -y && \
        /opt/conda/bin/conda install -n dev -y numpy pandas matplotlib scikit-learn jupyter pylint pytest black && \
        echo "conda activate dev" >> /root/.bashrc
    
    # Jupyterの設定
    RUN mkdir -p /root/.jupyter && \
        /opt/conda/envs/dev/bin/jupyter notebook --generate-config && \
        echo "c.NotebookApp.ip = '*'" >> /root/.jupyter/jupyter_notebook_config.py && \
        echo "c.NotebookApp.port = 8888" >> /root/.jupyter/jupyter_notebook_config.py && \
        echo "c.NotebookApp.allow_root = True" >> /root/.jupyter/jupyter_notebook_config.py
    
    # 作業ディレクトリの設定
    WORKDIR /workspace
    
    # Jupyterのポートを公開
    EXPOSE 8888
    
    # コンテナ起動時のコマンド
    CMD ["bash", "-c", ". /opt/conda/etc/profile.d/conda.sh && conda activate dev && \
         /opt/conda/envs/dev/bin/jupyter notebook --allow-root --ip=* --port=8888 --no-browser"]
    
  5. Dockerfileを基にイメージをビルドする。

2. Dockerイメージのビルド(Dockerfileからのイメージ作成)

コマンドプロンプトで、次の「docker build」コマンドを実行する。このコマンドは、カレントディレクトリのDockerfileを基にイメージを生成する。作成したイメージには、識別用の名前(例: myubuntu2404)とバージョン管理用のタグ(例: 1.0)を設定できる。

その後、「docker images」コマンドにより、ローカルに保存されたすべてのイメージを一覧形式で確認できる。

docker build -t myubuntu2404:1.0 .
docker images

3. 作成されたイメージからのコンテナの作成と実行

コマンドプロンプトで、次のコマンドを実行する。

docker run --name myubuntu -p 8888:8888 -it myubuntu2404:1.0 /bin/bash

次の実行画面では、Linuxコマンドのpwd、lsを実行した後、「exit」で切断している。

各オプションの説明:

4. 環境の確認

5. Docker運用上の注意点

6. Miniconda3の説明

Miniconda3は、Pythonとconda(パッケージ管理システム)を含む、軽量なAnacondaディストリビューションである。

Miniconda3の概要と機能

condaを使用してパッケージをインストールできる。condaは、パッケージの依存関係を自動的に解決し、互換性のあるバージョンをインストールする。また、独立した仮想環境を作成できる。WindowsやLinuxなど、複数のオペレーティングシステムに対応している。Miniconda3は、Pythonの複数バージョンを管理し、共存させることもできる。

Miniconda3とpipの併用

Miniconda3とpipを同一環境で使用する際には注意が必要である。基本的にはどちらか一方を使用することが推奨されるが、特定のパッケージがcondaで利用できない場合にpipを使用する必要がある。その際は、依存関係の競合を避けるため、新しいconda環境を作成し、その環境内でpipを使用することが強く推奨される。これにより、他の環境への影響を防ぐことができる。`--upgrade-strategy`は、依存関係が必要な場合にのみ、関連するパッケージをアップグレードするオプションである。

conda create -n myenv python=
conda activate myenv
pip install --upgrade-strategy only-if-needed 

Miniconda3環境設定のバックアップと再現

# 現在の環境設定をエクスポート
conda env export > environment.yml

# エクスポートした環境の内容確認
cat environment.yml

# 他の環境での環境を再現
conda env create -f environment.yml

Miniconda3のトラブルシューティング

環境の作成やアクティベートに問題がある場合、既存の環境を削除して新しい環境を作成することが有効な場合がある。以下のコマンドを使用する。ただし、必要なデータは事前に保存する必要がある。

conda remove --name  --all
conda create --name  python=
conda activate 

8. 全般的なトラブルシューティング

8.1 wingetでのインストールの問題

  1. wingetの更新
    winget upgrade
    
  2. キャッシュのクリア
    winget source reset
    
  3. よくある問題と対処
    • 「プログラムが見つかりません」エラー:
      winget source update
      
      でパッケージリストを更新する。
    • インストールが途中で止まる場合:
      • 管理者権限でコマンドプロンプトを開いて実行する。
      • または手動インストールに切り替える。

8.2 コンテナ、イメージ、ボリュームの完全な破棄

注意: 以下の操作を実行すると、実行中のものを含むすべてのコンテナ、イメージ、ボリュームが完全に削除される。この操作は元に戻すことができないため、重要なデータは事前にバックアップする必要がある。

  1. すべての実行中コンテナを停止して削除:

    for /f "tokens=*" %i in ('docker ps -a -q') do docker stop %i
    for /f "tokens=*" %i in ('docker ps -a -q') do docker rm %i
    
  2. すべてのイメージを強制削除:

    for /f "tokens=*" %i in ('docker images -a -q') do docker rmi -f %i
    
  3. 未使用のリソースの一括削除:

    docker system prune -a --volumes
    
    • -a オプションは未使用イメージも含めて削除する。

    • --volumes オプションは未使用ボリュームも削除する。

  4. Docker Desktopの再起動:

    • タスクトレイのDockerアイコンを右クリックし、「Restart」を選択する。

  5. Docker設定の完全リセット(より根本的な問題の場合):

    • Docker Desktopを終了する。

    • タスクトレイのDockerアイコンを右クリックし、「Troubleshoot」から「Clean / Purge data」を選択する。

    • 「Reset to factory defaults」オプションを選択する。