VSCodeでDockerコンテナのRailsアプリをデバッグ

2025.10.19更新

はじめに

Dockerコンテナを使ったRails開発環境において、VSCodeからデバッガ接続するためのメモ。デバッグ環境の構成はざっくり以下のとおりで、VSCodeからrdbgコマンドでデバッグポートに接続する形。

• コンテナ側：rdbgコマンド（debug gem）でRailsをデバッグモードで起動
• Windows側：rdbgコマンド（debug gem）でコンテナのデバッグポートに接続

コンテナとWindowsそれぞれにRubyとdebug gemを導入する必要がある。双方のバージョンは合わせる。

環境

• Windows 11 Home 24H2
  • Ruby+Devkit 3.4.7-1 (x64)
    • debug gem 1.11.0
  • Visual Studio Code 1.105.1
    • Ruby LSP 0.9.32
  • Docker Desktop 4.47.0
    • ruby 3.4.7
      • rails gem 8.0.3
      • debug gem 1.11.0

前提

• Railsアプリケーションが作成済である
• ルートフォルダ（Gemfileがあるフォルダ）をプロジェクトルートと呼ぶことにする
• ルートフォルダはWindowsとコンテナで共有（ファイルシステムをマッピング）している
• プロジェクトルートに.ruby-versionファイルが存在する場合は、ファイル内に記載のバージョンとインストールするRubyのバージョンを合わせる

導入方法

Windows側

Ruby

インストール手順はたくさん情報があるので詳細は割愛。
https://rubyinstaller.org/ からDevkit付きをダウンロードし、デフォルト設定でインストール。MSYS2も構成。

debug gem

Gemfileに以下を追記。

group :development, :test do
  # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
  gem "debug", platforms: %i[ mri windows ]
end

コマンドプロンプトを開き、プロジェクトルートに移動して以下を実行。

bundle install

以下を実行してrdbgのバージョン番号が表示されればOK。

rdbg -v

Visual Studio Code

インストール手順はたくさん情報があるので割愛。
インストール後、プロジェクトルート（Gemfileがあるフォルダ）を開く。
重要！ 複数フォルダを開く場合は、プロジェクトルートを先頭（一番上）に配置する。

Ruby LSPプラグイン

拡張機能で検索してインストールする。インストールするとプロジェクトルートに.ruby-lspフォルダが作成される。
適当なRubyのソースファイルを開いて、画面右下の{} Rubyにカーソルを当て、何もエラーが表示されなければOK。

デバッグ設定

プロジェクトルートに.vscode/launch.jsonを作成して以下を追記。

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "ruby_lsp",
      "name": "Attach debugger",
      "request": "attach",
      "debugPort": 1234
    }
  ]
}

Dockerコンテナ側

構成方法はたくさん情報があるので割愛。
環境変数に以下を設定する。

RUBY_DEBUG_LOCAL_FS_MAP=コンテナ側のプロジェクトルート:Windows側のプロジェクトルート（先頭のC:は削除）

具体的にはこんな感じ。RUBY_DEBUG_LOCAL_FS_MAP=/web:/work/someapp/web

Railsはデバッグモード（rdbg）で起動するよう設定する。

bundle exec rdbg -O -n --host 0.0.0.0 --port=1234 -c -- bin/rails server -b '0.0.0.0' -p 3000

デバッグ方法

ソースコード上で停止させたい位置に以下を追記。
※VSCodeでブレークポイントを設定しても効かない・・・。

binding.break

VSCodeの実行とデバッグでAttach debuggerを選択してデバッグを開始。この状態でWebブラウザからアプリを実行すると、VSCodeのデバッガが上記の位置で停止する。

なおbinding.breakを記載した状態でデバッガを起動せずに実行すると、Railsがデバッガ接続待ちで停止したままになってしまう。デバックが完了したらbinding.breakを削除する必要がある。

トラブルシュート

Windows側でrdbgが実行できない

コマンドプロンプトでrdbgを実行すると、こんなエラーが出る場合。

'rdbg' は、内部コマンドまたは外部コマンド、
操作可能なプログラムまたはバッチ ファイルとして認識されていません。

以下を確認する。

• C:\Ruby34-x64\bin\rdbg.batが存在すること
• 環境変数PATHにC:\Ruby34-x64\binが含まれていること
• プロジェクトルートでbundle info debugを実行してバージョン番号が表示されること

上記がダメならWindows側でのbundle installが失敗していると思われるので、再度実行する。

Ruby LSPプラグインが動作しない

以下を確認する。

• プロジェクトルートに.ruby-lspフォルダが存在すること
• VSCode上で複数フォルダを開いている場合、プロジェクトルートが先頭（一番上）になっていること

上記がダメならRuby LSP が正しく構成できていない。プロジェクトルートが先頭（一番上）であることを確認し、Ruby LSP を再インストールする。

デバッガが起動しない

以下を確認する。

• Windowsからコンテナのデバッグポートに接続できること
  PowerShellで以下を実行し、結果にTcpTestSucceeded : Trueが出力されることを確認する。

  Test-NetConnection -ComputerName localhost -Port 1234
  

上記がダメならWindowsからコンテナのデバッグポートに接続できていないので、コンテナのポート設定を確認する。

• デバッグポートが解放されているか。例えばcompose.ymlに以下が記載されているか

  ports:
      - "1234:1234"
  

• Rails起動コマンドのデバッグポート指定が正しいか。例えばcompose.ymlのRails起動コマンドが以下のようになっているか

  bundle exec rdbg -O -n --host 0.0.0.0 --port=1234 -c -- bin/rails server -b '0.0.0.0' -p 3000
  

課題

停止位置のファイルが別ウィンドウで開いてしまう（画像赤枠）。RUBY_DEBUG_LOCAL_FS_MAPを設定すればよいとの情報もあるが、Windows環境ではパスにコロンが入るため、どうしようもない気がしている・・・。