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では動くのに」というトラブルがなくなる． 異なる環境を１台のPCで共存することもできる． ただし，Windows固有の機能を使う開発では，Dockerは適していない．

コンテナの特徴として，コンテナを停止すると，操作結果がすべてなくなることにある．よく使う設定は操作は Docker file に記載し，Docker file を使って新しいイメージをビルドする．

2.1 環境構築

2.2 環境の分離

2.3 環境の再現性

2.4 メンテナンス性

3．前準備

WSL 2（Windows Subsystem for Linux 2：WindowsでLinuxを実行するためのシステム）が有効化されていること．

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により，画面を用いてビジュアルに，Dockerコンテナ， Dockerイメージ，Dockerボリュームの一覧表示，状態確認，基本的な操作を行うことができる．

Docker Desktopの起動は，Windowsのスタートメニューから起動できる．Docker デスクトップを起動することにより，Docker エンジンが起動する

4.1 インストール

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

インストールは，以下の2つの方法から選択可能である．

A）winget（Windowsパッケージマネージャー）を使用したインストール

  1. Windowsで，コマンドプロンプトを管理者権限で起動する（例：Windowsキーを押し，「cmd」と入力し，「管理者として実行」を選択）
  2. winget（Windowsパッケージマネージャー）が利用可能か確認する： 
    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上の Ubunut24.04 コンテナを作成ののち，xeyesアプリケーション（X11アプリケーションの１つ）をインストールし実行する手順である．同様の手順で他の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
  3. Dockerfile を次のように作成して保存する

    次のDockerfileは，Ubuntu 24.04 LTS（Long Term Support：長期サポート版）のイメージを取得し，Python環境を構築している．Miniconda3を用いてPython 3.12環境を作成し，NumPy，Pandas等の科学技術計算ライブラリを導入している．Jupyter NotebookをPort 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"]
  4. 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. Miniconda 3 の説明

Miniconda3は，Pythonとconda（パッケージ管理システム）を含むシステムである．

Minicodna 3 の概要と機能

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

Miniconda3とpipの併用

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

conda create -n myenv python=<version>
conda activate myenv
pip install --upgrade-strategy only-if-needed <package_name>

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

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

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

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

トラブルシューティング

環境の作成やアクティベートに失敗する場合：

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

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」オプションを選択する