概要

Windows PC上で、WSL2にてDocker環境を整えるための手順を記載します。Dockerの導入は、Docker Desktopのインストールを通じて行います。

ゴールは、VSCodeからWSL2に接続して、Dockerコマンドが通る（= WSL2でDockerを使った開発ができる）ところまで。宗教上の理由からUbuntuのディストリビューションをインストールしますが、Docker Desktopデフォルトのディストリビューションでも動作するので、不要であればそこは読み飛ばしてください。

前提条件

使用するOS、ツール類

WSL2で稼働するLinux OS：Ubuntu 22.04 LTS
Docker：Docker Desktopから有効化するDocker Engine
構築したWindowsのバージョン：23H2（OS ビルド 22631.4249）

WSL2のセットアップ方法は、Windows OSのバージョンによって変わるようです。

普通にWSL2のインストール方法をググるとMicrosoftの「WSL を使用して Windows に Linux をインストールする方法」がヒットしますが、今回構築したPCでは動作しませんでした。さらに、古い手順として残っている以前のバージョンの WSL の手動インストール手順の内容でも動作しなかったので、必要な手順をさらに追加して、最初から最後まで記載します。

WSL2のセットアップ

Windows側の設定を変更する

あらかじめ、Windowsの設定にて仮想環境を使えるよう、設定を変更しておく必要があります。

Windowsの検索に「機能」と入れる→以下の検索結果をクリックします。
コントロールパネルから プログラム > プログラムと機能 > Windowsの機能の有効化または無効化 を選択します。

WSL2を使うために必要な項目を有効化する

設定画面から、Linux 用 Windows サブシステムと仮想マシンプラットフォームにチェックを入れ、OKをクリックします。設定反映のために、PCを再起動します。

Linux カーネル更新プログラムパッケージを実行する

このリンクを踏むと、最新のWSL2向けLinuxカーネルがダウンロードできるので、ダブルクリックで実行します。画面の指示どおりに進んでけば大丈夫。

WSLをインストールする

通常であれば、ここでPowerShellからコマンドを実行すればよいのですが、今回は上手くいきませんでした。エラーの内容と回避策を記載します。

エラー内容：クラスが登録されていません

Windows PowerShellを管理者権限で開き、wsl --installを実行すると、以下のエラーが発生しました。

REGDB_E_CLASSNOTREG　クラスが登録されていません

回避策：GithubからWSL2インストーラを入手、実行

GithubでMicrosoftが公開しているWSLリポジトリから、最新版のインストーラを入手、実行しました。

今回の構築時点では、最新版は2.3.24。名称がwsl.x.x.x.x.x64.msi形式のファイルを選択します。arm64と記載があるものは、Intel CPUではなくARM製CPUが動作するWindows向けなので、該当する端末であればこちらを選べばよさそうです。

ダウンロードしたmsiファイルをダブルクリックして実行、インストールが終わったら、PowerShellを管理者として実行、wsl --statusを実行します。以下のように表示されればOK。

既定のバージョン: 2

Ubuntuをインストールする（必須ではないです）

WSLをインストールした時点では、まだLinux OSの本体（ディストリビューション）が導入されていません。ここでは、今後のコンテナ実行環境に利用するディストリビューションとして、Ubuntuをインストールします。要らん人は飛ばしてください。

Ubuntuの選定理由

後述するDocker Desktopのインストールによって、Docker ディストリビューションがインストールされますが、以下の理由からUbuntuを用いて開発を行うことにしました。

コミュニティサポートが強力（要するに、広く使われている）なので、コマンドやエラー発生時の調査において有利
docker desktopインストール時に入ってくる物は独自のカスタマイズなどされている可能性もあり、ハマったときに情報が無くて困りそうなので避けたい

インストールと初期ユーザー登録

Microsoft Storeアプリを立ち上げてubuntuを検索し、導入したいバージョンを選択します。v24のLTS版が出ていたので、軽率にこれを選びました。

インストールのスピナーが停止し「開始」と表示されたら、これをクリックします。

ターミナルが開いて、新しいユーザー名を入力するよう求められます。とりあえずubuntuで登録しておきました。パスワードを設定して少し待ったら、緑文字のターミナル入力待ちになります。これで、Ubuntuのインストールは完了です。

Docker Desktopをインストールする

インストーラを入手する

公式サイトでDocker Desktopをダウンロードするをクリックして、インストーラを入手します。アカウントの作成はしなくても進められます。

インストーラを実行する

exeファイルをダブルクリックします。

最初の画面は1つ目のrecommendedされているものだけチェックが入っていればよいです。OKをクリックして、インストール処理が実行されるのを待ちます。

インストールが成功したらCloseをクリックしてインストーラを閉じます。

Docker Desktopを起動する

インストールしたDocker DesktopをWindowsのアプリ一覧から起動します。プライバシーポリシー云々で同意画面が出るので、ちゃんと読んでからAcceptをクリックします。

ユーザーの登録画面に遷移します。実は画面右上にskipが見えていますね。この後も2つほど、同様にアンケートっぽい画面が表示されますが、これもSkipできます。ナイショです。

設定値を変更する（Ubuntuを入れた人だけ）

画面上部の歯車マークから設定画面に遷移します。

使用するWSL2ディストリビューションとして、先ほどインストールしたubuntuを選択します。Apply & Restartをクリックして、関連リソースを再起動します。（けど、何も起こらなかったように見えた）

UbuntuがWSL2のデフォルトディストリビューションになっていることを確認する（Ubuntuを入れた人だけ）

Docker Desktopインストールに際して独自のディストリビューションも導入されるので、このタイミングで確認します。管理者として実行したPowershellから、wsl -lを実行します。Ubuntuが既定となっていればOK。

Visual Studio CodeからWSL2とDockerを利用する

拡張機能のRemote Developmentをインストールしておけば、一式使えるはず。

WSL2に接続する

Ctrl + Shift + P でコマンドパレットを開いて、WSLに接続します。WSLと検索をかけるといくつか候補が出てきますが、ここまでの手順でUbuntuがデフォルトのディストリビューションになっているはずなので、シンプルにWSL: Connect to WSLを選んでおいてよいはず。

画面左下部にWSL: ディストリビューション名が表示されたら、WSL2への接続が完了しています。ターミナルを開けば、ubuntuユーザーでログインしてコマンドの入力待ちになるはず。

パッケージの最新化を行う

sudo apt update # パッケージ情報を更新
sudo apt upgrade # パッケージを更新
# 途中でDo you want to contiue? [Y/n]と聞かれたらyを入力

Dockerが利用できるか確認する

以下2つのコマンドをWSL2のターミナル上で実行して、バージョン番号が返って来れば、WSL2とDocker Desktopを用いたコンテナ開発が可能になったと判断できます。

docker -v
# Docker version 27.2.0, build 3ab4256

docker-compose --version
# Docker Compose version v2.29.2-desktop.2

WSL2やGit関連の設定を行う

必要に応じて、適宜以下の設定を行います。

【Docker】Remote-Developmentの構築
【Git】WSL2環境でGitを使う場合のGitHub SSHキー設定
- Windows側のC:\Users\<username>\.sshにGitの秘密鍵や設定ファイルがあるなら、WSL2側の /home/ubuntu/.ssh/（Ubuntuの場合）にファイルをコピーすればそのまま流用できます。この際、コンテナ内でchmod 600 ~/.ssh/id_rsaを実行し、ファイルのパーミッションを変更する必要があります。
【WSL2】Ubuntuディストリビューションのユーザーがsudoできるようにする

ここまでで、すべての手順が完了しました。あとは、コンテナで色々つくってこわして遊んでください！