- [todo : clinkなどの旧来の拡張機能との調整中]
Windows + WSL2 + Docker 設計まとめ
1. 目的
Windows Terminal 上で WSL2 (Ubuntu) を日常の Shell として使い、Docker コンテナを 透過的に操作 するための設計・運用指針をまとめる。
2. 全体像(推奨アーキテクチャ)
Windows Terminal
├─ PowerShell (Windows操作)
└─ WSL2 / Ubuntu ← メインShell
└─ docker / docker compose
└─ Docker Desktop (WSL2 backend)
└─ Linux containers
- 人が触る Shell : WSL2
- 環境再現・実行 : Docker コンテナ
3. なぜ WSL2 をメイン Shell にするのか
- Windows ⇄ Linux のファイル・コマンド連携が公式サポート
-
explorer.exe .やcode .が自然に使える - コンテナは「実行環境」に専念させられる
4. Docker 利用パターン
パターンA(推奨): Docker Desktop + WSL 統合
- Docker Engine : Docker Desktop
- 操作 : WSL2 Ubuntu から
docker/docker compose - 特徴 :
- セットアップが簡単
- GUI 管理も可能
- WSL との統合が公式
パターンB: WSL2 に Docker Engine 直インストール
- Docker Desktop 不要
- 軽量・ライセンス考慮向け
- Windows との統合は弱くなる
※ Docker Desktop と WSL 内 Docker Engine の 併用は非推奨
5. ディレクトリ設計(重要)
推奨
/home/username/work/project
- プロジェクトは WSL2 の Linux ファイルシステム に置く
-
/mnt/c配下は避ける
理由:
- ファイル I/O が高速
- パーミッション問題が起きにくい
- inotify / fswatch が安定
6. docker compose 前提の基本構成
ディレクトリ例
project/
├─ compose.yaml
├─ .env
├─ docker/
│ └─ app.Dockerfile
└─ src/
compose.yaml 例
services:
app:
build:
context: .
dockerfile: docker/app.Dockerfile
volumes:
- .:/workspace
working_dir: /workspace
tty: true
ports:
- "8080:8080"
基本操作(WSL Shell)
docker compose up -d --build
docker compose logs -f
docker compose exec app bash
docker compose down
7. VS Code 連携設計
パターン1: Remote - WSL
- VS Code は WSL に接続
- 編集は WSL
- 実行は Docker
パターン2: Dev Containers
- 必要な時だけコンテナに attach
- IDE も完全にコンテナ側
8. 運用ルール(テンプレ)
- Windows Terminal の既定 Shell は WSL2
- Docker 操作は WSL からのみ行う
- プロジェクトは WSL2 側に clone
- 起動は docker compose を唯一の入口にする
- VS Code は Remote-WSL / Dev Containers を標準
9. よくある落とし穴
- docker コマンドが見つからない → WSL Integration / PATH を確認
- GPU 設定入り compose を CPU 環境で実行 → compose 分離
- WSL / Docker Desktop のバージョンが古い → 更新
10. まとめ
- WSL2 = 人が操作する作業環境
- Docker = 再現性のある実行環境
- この役割分離が Windows + Linux + Container を最も快適にする
参考::導入手順チェックリスト
WSL2 + Docker 透過利用
✅ チェックリスト形式 導入手順書
フェーズ0:事前確認(Windows 側)
- Windows 10 (22H2) 以降 / Windows 11 である
- BIOS/UEFI で仮想化(Intel VT-x / AMD-V)が有効
- Windows Update が最新
フェーズ1:WSL2 の導入
1-1. WSL2 インストール
-
管理者 PowerShell で以下を実行
wsl --install - 再起動後、Ubuntu が起動できる
- ユーザー名・パスワードを設定済み
1-2. WSL2 であることを確認
-
PowerShell で以下を実行
wsl -l -v -
VERSION が
2になっている
フェーズ2:Docker Desktop の導入
2-1. Docker Desktop インストール
- Docker Desktop for Windows をインストール
- インストール時に Use WSL 2 based engine が有効
2-2. WSL 統合を有効化
-
Docker Desktop → Settings → General
- Use WSL 2 based engine ON
-
Docker Desktop → Settings → Resources → WSL Integration
- 使用する Ubuntu にチェック
- Apply & Restart を実行
フェーズ3:WSL から Docker を使えるか確認
3-1. docker コマンド確認(WSL)
-
Ubuntu ターミナルで以下を実行
docker --version - バージョンが表示される
3-2. テストコンテナ起動
-
以下を実行
docker run --rm hello-world - "Hello from Docker!" が表示される
フェーズ4:ディレクトリ設計(重要)
4-1. 作業ディレクトリ
- プロジェクトは WSL 側 に配置
/home/<user>/work/<project>
-
/mnt/c/...配下にコードを置いていない
フェーズ5:docker compose 標準化
5-1. compose ファイル配置
-
プロジェクト直下に
compose.yaml -
volume マウントは相対パス(
.)を使用
5-2. 基本操作が WSL からできる
-
起動
docker compose up -d --build -
ログ確認
docker compose logs -f -
シェル接続
docker compose exec app bash -
停止
docker compose down
フェーズ6:VS Code 連携(推奨)
パターンA:Remote - WSL
- VS Code に WSL 拡張 をインストール
-
WSL ターミナルで
code .が使える
パターンB:Dev Containers
- VS Code に Dev Containers 拡張 をインストール
- Running Container に attach できる
フェーズ7:運用ルール確認(チーム向け)
- 普段の Shell は WSL2
- Docker 操作は WSL からのみ
-
手動
docker runを避け、compose を入口に - Windows 側 PowerShell での docker 使用は禁止
トラブルシュート早見
-
docker: command not found- → Docker Desktop の WSL Integration を再確認
-
起動が遅い / 不安定
- → プロジェクトが
/mnt/c配下でないか確認
- → プロジェクトが
-
GPU エラー
- → GPU 用 compose と CPU 用 compose を分離
✅ 完了条件
- WSL2 Shell から Docker を意識せず操作できる
- Windows / Linux / コンテナの役割が分離されている
(このチェックリストはそのまま README / 社内 Wiki に貼り付けて使用可能)