In case you have a script that you’d like to debug but cannot run locally, e.g. it requires access to a database, which is located only in production, RubyMine provides an ability to connect to the remote debug session from the local host and use all benefits of the graphical built-in debugger.

In this tutorial we will use RubyMine 7.1.2 and demo-script to illustrate basic steps. Please clone sample from Github.

0. Starting remote debug session on the remote host

The common view of the command is:

rdebug-ide --host --port 1234 --dispatcher-port 26162 -- $COMMAND$

This command is also shown in Run/Debug Configuration as a tip:

So in order to do it we have to run SSH session to the remote host. Open Tools | Start SSH session..., add remote host using Edit Credentials option, specify port, user/password and click OK.

Remote host connection will open in the Terminal and we can run remote debug session:

~$ rdebug-ide --host --port 1234 --dispatcher-port 26162 /home/user/RubymineProjects/remote-debug-example/math_wiz.rb

If you have any problems with debugging or prefer a full log, it might be useful to start a session with an additional debugger log: add a parameter ---debug to the command:

rdebug-ide --host --port 1236 --dispatcher-port 26167 --debug /home/user/RubymineProjects/remote-debug-example/math_wiz.rb

In this command:
port (1234) - port on the remote host
dispatcher-port (26162) - port on your localhost

Now we have remote debug session started.

1. Creating a local copy of the script in question

In order to open our script in RubyMine to set breakpoints and finally start debugging, we need to copy it to the local host. The fastest way would be to switch to the local tab (or open a new one) in the Terminal and copy our script:

#create a local folder
~$ mkdir ~/RubymineProjects/remote-debug-example

#copy file to the local folder
~$ scp user@remote-host:RubymineProjects/remote-debug-example/math_wiz.rb ~/RubymineProjects/remote-debug-example/

Then open the folder ~/RubymineProjects/remote-debug-example with script in RubyMine. It will create a new project and RubyMine will suggest you to configure a Ruby interpreter for it.

In case you need to debug some internal(native) Ruby code, it would be better to use the same environment as on the remote host (you could select the same Ruby SDK in the Settings | RubyMine SDK and Gems).

2. Configuring breakpoints

Just click on the left side of the code line in Editor to set a breakpoint (or use shortcut Cmd+F8).

3. Configuring the Ruby Remote Debug Run/Debug configuration

Then set other parameters in the configuration:

Save configuration with Apply and OK buttons. Now we are ready to connect to the remote session and debug the script.

4. Running remote debug configuration in debug mode

Run 'Remote debug configuration' in debug mode (please note that only this mode is available). Local debugger connects to the remote session and stops on the breakpoint that we've set locally in our script.

5. Running remote debug for Rails applications

It’s possible to use this way of debugging in case of Rails applications as well.

For example, the command which starts debug session could be:

~$ rdebug-ide --port 1236 --dispatcher-port 26166 --host bin/rails – s -b

Run/Debug Configuration example:

Then we can run Rails remote debug configuration in debug mode and stop on the breakpoint using remote debug session: