Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

WSL・Debian・Docker Engine構築ガイド アウトライン

本ドキュメントは、WindowsのWSL2（Windows Subsystem for Linux 2）環境にLinuxディストリビューション「Debian」を導入し、その上でコンテナ仮想化技術である「Docker Engine」を直接インストールして運用するための構築ガイドです。

本書は「入門編」と「実施編」の2つのレベルに分かれています。

入門編

1. はじめに

  • 本書の目的と対象読者
  • WSL2・Debian・Docker Engineを組み合わせるメリット

2. WSL2とDebianのセットアップ

  • WSL2の有効化と最新化
  • Debianのインストール
  • Debianの初期設定

実施編

3. Docker Engineのインストール

  • 古いパッケージのクリーンアップ
  • Docker公式リポジトリの登録
  • Docker Engineのインストールと動作検証
  • 非ルートユーザーでのDockerの実行許可

4. WSL2上でのDocker運用とトラブルシューティング

  • systemdを用いたDocker自動起動の設定
  • ネットワークとファイルアクセスの最適化
  • よくあるトラブルと解決策

第1章 はじめに

1.1 本書の目的と対象読者

本書は、Windows 10またはWindows 11のパソコン上で、Linuxの環境を手軽に作り、そこでDockerを使ってアプリ開発をしたいと考えている初心者を対象としています。WSL2やLinux（Debian）の基本的なコマンド操作が初めての方でも、記述された手順通りに進めるだけで、安全かつ確実に開発環境を構築できるように解説します。

Windows上でDockerを動かす方法としては「Docker Desktop」というソフトウェアを導入する方法が有名ですが、会社の規模によってはライセンスが有料になる場合があります。本書では、規約の制限なく完全無料で使えるようにするため、WSL2内のDebianに直接「Docker Engine（オープンソース版）」をインストールして運用する方法を選択します。

1.2 WSL2・Debian・Docker Engineを組み合わせるメリット

WSL2（Windows Subsystem for Linux 2）を使用することで、Windowsのシステムの中で本物のLinuxカーネルを動かすことができます。これにより、パソコンの動作を重くすることなく、非常に高速かつ軽量にLinuxのソフトウェアを動かすことが可能になります。

Debianは、Linuxディストリビューションの中でも歴史が古く、動作の安定性に優れているのが特徴です。余計なプログラムが初期状態ではインストールされていないため、システム全体を軽く保つことができます。

このDebian環境にDocker Engineを直接インストールすることで、仮想マシンを別で起動するような無駄な処理を挟まずに、Linux本来の処理スピードでコンテナを動かすことができます。これにより、本番環境のサーバーとほぼ同じ構成を自分のパソコン内に素早く構築し、開発やテストを快適に進められるようになります。

第2章 WSL2とDebianのセットアップ

2.1 WSL2の有効化と最新化

WSL2を利用するためには、まずWindowsにWSL機能をインストールする必要があります。Windowsの「スタートボタン」を右クリックし、「ターミナル（管理者）」または「PowerShell（管理者）」を開いて、以下のコマンドを実行します。

# WSL機能を自動で有効化し、必要なファイルをインストールします
wsl --install

コマンドの実行が完了したら、システムを有効にするためにWindowsパソコンを一度再起動してください。すでにWSLを導入している場合は、以下のコマンドを実行してWSLを最新版に更新しておきます。

# WSLを最新の状態にアップデートします
wsl --update

2.2 Debianのインストール

WSL2の準備ができたら、Linuxディストリビューションである「Debian」をインストールします。PowerShellを開き、以下のコマンドを入力してDebianをダウンロードおよびインストールします。

# オンラインからDebianを取得してインストールを開始します
wsl --install -d Debian

インストールが完了すると、自動的にDebianのターミナル画面（黒い画面）が立ち上がります。画面の指示に従って、新しいユーザー名（Username）と、ログイン時に使用するパスワード（Password）を入力して初期設定を完了させます。

2.3 Debianの初期設定

インストール直後のDebianは、保存されているパッケージ情報が古いため、最新の状態に更新する必要があります。Debianのターミナルで以下のコマンドを実行します。

# パッケージ一覧を更新し、インストールされているシステムを最新化します
sudo apt update && sudo apt upgrade -y

また、今後のインストール作業で必要となる基本的なツールをあらかじめ追加しておきます。以下のコマンドを実行してインストールしてください。

# 証明書の管理やダウンロードに必要な基本ツールを導入します
sudo apt install -y curl ca-certificates gnupg lsb-release

第3章 Docker Engineのインストール

3.1 古いパッケージのクリーンアップ

もし以前に古いバージョンのDockerがインストールされていた場合、新しいDocker Engineのインストール時に競合（エラー）が起きる原因になります。そのため、まずは以下のコマンドを実行して、古い関連パッケージをきれいに削除します。

# 古いDocker関連のパッケージをすべて削除します（無い場合は無視されます）
sudo apt remove -y docker docker-engine docker.io containerd runc

3.2 Docker公式リポジトリの登録

最新の安定したDocker Engineをインストールするために、Docker公式のパッケージ配信サーバー（リポジトリ）をDebianのシステムに登録します。

まず、データの暗号化に必要な公式のGPG鍵をダウンロードして保存します。

# 鍵を保存するためのフォルダを作成します
sudo mkdir -p /etc/apt/keyrings

# Docker公式のGPG鍵をダウンロードし、ファイルに書き込みます
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

次に、DebianがDockerの配布サーバーを参照できるように設定ファイルを追加します。

# パッケージの取得元リストにDocker公式リポジトリを登録します
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

3.3 Docker Engineのインストールと動作検証

リポジトリの登録が終わったら、登録情報を読み込んでDockerのインストールを行います。以下のコマンドを実行します。

# 登録したリポジトリの情報をシステムに読み込ませます
sudo apt update

# Dockerの本体、管理ツール、便利なプラグインを一括でインストールします
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

インストールが完了したら、Dockerのサービスを手動で起動し、正常に動いているかテスト用コンテナを使って確認します。

# Dockerのバックグラウンド処理（サービス）を起動します
sudo service docker start

# テスト用コンテナ「hello-world」をダウンロードして実行します
sudo docker run hello-world

画面に「Hello from Docker!」とメッセージが表示されれば、Docker Engineのインストールは無事に成功しています。

3.4 非ルートユーザーでのDockerの実行許可

初期状態では、Dockerコマンドを実行するたびに sudo を最初につけて管理者権限で実行する必要があります。これは手間がかかるため、現在のログインユーザーを「dockerグループ」に登録し、sudo なしでコマンドを実行できるように設定を変更します。

# 現在のユーザー（$USER）をdockerグループに追加します
sudo usermod -aG docker $USER

この設定変更を適用するために、以下のコマンドを実行するか、一度Debianのターミナル（黒い画面）を閉じて再度起動し直してください。

# グループ設定の変更を現在のログインセッションにすぐに反映させます
newgrp docker

# sudoなしで動作するかテストします
docker run hello-world

第4章 WSL2上でのDocker運用とトラブルシューティング

4.1 systemdを用いたDocker自動起動の設定

WSL2の最新版では、Linux標準のシステム起動管理の仕組みである「systemd」を使用できます。これを有効にすることで、Debianが起動した瞬間に自動的にDockerサービスも連動して起動するようになり、毎回の sudo service docker start コマンドの入力が不要になります。

まず、Debian内にWSLの設定ファイルを作成して、systemdを有効にする設定を書き込みます。

# wsl.confファイルを管理者権限のテキストエディタで作成・編集します
sudo nano /etc/wsl.conf

ファイルの中に、以下の設定テキストをコピーして貼り付けて保存してください（nanoエディタの場合は Ctrl + O の後に Enter で保存し、Ctrl + X で終了します）。

[boot]
systemd=true

設定を有効化するために、WSLのシステムを一度完全にシャットダウンします。WindowsのPowerShellを開き、以下のコマンドを実行します。

# すべての稼働中のWSLディストリビューションを完全に停止させます
wsl --shutdown

再びDebianのターミナルを起動し、以下のコマンドでDockerの自動起動設定を有効にします。

# systemd経由でDockerの自動起動を有効にし、その場で起動します
sudo systemctl enable docker
sudo systemctl start docker

4.2 ネットワークとファイルアクセスの最適化

WSL2環境でDockerを使用する上で、ファイルの保存場所は「動作スピード」に極めて重大な影響を与えます。

Windows側のフォルダ（例: /mnt/c/Users/...）にあるプログラムコードをDockerコンテナに直接マウント（共有）して実行しようとすると、WindowsとLinux間のファイル転送処理がボトルネックになり、コンテナの動作や読み込みが非常に遅くなります。

これを防ぐためのベストプラクティスは以下の通りです。

  1. プロジェクトファイルはWSL内に置く: 開発するソースコードやプロジェクトフォルダは、必ずDebian内のホームディレクトリ（例: /home/ユーザー名/projects/）の下に作成・配置してください。
  2. Windows側からアクセスする: Windowsのエクスプローラーのアドレスバーに \\wsl.localhost\Debian\ と入力することで、Windows側から安全かつ高速にDebian内のファイルへアクセスできます。また、エディタは「VS Code」を使用し、「WSL拡張機能」を入れて開発を行うのが最もスムーズです。

4.3 よくあるトラブルと解決策

エラー: 「permission denied」でDockerが使えない

  • 状況: docker ps などのコマンドを実行した際に、権限不足でソケットファイルにアクセスできないエラーが出ます。
  • 解決策: ユーザーがdockerグループにまだ所属していないか、設定の反映が行われていません。以下のコマンドでグループを確認してください。
groups

もし出力結果に docker が見当たらない場合は、再度 sudo usermod -aG docker $USER を実行し、ターミナルソフトを再起動、またはPCを再起動してください。

状況: Dockerサービスが起動しない、または動かなくなった

  • 状況: ネットワークの設定エラーなどでDockerデーモンが起動できない状態です。
  • 解決策: 以下のコマンドで、システム起動時のエラーログを確認して原因を探します。
sudo systemctl status docker.service

多くの一時的な動作不良は、WindowsのPowerShellで実行する wsl --shutdown コマンドでWSL全体をリセット（再起動）することで解決します。