🤖

WSL2+Docker環境構築手順

2022/02/05に公開

はじめに

Web システムの構築において、コンテナ技術(Docker)を用いて開発環境構築や本番環境へのデプロイを行うことは一般的になってきました。
しかし、これまで Windows 環境ではコンテナ技術を動かすうえでのハードルが高く、WindowsOS の上でに仮想マシンを起動してさらにそのうえでコンテナを動かしたり、また、ファイルシステムの差異によるトラブルが多く起きていました。
そのため、Windows 環境での開発は不人気でしたが、WindowsOS 上で Linux をネイティブに近い状態で動かす技術の WSL2 が登場し、かなり高速に Docker を動かせるなど、利便性が向上してきています。
そこで、WindowsOS(Windows10/Windows11)上で、WSL2 を用いて Docker 開発環境を構築する手順をまとめておきます。

仮想化機構の有効化

Windows で「Windows の機能の有効化または無効化」を開きます。
Windows の画面下部検索欄で「Windows の機能」といった形で検索すると出てきますので、

  • Linux 用 Windows サブシステム
  • 仮想マシンプラットフォーム

にチェックを入れます。


Linux カーネル更新プログラムパッケージをインストールする

Linux カーネル更新プログラムを適用し、カーネルを最新化します。

[ダウンロードサイト]
https://docs.microsoft.com/ja-jp/windows/wsl/install-manual#step-4---download-the-linux-kernel-update-package

「x64 マシン用 WSL2 Linux カーネル更新プログラム パッケージ」をダウンロードしてインストールします。

WSL2 を既定のバージョンとして設定する

Windows の PowerShell を起動し、次のコマンドを実行します。

powershell
wsl --set-default-version 2
WSL 2 との主な違いについては、https://aka.ms/wsl2 を参照してください
この操作を正しく終了しました。

と表示されれば、OK です。
※表示されない場合、--set-default-version コマンドが存在しないと言われてしまう場合、「Windows の機能の有効化または無効化」から「Hyper-V」を有効にしてみてください。

Microsoft Store から最新の Ubuntu をインストールする

Microsoft Store で「Ubuntu」で検索し「Ubuntu 20.04 LTS」を選択しインストールします。
Windows の画面下部検索欄で「Store」といった形で検索すると出てきます。

Installing, this may take a few minutes...
WslRegisterDistribution failed with error: 0x800701bc
Error: 0x800701bc WSL 2 ???????????? ??????????????????????? https://aka.ms/wsl2kernel ?????????

Ubuntu を起動しユーザーとパスワードを作成する

画面指示に従って任意のユーザ名とパスワードを設定します。

Ubuntu ディレクトリをネットワークドライブに割り当てておく

WSL2 は\\wsl$というディレクトリパスでアクセスすることができます。(Windows のエクスプローラで開いてみてください)
必須の手順ではありませんが、WSL2 のディレクトリにドライブレター(Z:など)を割り当てておくと、後で便利です。

\\wsl$ディレクトリを開くとUbuntu-20.04というディレクトリが見えるので、右クリックして「ネットワークドライブの割り当て」から割り当てを設定します。

メモリの割り当てを実施する

デフォルトのままだと、メモリを際限なく使用してしまうため、メモリ使用量の設定を行います。
下記の位置に.wslconfigファイルを配置します。(デフォルトでは存在しないので新規に配置します)

C:\Users\[ユーザ名]\.wslconfig

下記のように、メモリと CPU プロセッサの使用量を設定します。

[wsl2]
memory=3GB
processors=2

※2GB だと足りなくなる場合が多くなるようですので、3GB 程度で設定しています。

Docker をインストールする

以下のサイトからダウンロードが可能です。
https://www.docker.com/

  1. 「Get Started」⇒「Docker Desktop」⇒「Download for Windows」でダウンロードします。
  2. インストールを開始し、「Install required Windows components for WSL 2」のチェックを入れたまま「OK」で進めます。
  3. Windows からいったんログアウトするように言われるので、いったんログアウトして再度サインインすると完了です。

Docker の有効化

Docker デスクトップを起動し、「Start」→「Skip tuotrial」→「Settings(歯車アイコン)」と進め「Use the WSL 2 based engine」にチェックが入っていることを確認します。

この状態にすることで、PowerShell からも WSL2 からも Docker が呼び出せるようになります。

powershell
docker -v
実行結果
Docker version 20.10.12, build e91ed57
WSL2(Ubuntu)
docker -v
実行結果
Docker version 20.10.12, build e91ed57

※Windows の権限docker-usersグループに操作ユーザを設定する必要がある場合があるようです。
 下記手順で解消したという報告があります。

  • コンピュータ管理を管理者権限で実行 →ローカルユーザとグループグループdocker-usersをダブルクリック
    追加 →NT AUTHORITY\Authenticated usersを追加する。再起動で docker が開けるようになる。
  • windows powershell を開く(管理者権限でなく普通に開く)。
  • wsl -l -vで ubuntu20.04 が追加されていることを確認。(追加されていない場合はwsl --install -d Ubuntu-20.04を実行。)
  • wsl --set-version Ubuntu-20.04 2を実行。
  • wsl -l -vubuntu20.04の version が 2 になっていることが確認できる。
  • Docker を開き、システム(⚙)→ResourcesWSL INTEGRATION Ubuntu-20.04を ON にする。

WSL2 で Docker を使う場合の注意点

  • /mnt/配下など Windows 側のファイルシステムにいるファイルをマウントすると非常に遅くなります。
  • Linux(WSL2)側の/home/にファイルを置いて、直接編集すると速くなります。

\\wsl\home\[ユーザ名]\sampleのようなフォルダにアクセスする場合、
ドライブレターを割り当てると、Windows 側からは下記のようにアクセスできます。

Z:\home\[ユーザ名]\sample

Linux 側から見ると、以下のパスが同じファイルを参照しています。

/home/[ユーザ名]/sample

docker グループに自身のユーザを追加(権限の付与)

docker グループに対して、OS を操作するユーザの権限がないと動かないので、権限を設定します。

WSL2(Ubuntu)
sudo usermod -aG docker [ユーザ名]

※ユーザ名には、Ubuntu をインストールしたときの自身のユーザ名を設定します。

補足

docker グループが存在せずエラーとなる場合は、以下コマンドを先に実行してから、ユーザを docker グループに追加してください。

WSL2(Ubuntu)
sudo groupadd docker

一度 OS からログアウトして入りなおす

一度 OS(Linux)からログアウトして入りなおすと、設定が有効になります。

WSL2(Ubuntu)
su - $USER

以上で設定は終了です。
Dockerfile や docker-compose.yaml ファイルを作成し、docker-compose up等が使用できる状態になります。

注意事項 1

WSL2 で Docker を動作させた状態で、Docker コンテナ側からファイルを作成すると、ファイルの所有者がrootになります。
一方で、WSL 上の操作ユーザはデフォルトで root 以外のユーザとなっており、また、VSCode などでファイルを開いた場合も root 以外のユーザとなるため、ファイル更新しようとするとPermission deniedエラーが発生します。
対応としては、VSCode のエクステンションを用いて、WSL2→VSCode 用コンテナ → 対象のフォルダという形で接続して作業を行う必要があります。
以下を参考としていただければと思います。
https://zenn.dev/ttani/articles/wsl2-docker-edit-root-user

注意事項 2

WSL2 を起動させたまま長時間使用していると、メモリがひっ迫していくる場合があります。その場合は PC を再起動することをお勧めします。

株式会社トッカシステムズ

Discussion