Setting Up a Rails Server Run/Debug Configuration in RubyMine

Desired Outcome

Create a RubyMine Run/Debug configuration that starts a local Rails server, allows you to set breakpoints, inspect variables, and stop the server cleanly.

Prerequisites

1. RubyMine installed (version 2023.2 or later recommended).
2. A Rails project open in RubyMine that contains a Gemfile and config/application.rb.
3. The Ruby SDK configured via Settings → Languages & Frameworks → Ruby SDK and Gems.
4. Network access to bind to localhost:3000 (or another free port).

Procedure

1. Open the configuration dialog: From the main menu choose Run → Edit Configurations….
2. Add a Rails Server configuration: Click the + button, select Rails Server from the list.
3. Fill in the fields:
   • Name: e.g., Dev Server.
   • Ruby SDK: choose the SDK you verified in Prerequisites.
   • Host: keep the default localhost (or change if you need a different interface).
   • Port: default 3000; adjust only if you know the port is free.
   • Environment variables: add any needed vars (e.g., RAILS_ENV=development) using the … button.
4. Apply and close: Click Apply, then OK.
5. Start the server in debug mode: In the toolbar, select the newly created configuration from the dropdown and click the Debug icon (bug symbol). RubyMine will launch the Rails server and attach a debugger.
6. Set breakpoints: Open any controller, model, or view file and click the gutter next to a line of code. A red dot indicates a breakpoint.
7. Trigger a breakpoint: Open a browser and navigate to http://localhost:3000 (or the host/port you set). When the request hits a breakpoint, execution pauses and the Debug tool window appears, showing frames, variables, and evaluation options.

Expected Checks

• After clicking Debug, the Run tool window should display the Rails startup log and end with a line like => Booting Puma or => Rails 7.0.4 application starting in development.
• The Debug tool window lists a process ID (PID) and shows a Frames pane with your application’s source files.
• Hitting a breakpoint pauses execution; you can inspect variable values in the Variables pane and evaluate expressions in the Evaluate Expression dialog.
• Opening http://localhost:3000 in a browser returns the Rails welcome page or your application’s root route without error.
• Running a Rails generator from Tools → Run Rails Generator (e.g., rails generate controller welcome index) creates the expected files, confirming the environment is usable.

Recovery Options

1. Stop the server: In the Debug tool window, click the Stop button (red square) or select the configuration again and choose Stop from the dropdown. The console will show the exit code.
2. Port conflict: If you see an error like Address already in use - bind(2) for "127.0.0.1" port 3000, change the Port field in the configuration to a free number (e.g., 3001) and restart.
3. SDK misconfiguration: If the console shows Could not find ruby-X.X.X, open Settings → Languages & Frameworks → Ruby SDK and Gems, verify the SDK path, and reapply the configuration.