0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Windows を使った開発関係の環境準備などのメモ

0
Last updated at Posted at 2026-02-24
  • [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. 運用ルール(テンプレ)

  1. Windows Terminal の既定 Shell は WSL2
  2. Docker 操作は WSL からのみ行う
  3. プロジェクトは WSL2 側に clone
  4. 起動は docker compose を唯一の入口にする
  5. 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 に貼り付けて使用可能)

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?