WSL2・Docker セットアップ詳細（Windows 向け）

このページは、Windows 受講生向けに WSL2 と Docker のセットアップ手順を詳細に解説するものです。環境構築クイックスタート（macOS / Windows） で詰まった場合や、Docker Desktop / WSL ネイティブ Docker の選択・トラブル対処の詳細を確認したいときに参照してください。macOS 利用者はこのページを読む必要はありません。

開発作業は原則として WSL2 上の Ubuntu ターミナルで行います。PowerShell やコマンドプロンプトは WSL の管理用コマンドを実行するときにだけ使う、という役割分担を最初に押さえておきましょう。

WSL2 のインストール

1. Windows ターミナルを開く

スタートメニューで「ターミナル」を検索して起動します。規定ではコマンドプロンプトまたは PowerShell のタブが開きますが、どちらでも構いません（以降の wsl コマンドは両方で動作します）。

2. wsl --install を実行する

wsl --install

これだけで WSL2 本体と既定ディストリである Ubuntu が同時にインストールされます。完了後、PC を再起動する必要がある場合があります。

3. 既定ディストリが Ubuntu になっているか確認する

再起動後、再びターミナルを開いてコマンドプロンプトのタブで以下を実行します。

wsl -l

出力例:

Linux 用 Windows サブシステム ディストリビューション:
Ubuntu-24.04 (既定値)
docker-desktop

Ubuntu-24.04 (既定値) と表示されていれば問題ありません。Ubuntu が既定値になっていない場合は、次のコマンドで既定に設定します。

wsl -s Ubuntu-24.04

この操作を正しく終了しました と表示されたら、もう一度 wsl -l で既定値が切り替わっていることを確認してください。

4. 初回起動でユーザー名・パスワードを設定する

Ubuntu を初めて起動するとユーザー名とパスワードの入力を求められます。どちらも後続の作業で sudo を使うたびに必要になるため、パスワードは必ずメモに残しておいてください。Windows アカウントのパスワードとは別物で、Ubuntu 内だけで通用する資格情報です。

入力タイミングは Windows / WSL のバージョンによって異なります。wsl --install 直後に聞かれる場合もあれば、ディストリの初回起動時に聞かれる場合もあります。

5. Windows Terminal のデフォルトを Ubuntu に切り替える

Windows Terminal のタブ横にある ∨ を押し、設定画面を開きます。既定のプロファイル を Ubuntu に変更すると、以降はターミナルを起動するだけで WSL が立ち上がる状態になります。

WSL のパスワード再設定方法

Ubuntu のパスワードを忘れると sudo が打てず、パッケージインストールもできなくなります。次の手順で root 経由で再設定します。

1. コマンドプロンプトから root でログインする

Windows 側のコマンドプロンプト（または PowerShell）で以下を実行します。

wsl -u root

プロンプトが root@ホスト名:~# のような形に変われば root でログインできています。

2. 対象ユーザー名を確認する

まず root ログイン中にユーザー名が分からない場合は、別タブで Ubuntu を普通に開き、次を実行します。

whoami

出力された文字列がパスワードを再設定するユーザーの名前です。

3. passwd で再設定する

root シェルに戻り、ユーザー名を指定して新しいパスワードを入力します。

passwd <ユーザー名>

New password: と Retype new password: を入力すれば完了です。以降は通常ユーザーに戻って sudo が使えることを確認してください。

Docker のインストール：2 つの選択肢

Windows で Docker を使う方法は大きく 2 通りあります。

最初は Docker Desktop で始め、動作が重いと感じたら WSL ネイティブへ切り替える方針で問題ありません。

Docker Desktop を使う場合

1. インストーラーを取得する

Docker Desktop for Windows にアクセスし、Docker Desktop for Windows - x86_64 をダウンロードします。RUNTEQ カリキュラムでは Arm アーキテクチャの Windows PC は非推奨のため、x86_64 版を選んでください。

2. インストーラーを起動する

ダウンロードしたファイルをダブルクリックし、インストーラーの指示にそのまま従います。完了後 Close and restart をクリックして PC を再起動します。

3. WSL 統合を有効化する

再起動後、Docker Desktop を起動します。右上の歯車アイコンから設定画面を開き、以下を有効化します。

1. Resources → WSL Integration → Enable integration with my default WSL distro
2. 同画面の Enable integration with additional distros で Ubuntu のトグルを ON
3. Apply & restart で設定を保存

4. Ubuntu 側で動作確認する

Ubuntu ターミナルで次を実行します。

docker -v

Docker version 27.x.x, build ... のようにバージョンが表示されれば、WSL から Docker Desktop のデーモンへアクセスできています。バージョンが出ず command not found や接続エラーになる場合は、Docker Desktop 本体が起動しているか・WSL Integration で Ubuntu が ON になっているかを見直してください。

Docker Desktop を使わない場合（WSL ネイティブ Docker）

Docker Desktop をインストール済みでこの方式に切り替える場合は、先に Docker Desktop を停止します。以下はすべて Ubuntu ターミナルで実行してください。

1. 古いパッケージを削除する

sudo apt-get remove docker docker-engine docker.io containerd runc

2. リポジトリ取得に必要なパッケージを入れる

sudo apt-get update
sudo apt-get -y install ca-certificates curl gnupg lsb-release

3. GPG キーを追加する

公式キーを取り込むことで、後続の apt リポジトリが正当かどうかを検証できるようになります。

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

4. Docker 用 apt リポジトリを設定する

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

5. Docker 本体をインストールする

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose

6. Docker デーモンを起動する

WSL の Ubuntu は systemd が標準で有効でない構成もあり得るため、service コマンドでデーモンを起こすのが確実です。

sudo service docker start

Ubuntu を再起動（wsl --shutdown → 再ログイン）するたびに再度実行が必要になる点に注意してください。常駐させたい場合は /etc/wsl.conf に [boot] systemd=true を追記して systemd を有効化する方法もあります。

7. 動作確認（docker-compose）

カリキュラムで docker compose up が登場する場面ではあえて docker-compose（ハイフン区切り） を使います。Docker CE と同時に入れた docker-compose パッケージが独立バイナリとして動くためです。

docker-compose up

8. docker-credential-desktop.exe エラーへの対処

以下のようなエラーが出る場合、以前インストールした Docker Desktop の資格情報ヘルパー設定が残っています。

"docker-credential-desktop.exe": executable file not found in $PATH, out: ``

~/.docker/config.json を開き、credsStore を credStore に変更して保存すれば解消します。

{
  "credStore": "desktop.exe"
}

Docker 生成ファイルで Permission Denied が出るとき

Rails などを Docker コンテナ内で動かしているとき、bin/rails generate model User のようにコンテナ側でファイルを生成すると、ホストの VSCode で編集できなくなる（Permission Denied）ことがあります。

対処はシンプルで、プロジェクトルートで次を実行し、所有者を自分に戻します。

sudo chown -R $USER:$USER .

毎回のファイル生成後に実行する運用になりますが、WSL2 環境では避けにくい作業コストと割り切ってください。

なぜ WSL2 ではファイル権限の問題が起きやすいのか

卒業までに細部まで理解する必要はありませんが、原因を一度押さえておくと納得感が違います。

• ユーザー識別子の違い: Linux は UID/GID で、Windows は SID でユーザーを表現します。WSL2 は両者を橋渡しする必要があり、境界でズレが生じやすいです。
• ファイルシステムのエミュレーション: WSL2 は Windows のディスク上に Linux のファイルシステムをエミュレートしています。所有権やパーミッションのメタデータが完全には一致せず、コンテナとホストの往復で不整合が発生します。
• macOS は Unix 系: macOS のファイルシステムはもともと Unix 系で UID/GID をそのまま扱います。Docker コンテナとホスト間で権限が揃いやすいため、同種の問題は顕在化しにくいです。

Windows で開発する以上、ファイル生成後の chown はセットで覚えておいてください。

参考リソース

• WSL インストールガイド（Microsoft 公式）: https://learn.microsoft.com/ja-jp/windows/wsl/install
• Docker Desktop for Windows: https://docs.docker.com/desktop/install/windows-install/
• Docker CE on Ubuntu: https://docs.docker.com/engine/install/ubuntu/
• WSL 上で systemd を有効化する: https://learn.microsoft.com/ja-jp/windows/wsl/systemd

確認クイズ

この章で手を動かすときの確認

この章は 導入編にある 「手を動かす」 の章です。本文を読み終えたあと、次の観点だけ確認すると次へ進みやすくなります。

この章で確認すること:

• Windows 上で WSL2 と Docker を使えるようにする
• Docker 導入時の典型的な詰まりどころを把握する

次に活きる章:

• AWSインフラ基礎
• PostgreSQL に保存する

補助参照:

• カリキュラム全体の完成条件（checklist.yml）
• 参照実装の README