コンテンツにスキップ

Dev Container 利用ガイド

本ドキュメントでは、リツビ B2B EC 開発リポジトリ向けに整備した Dev Container 環境の使い方と、ローカル開発環境との整合を取るための設定方法をまとめる。

目的とメリット

  • 環境差分の吸収: Node.js 22 / pnpm 10.17 を共通化し、依存ツールのバージョン差による不具合を防ぐ。
  • 初期セットアップの自動化: pnpm install --frozen-lockfile と Lefthook インストールをコンテナ作成時に自動実行。
  • 既存ワークフローの継承: Docker ソケット共有と永続ボリュームにより、apps/vendure-server/docker-compose.dev.yml や pnpm キャッシュをそのまま活用。
  • 個人設定の反映: ホストの dotfiles をコピーし、シェルやエイリアス設定を再現。

ディレクトリ構成

.devcontainer/
├── Dockerfile                 # Node.js 22 ベースのカスタムイメージ
├── devcontainer.json          # 既定設定（共通で利用）
├── devcontainer.local.json    # 個人向け上書き設定（Git 除外）
├── .gitignore                 # _dotfiles-cache/ と local 設定を除外
└── scripts/
    ├── prepare-dotfiles.sh    # ホスト側 dotfiles をキャッシュ
    ├── copy-dotfiles.sh       # キャッシュ内容をコンテナへ展開
    └── post-create.sh         # 依存インストールと Lefthook セットアップ

利用手順

  1. VS Code でコマンドパレットから Dev Containers: Rebuild and Reopen in Container を実行。
  2. ビルド完了後、post-create.sh が自動で依存関係をインストールし、Lefthook を設定する。
  3. 必要に応じて pnpm run dev や pnpm run dev:services を実行して開発を開始する。

補足: 初回ビルド時はベースイメージ取得と依存インストールで時間がかかる。pnpm 用ボリューム (ritsubi-pnpm) と uv キャッシュボリューム (ritsubi-uv-cache) はコンテナ再生成後も再利用される。

Dotfiles 同期の仕組み

  • initializeCommand が prepare-dotfiles.sh を実行し、ホストの ~/.dotfiles（または DEVCONTAINER_DOTFILES_SOURCE で指定したパス）を .devcontainer/_dotfiles-cache/ に同期する。
  • post-create.sh 内で copy-dotfiles.sh を呼び出し、キャッシュ済みの dotfiles をコンテナ内 ${HOME} 配下にコピーする。
  • dotfiles 同期を無効化したい場合は、Dev Container 再ビルド前にホストで DEVCONTAINER_DOTFILES_DISABLE=1 を設定する。

カスタムパスの指定例

# fish などのシェルで環境変数を設定した例
set -Ux DEVCONTAINER_DOTFILES_SOURCE /Users/example/.config/dotfiles

ローカル専用設定 (devcontainer.local.json)

  • .devcontainer/devcontainer.local.json は Git にコミットされず、各開発者が自由に編集できる。
  • 既定では ~/.xxxx を読み取り専用でマウントする例を記載している。必要に応じて別のディレクトリに書き換える。
  • 例: GitHub CLI 資格情報を使いたい場合
{
  "mounts": [
    "source=${localEnv:HOME}/.config/gh,target=/home/node/.config/gh,type=bind,consistency=cached,ro"
  ]
}

提供ツールとパス

  • イメージレイヤーで追加済みの主なツール
  • git, rsync, postgresql-client, redis-tools, python3, uv
  • corepack で pnpm 10.17 を有効化済み。PNPM_HOME=/home/node/.local/share/pnpm が containerEnv で設定される。
  • Docker ソケット (/var/run/docker.sock) を共有しているため、コンテナ内部から docker compose や flyctl などを利用可能（CLI が必要なら利用者側で追加インストールする）。

トラブルシューティング

症状 原因と対処
dotfiles が反映されない DEVCONTAINER_DOTFILES_DISABLE=1 が設定されていないか確認。~/.dotfiles が存在しない場合はログで「source not found」と表示される。
コンテナ起動後に pnpm が見つからない post-create.sh 実行前にターミナルを開いた可能性。ターミナルを再起動するか、pnpm env use --global 10.17.0 を手動で実行。
Docker コマンドが失敗する ホスト側で Docker Desktop 等が停止していないか確認。社内ポリシーでソケット共有が禁止されている場合は、devcontainer.local.json で Docker マウントを削除し、外部サービスはホストで起動する。

今後の拡張ポイント

  • post-create.sh に pnpm run docs:build や pnpm run typecheck を追加し、初期チェックを自動化する余地がある。
  • features セクションに GitHub CLI など他の devcontainer feature を追加する場合は、互換性を確認してから devcontainer.json を更新する。
  • ARM 環境（Apple Silicon 等）でベースイメージの互換性に問題があれば、Dockerfile のベースタグを調整する。

以上。