Configuring Rails Server Run/Debug Profiles in RubyMine

The Problem: Manual Server Management

Running a Rails server via the embedded terminal using rails s is common, but it disconnects the server process from the IDE's powerful debugging and profiling tools. When you run the server through a dedicated Run/Debug Configuration, you gain the ability to set breakpoints, inspect variables in real-time, and restart the server with a single click without hunting for the terminal process to kill it.

Prerequisites

• RubyMine Version: 2023.2 or later.
• SDK Setup: A configured Ruby SDK (verified in Settings > Languages & Frameworks > Ruby SDK and Gems).
• Project State: A Rails project with a Gemfile where bundle install has been successfully executed.
• Database: A functional database instance (e.g., SQLite3 or PostgreSQL) ready for migrations.

Creating the Rails Run Configuration

Follow these steps to move your server management from the terminal into the IDE interface:

1. Navigate to the top toolbar and click the Run menu, then select Edit Configurations....
2. Click the + (Add New Configuration) icon in the top-left corner of the dialog.
3. Select Rails from the list of available templates.
4. Configure the following fields:
   • Name: Give it a descriptive name (e.g., Rails Dev Server).
   • Project root: Ensure this points to the base directory of your Rails application.
   • Environment: Set this to development.
   • Port: Default is 3000; change this if you have multiple apps running locally.
5. (Optional) Check Launch browser if you want RubyMine to automatically open your default browser to the root URL upon successful boot.
6. Click Apply and then OK.

Verification and Diagnostics

To verify the configuration is working, select your new profile from the toolbar and click the Run (green arrow) or Debug (bug icon) button. Monitor the Run tool window at the bottom of the IDE.

Check	Expected Result	Indication of Failure
Log Output	=> Booting Puma (or your specific web server)	Stack trace or GemNotFound errors
Network Binding	Listening on http://127.0.0.1:3000	Address already in use (Port conflict)
Browser Access	Application home page loads successfully	500 Internal Server Error or Connection Refused

Handling Common Configuration Failures

If the server fails to start, check these specific points:

• SDK Mismatch: Run bundle exec ruby -v in the terminal. Compare this version to the one selected in Settings > Languages & Frameworks > Ruby SDK and Gems. If they differ, the IDE may attempt to boot the server with the wrong Ruby version.
• Custom Boot Scripts: If your project uses a Procfile or a custom shell script to launch the server (common in Dockerized or complex environments), the standard Rails configuration may fail. In this case, create a Ruby script configuration instead and point it to your specific entry point.
• Stale PID Files: If you see an "Address already in use" error, a previous process may have crashed without cleaning up. Run rm tmp/pids/server.pid in the terminal and restart the configuration.

Rollback and Recovery

Because creating a Run Configuration only adds a metadata file (usually stored in .idea/runConfigurations) and does not modify your application code or environment, the only "rollback" required is deleting the configuration:

1. Go back to Run > Edit Configurations....
2. Select the Rails configuration you created.
3. Click the - (Remove) button.
4. Click OK.