WSL2+Docker環境構築手順
はじめに
Web システムの構築において、コンテナ技術(Docker)を用いて開発環境構築や本番環境へのデプロイを行うことは一般的になってきました。
しかし、これまで Windows 環境ではコンテナ技術を動かすうえでのハードルが高く、WindowsOS の上でに仮想マシンを起動してさらにそのうえでコンテナを動かしたり、また、ファイルシステムの差異によるトラブルが多く起きていました。
そのため、Windows 環境での開発は不人気でしたが、WindowsOS 上で Linux をネイティブに近い状態で動かす技術の WSL2 が登場し、かなり高速に Docker を動かせるなど、利便性が向上してきています。
そこで、WindowsOS(Windows10/Windows11)上で、WSL2 を用いて Docker 開発環境を構築する手順をまとめておきます。
仮想化機構の有効化
Windows で「Windows の機能の有効化または無効化」を開きます。
Windows の画面下部検索欄で「Windows の機能」といった形で検索すると出てきますので、
- Linux 用 Windows サブシステム
- 仮想マシンプラットフォーム
にチェックを入れます。
Linux カーネル更新プログラムパッケージをインストールする
Linux カーネル更新プログラムを適用し、カーネルを最新化します。
[ダウンロードサイト]
「x64 マシン用 WSL2 Linux カーネル更新プログラム パッケージ」をダウンロードしてインストールします。
WSL2 を既定のバージョンとして設定する
Windows の 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 をインストールする
以下のサイトからダウンロードが可能です。
- 「Get Started」⇒「Docker Desktop」⇒「Download for Windows」でダウンロードします。
- インストールを開始し、「Install required Windows components for WSL 2」のチェックを入れたまま「OK」で進めます。
- Windows からいったんログアウトするように言われるので、いったんログアウトして再度サインインすると完了です。
Docker の有効化
Docker デスクトップを起動し、「Start」→「Skip tuotrial」→「Settings(歯車アイコン)」と進め「Use the WSL 2 based engine」にチェックが入っていることを確認します。
この状態にすることで、PowerShell からも WSL2 からも Docker が呼び出せるようになります。
docker -v
Docker version 20.10.12, build e91ed57
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 -v
でubuntu20.04
の version が 2 になっていることが確認できる。 - Docker を開き、システム(⚙)→
Resources
→WSL 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 を操作するユーザの権限がないと動かないので、権限を設定します。
sudo usermod -aG docker [ユーザ名]
※ユーザ名には、Ubuntu をインストールしたときの自身のユーザ名を設定します。
補足
docker グループが存在せずエラーとなる場合は、以下コマンドを先に実行してから、ユーザを docker グループに追加してください。
sudo groupadd docker
一度 OS からログアウトして入りなおす
一度 OS(Linux)からログアウトして入りなおすと、設定が有効になります。
su - $USER
以上で設定は終了です。
Dockerfile や docker-compose.yaml ファイルを作成し、docker-compose up
等が使用できる状態になります。
注意事項 1
WSL2 で Docker を動作させた状態で、Docker コンテナ側からファイルを作成すると、ファイルの所有者がroot
になります。
一方で、WSL 上の操作ユーザはデフォルトで root 以外のユーザとなっており、また、VSCode などでファイルを開いた場合も root 以外のユーザとなるため、ファイル更新しようとするとPermission denied
エラーが発生します。
対応としては、VSCode のエクステンションを用いて、WSL2→VSCode 用コンテナ → 対象のフォルダという形で接続して作業を行う必要があります。
以下を参考としていただければと思います。
注意事項 2
WSL2 を起動させたまま長時間使用していると、メモリがひっ迫していくる場合があります。その場合は PC を再起動することをお勧めします。
Discussion