Choosing a Rails Server Launch Method in RubyMine: Built-in, Docker-Compose, or External Terminal

The decision you face

When starting a Rails project in RubyMine, you must decide how the server is launched. This choice determines the speed of your feedback loop, the reliability of your breakpoints, and how closely your development environment mirrors production. The goal is to balance developer velocity with environment parity.

Constraints that shape the choice

• Startup speed – The time elapsed from clicking "Run" to a responsive localhost:3000.
• Debugging fidelity – The ability to set breakpoints, inspect variables, and navigate the call stack directly within the IDE.
• Environment parity – Whether the runtime (Ruby version, gems, and OS libraries) matches the production Docker image.
• IDE integration – Access to integrated log viewers, console output, and automatic run-configuration management.

Option comparison

Launch method	Typical start time	Debugging	Environment	IDE integration	Setup effort
Built-in server	≤ 5s	Full (Native)	Local machine	Seamless	Minimal
Docker-Compose	30–120s	Full (Remote)	Isolated/Prod-like	Good	Moderate
External terminal	Fast	Limited/Manual	Local machine	Manual	Low

Trade-offs explained

Built-in server: Maximum velocity

RubyMine starts the Rails process directly on your host OS. This provides the fastest edit-debug cycle because there is no container overhead. Breakpoints hit instantly, and the IDE manages the process lifecycle. The primary risk is "environment drift," where your local system libraries differ from those in production.

Docker-Compose: Production parity

Running inside a container ensures that every developer on the team uses the exact same Ruby binary and OS packages. While this eliminates "it works on my machine" bugs, it introduces latency during startup and requires a more complex debugging setup involving port forwarding and remote debugger gems.

External terminal: Maximum flexibility

Launching via a shell is useful for custom launch scripts or testing systemd-style environment variables. However, you lose the one-click debugging and integrated log parsing that make RubyMine efficient. This should be a fallback for edge cases.

Concrete validation: Built-in server

To verify the built-in workflow in RubyMine 2024.3:

1. Navigate to Run → Edit Configurations → + → Rails.
2. Set the Server to "Built-in" and the Port to 3000. Ensure the Ruby SDK matches your project's .ruby-version.
3. Place a breakpoint in app/controllers/application_controller.rb.
4. Start the configuration in Debug mode (Shift+F9).
5. Visit http://localhost:3000 in a browser.

Expected result: The IDE should pause execution at the breakpoint, displaying the current stack frame and local variables in the Debug tool window.

Concrete validation: Docker-Compose with remote debug

To verify the Docker workflow, follow these configuration steps:

1. Add the necessary debug gems to your Gemfile or Dockerfile:

   # Dockerfile example
   RUN bundle add ruby-debug-ide debase --group development

2. Configure docker-compose.yml to expose the debugger ports:

   services:
     web:
       command: bundle exec rdebug-ide --host 0.0.0.0 --port 1234 --dispatcher-port 26162 -- bin/rails s -b 0.0.0.0
       ports:
         - "3000:3000"
         - "1234:1234"
         - "26162:26162"
       environment:
         - RUBYMINE_DEBUG=1

3. Run docker-compose up --build from a terminal with Docker permissions.
4. In RubyMine, create a Ruby Remote Debug configuration targeting localhost:1234. Map your local project root to the container's working directory (e.g., /app).
5. Set a breakpoint and start the Remote Debug configuration.

Expected result: Upon reloading the page, the IDE should attach to the remote process and trigger the breakpoint.

Limitations and verification

• Path Mappings: In Docker mode, if breakpoints are marked as "unresolved," check the path mappings in the Remote Debug configuration. The IDE must know exactly how the local path relates to the container path.
• Port Conflicts: Only one method can occupy port 3000. Ensure previous server instances are killed before switching methods.
• Gem Compatibility: ruby-debug-ide and debase must match the Ruby patch version. Version mismatches often result in connection failures.

Final verification checklist:

1. Confirm curl -s http://localhost:3000 returns a response.
2. Confirm the debugger pauses at a controller breakpoint.
3. Confirm Rails request logs are streaming in the IDE console.