【devcontainer完全ガイド】DockerとWSLで最強のイマドキ開発環境を手に入れよう！

みなさんDocker活用してますか
CI/CDでDocker Imageを使うのはもちろんですが、やはりコンテナの有用性は、環境に依存せずどこでも同じように動作することですよね。

それを活用してみんな同じ開発環境が使えたら嬉しくないですか
そんなときに使えるのがdevcontainerの仕組みです。

以下に当てはまるアナタへ役立つ記事です。

• Node.js, npx, Javaなどはどんどんバージョン増えるので入れたくない。
• VSCodeの拡張機能がたくさん増えてしまって重くなってしまうのも嫌。
• プロジェクトの新規加入メンバーに導入手順を渡して1日浪費するのは、もったいないし面倒。
  (やることでプロジェクトの理解は深まると思いますが)

winget install Microsoft.VisualStudioCode
code --install-extension ms-ceintl.vscode-language-pack-ja
code --install-extension ms-vscode-remote.remote-containers
code --install-extension ms-vscode-remote.remote-wsl

1. WSLのセットアップ (できていれば飛ばしてOK)
2. 作業ディレクトリの用意
3. 開発環境イメージの選定と定義
4. devcontainer.jsonの実装
5. devcontainerの立ち上げ
6. リポジトリにpushじゃあああ

1. WSL本体の導入

   Powershell (管理者権限) で以下を実行

   Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
   # 実行後に再起動が必要
   

2. Ubuntuのディストリビューションを指定してインストール

   コマンドプロンプトで以下を実行 (時間かかります)

   SET DISTRIBUTION=Ubuntu-22.04
   WSL --install --distribution %DISTRIBUTION%
   REM デフォルトユーザーとパスワードの設定
   

   ディストリビューションのアンインストール

   WSL --unregister Ubuntu-22.04
   winget uninstall Canonical.Ubuntu.2204
   

WindowsのDocker Desktopには会社の制限がありますよね。
「Dockerが使えない」と泣いていたあなたでも、WSLが使えるのであればUbuntu側にDocker CEをインストールすれば解決です。
以下をWSL環境のBashターミナルで実行して数分待てばインストール完了です。

sudo apt update
sudo apt install -y \
 ca-certificates \
 curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

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

sudo apt update
sudo apt install -y \
 docker-ce \
 docker-ce-cli \
 containerd.io \
 docker-buildx-plugin \
 docker-compose-plugin &&
  sudo apt clean &&
  sudo rm -rf /var/lib/apt/lists/*

sudo service docker start
sudo usermod -aG docker $USER
# ターミナル再起動後にsudo無しで実行可能

上記コマンドの詳細が知りたければこちらをご参照ください Install Docker Engine on Ubuntu

git config --global user.name "[名前]"
git config --global user.email "[メールアドレス]"
ssh -T git@github.com
# 聞かれたら`yes`

1. 適当なフォルダをWSL環境で用意してください。
   (下記の例はユーザーフォルダ直下のdevcontainer_sampleフォルダ)

   mkdir ~/devcontainer_sample
   code ~/devcontainer_sample
   

   codeコマンド

   VSCodeのコマンドです。PATHを通せばcmdからでも任意のものがVSCodeで開けます。
   引数でパスを指定します。

   • 対象がファイルであれば、カレントウィンドウで開いて編集できるようになります。
   • 対象がフォルダであれば、ウィンドウを切り替えてワークフォルダが指定のパスに切り替わります。

   詳細はリファレンスで。 The Visual Studio Code command-line interface

2. 作成したフォルダが新規ウィンドウで開かれているので、ここで .devcontainerフォルダを作成

   mkdir .devcontainer
   

3. 作成した .devcontainerフォルダ内にファイルを作成

   touch .devcontainer/{Dockerfile,devcontainer.env,compose.yaml,devcontainer.json}
   

4. こうなっていればOKです

   ~/devcontainer_sample$ tree -a
   .
   └── .devcontainer
       ├── Dockerfile
       ├── compose.yaml
       ├── devcontainer.env
       └── devcontainer.json
   

   treeコマンドはデフォルトでは入っていません

   sudo apt install tree
   

いよいよdevcontainerのDocker Image設定ファイルを作っていきます。

1. Dockerfileにベースイメージを定義

   Dockerfile

   ARG TAG
   FROM ubuntu:${TAG}
   

   • alpineなどの軽量イメージを使ってもなんだかんだ不都合があったりするので、私はよく普通のubuntuイメージを使っています。
   • このファイルでは、引数でイメージタグを受けるようにしてあります。
   • その他、基本的にどの開発環境でも必要なライブラリ等があればインストールしておいてOKです。
   • 自分で探したい人はDocker Hubから見つけましょう。 dockerhub
   devcontainer用のイメージ

   Microsoftがdevcontainer用のイメージとして提供しているものがあります。 microsoft/devcontainers
   セクションのはじめにも記載したとおり、ここでJavaなど言語固有のイメージを使わないことをオススメします。

   また、例で記載しているubuntuのイメージよりも、mcr.microsoft.com/devcontainers/base:ubuntu-22.04が適している可能性が高いです。
   私はプレーンなubuntuと違うことで不都合があったら嫌だなと思って使っていませんが、どういう違いがあるかは把握していません (無駄な拡張機能とか入れられたら嫌だし...)。

2. Docker Image用のenvファイルを定義
   システムの根本的なものだけ定義し、次のcomposeファイルで使います

   devcontainer.env

   TZ="Asia/Tokyo"
   LANG="C.UTF-8"
   

3. docker composeにサービスを定義
   ubuntuのイメージからplainというイメージを作っています。
   この例は最低限の実装なのでplainイメージには何も有り難みがないです。
   2行目のubuntuというサービス名を、後述のdevcontainer.jsonで使います

   compose.yaml

   services:
       ubuntu:
           build:
               context: .
               dockerfile: Dockerfile
               args:
                   TAG: 22.04
           image: plain:22.04
           hostname: ubuntu
           env_file:
               - devcontainer.env
   

   docker composeのファイル名

   いつの間にか「compose.yaml」が推奨になっていたらしい Compose file reference

なんと、イメージ選定と定義は以上です。
Javaの環境などについては↓のfeaturesで。

これから作るのはこちら。

{
    // # devcontainer.json sample
    // recommend: Do not sort json
    // ## To create image
    "name": "mySample",
    "workspaceFolder": "/workspace",
    "shutdownAction": "stopCompose",

    // ## From base image
    "dockerComposeFile": ["./compose.yaml"],
    "service": "ubuntu",
    "runServices": [],

    // ## Resources
    // warning: Can not use Env
    "mounts": [
        {
            "type": "bind",
            "source": "${localWorkspaceFolder}",
            "target": "${containerWorkspaceFolder}",
            "consistency": "delegated"
        }
    ],
    "features": {
        "ghcr.io/devcontainers/features/common-utils:2": {
            "username": "developer"
        },
        "ghcr.io/devcontainers/features/git:1": {}
    },

    // ## Environment
    "remoteUser": "developer",
    "containerEnv": {},
    "remoteEnv": {},
    "portsAttributes": { "80": { "label": "http", "onAutoForward": "silent" } },

    // ## Container command
    // warning: To use .sh you need mount
    // info: key is output stage
    "overrideCommand": true,

    // ## IDE
    "customizations": {
        "vscode": {
            "extensions": [],
            "settings": {}
        }
    }
}

それぞれ区切って解説します
詳細はリファレンスへ Dev Container metadata reference

作成するコンテナの名前 (name) とdevcontainerを開いたときのworkspaceFolderを指定します。
shutdownActionはdevcontainerを終了したときの動作で、デフォルトはstopComposeですが、気になるので明示的に書いています。

{
    "name": "mySample",
    "workspaceFolder": "/workspace",
    "shutdownAction": "stopCompose",
}

compose.yamlのパスとその中から使うサービス名を記述します。
runServicesで複数起動もできます。便利そうだけど、活用できてない。

{
    "dockerComposeFile": ["./compose.yaml"],
    "service": "ubuntu",
    "runServices": [],
}

一番カスタマイズするところです。

{
    "mounts": [
        {
            "type": "bind",
            "source": "${localWorkspaceFolder}",
            "target": "${containerWorkspaceFolder}",
            "consistency": "delegated"
        }
    ],
    "features": {
        "ghcr.io/devcontainers/features/common-utils:2": {
            "username": "developer"
        },
        "ghcr.io/devcontainers/features/git:1": {}
    },
}

mounts

• devcontainer内で活用するファイルやフォルダを紐付けましょう
  ここで見慣れない変数が出てきました

  • ${localWorkspaceFolder}: VSCodeで現在開いているウィンドウのルートパスに置き換わります
  • ${containerWorkspaceFolder}: workspaceFolderで指定したパスに置き換わります

  その他、詳細はリファレンスへ Variables in devcontainer.json

  mountの構築段階では環境変数が使えません

  使える変数も限られているのでちょっと不便です。

• 書くことは普段のDockerのbindやvolumeの内容と変わりません
  volumeはcompose.yamlで定義していなくてもdevcontainer.jsonで記述すれば作ってくれます

  dockerのmountの記述

  Dockerを普段から活用している皆さんは、short syntaxではなくlong syntaxで書きましょう。 ^[1]
  Docker-docs-ja

features

これがdevcontainerの一番の特徴といっても過言ではありません (名前の通り)。

• このfeaturesを指定することで特定の言語の環境構築や設定を諸々済ませてくれます。
  拡張機能も一緒につけてくれるおまけ付きです
  (個人的には追加で入れてくる拡張機能は自分で指定したいところですが...)。

• 存在するfeatureはここから探してください。 Features

• featureによってはパラメータでバージョンなどを指定できます。

• 例えばJava+Node.js+AWS (Terraform) の環境を作る場合。

  feature	コメント
  ghcr.io/devcontainers/features/common-utils:2	イメージ内のユーザー作成 (UIDも指定可能) デフォルトはvscodeユーザーが作られるのですが、なんか嫌なので使っています。
  ghcr.io/devcontainers/features/git:1	Gitの環境構築 (大体のイメージには標準でありますが、一応入れています)
  ghcr.io/devcontainers/features/java:1	Javaの環境構築 (もちろんバージョン指定可能)
  ghcr.io/devcontainers/features/node:1	Node.jsの環境構築 (もちろんバージョン指定可能)
  ghcr.io/devcontainers/features/aws-cli:1	AWS-CLIが入れられます (~/.awsのbindを忘れずに)
  ghcr.io/devcontainers/features/terraform:1	Terraformが入れられます

  Column

  イマドキ開発にうってつけの、Docker-in-Dockerのfeatureもあります
  ぜひ開発に欲しいものがないか探してみてください

{
    "remoteUser": "developer",
    "containerEnv": {},
    "remoteEnv": {},
    "portsAttributes": { "80": { "label": "http", "onAutoForward": "silent" } },
}

remoteUser

コンテナで作業する際のユーザー名。

containerEnv

あまり使わないことを推奨。
コンテナ固有の環境変数で、変化するとコンテナの再構築が必要。

remoteEnv

• 接続時のみに反映される環境変数。
• containerEnvよりも使いやすい。
• AWS_DEFAULT_PROFILEなどをセットして使っています。
  (もちろんこの環境変数を使う場合は~/.awsをマウントしましょうね。)

portsAttributes

属性についてはリファレンスを参照してください。 Port attributes

{
    "overrideCommand": true,
}

• コンテナのcreate時やattach時に実行するコマンドを指定できます。
  • タイミングやライフサイクルによってコマンドが6種類もあります。
  • 例えばコンテナを構築した時に、node_modulesのvolumeのchownやnpm installをするが、一度コンテナを作った以降でコンテナにattachする際は実行する必要が無いものなど。
• 定義できるコマンドはこちら (注意点もたくさんあります)。 Lifecycle scripts

{
    "customizations": {
        "vscode": {
            "extensions": [],
            "settings": {}
        }
    }
}

IDE固有の記述です。
これもリファレンスがあります。みなさんの好きなもので使えると良いですね。 Supporting tools and services

今回はVSCodeに限った紹介をします。

extensions

• devcontainer内で自動的にインストールされる拡張機能で、拡張機能のIDを指定します。
• featuresによって勝手にインストールされる拡張機能もありますが、重複は問題ありません。

settings

• リポジトリの .vscodeに含むもよし、ここで設定するのもよし。
• ユーザーのsettings.jsonも使われますのでご安心を。
• なので私はあんまりここに書かないです

おめでとうございます。
ここまでで設定ファイルができあがれば、あとは以下の手順でdevcontainerを立ち上げることができます。

1. WSL環境のVSCodeで、Ctrl+Shift+Pでコマンドパレットを開く
2. Dev Containers: Rebuild and Reopen in Containerを入力しEnter
   • VSCodeで開いているワークフォルダから .devcontainer/*/devcontainer.jsonを探して、構文チェックが済むとcreateが始まります (複数あると選択ポップアップが出ます)。
   • create中にエラーがあってもWSL環境に戻って、エラースタックが表示されるので安心です
3. devcontainer起動後のウィンドウで、VSCodeの拡張機能のインストールが終了すれば完了です
4. WSL環境に戻る場合は、再度コマンドパレットを開いて、Dev Containers: Reopen Folder in WSLを実行します
5. 次回以降はコマンドパレットから、Dev Containers: Reopen in Containerを実行します
   コンテナの再構築は不要なので初回より断然、時間がかからなくなります
6. WSL環境のVSCodeにms-azuretools.vscode-docker拡張機能を入れておけば、コンテナやイメージの一覧が出るので嬉しいです

devcontainer環境下で開発をしていて、リポジトリの内容を更新したので、いざgit push...というときにエラーが出ます。

「そうか、.gitconfigのbindをしていないじゃないか」
→ 違います。devcontainerは ~/.gitconfigを自動で複製してくれます。

というわけで、そのあたりの導入をします。

REM sshのバージョンアップ
winget install Microsoft.OpenSSH.Beta

KEY_NAME=ed25519

sudo apt update
sudo apt install -y \
   openssh-client \
   keychain \
   socat \
   xsel &&
  sudo apt clean &&
  sudo rm -rf /var/lib/apt/lists/*

# keyがなければ生成
if [ ! -f $HOME/.ssh/id_${KEY_NAME} ]; then
   ssh-keygen -t ${KEY_NAME}
   echo "clipboard: id_${KEY_NAME}.pub content"
   cat $HOME/.ssh/id_${KEY_NAME}.pub | xsel -bi
fi

# 自動エージェント起動の設定
echo \
   "if [ -z \"\$SSH_AUTH_SOCK\" ]; then
   RUNNING_AGENT=\"\`ps -ax | grep 'ssh-agent -s' | grep -v grep | wc -l | tr -d '[:space:]'\`\"
   if [ \"\$RUNNING_AGENT\" = \"0\" ]; then
        ssh-agent -s &> $HOME/.ssh/ssh-agent
   fi
   eval \`cat $HOME/.ssh/ssh-agent\` > /dev/null
   ssh-add $HOME/.ssh/id_${KEY_NAME} 2> /dev/null
fi" \
   >$HOME/.bash_profile

echo \
   "/usr/bin/keychain -q --nogui $HOME/.ssh/id_${KEY_NAME}
source $HOME/.keychain/$(hostname)-sh" \
   >$HOME/.bashrc

軽く説明します。

1. 必要なものをapt installしています。
2. ~/.ssh/id_ed25519がなければ生成します。
   • 生成された公開鍵はクリップボードに送られています。
3. ssh-agentの起動とssh-addを .bash_profileに上書きします。
   • 困るようであれば追記に修正してください。
4. keychainというもので、devcontainerとの連携を定義し .bashrcに上書きします
   • 困るようであれば追記に修正してください。
5. 手動で、GitHubのSSHキー登録先にクリップボードの内容を登録してください。
   https://github.com/settings/keys
6. あとはdevcontainer内部で、ssh -T git@github.comが実行できれば問題ありません。

お疲れ様でした。これでみんな幸せに開発環境構築できますね。
個人的にポイントだと思うのは、ベースとするDocker Imageを言語固有のものにしないことです。
記事中に書いたとおり、開発環境に複数の言語を入れることになるのであれば、言語固有のものは使わない方が良いと思います。

またお気づきかもしれませんが、今回Docker Imageが3つ登場します。

1. ubuntu:22.04
2. plain:22.04
3. devcontainerのイメージ

compose.yamlを開発環境で共有して一カ所で管理してしまうと、同じイメージを参照して不都合があったので、開発環境ごとに複製したほうがよいです。

まだノウハウなども多くない内容だと思いますので、どんどんオレオレ環境を作っていきましょう。