Debug
Remote debugging
Tutorial: Attach to a remote process

Tutorial: Attach to a remote process

Last modified: 09 August 2022

RubyMine enables you to attach to a running process on a local or remote computer. This capability allows you to debug applications that cannot be launched directly from the IDE.

In this topic, we’ll use this capability to debug a sample Rails application running on a remote machine.

Prerequisites

In this tutorial, we'll use two machines to demonstrate debugging of the remote application:

Local machine: Mac with macOS, with RubyMine installed.
Remote machine: The Ubuntu machine with enabled SSH access and the Ruby interpreter installed. Note that GDB should also be installed on a remote machine.
In our tutorial, the remote computer has the sample-web-server name.
tip
For the remote macOS machine, LLDB should be installed.

On both machines, we’ll use the jetbrains user’s home directories to store source code.

Clone and run a remote application

First of all, we need to clone and run the sample application on a remote machine. To do this, connect to a remote machine and use instructions from the Getting started chapter. After performing the required steps, use the rails server command to run an application:

Clone a project on a local machine

After running the sample application on a remote machine, launch RubyMine and open the same application on a local machine using this instruction: Check out a project from Version Control. In URL, insert the following address: https://github.com/JetBrains/sample_rails_app.git. Then click Clone.

Configure a remote interpreter

In this part, we’ll configure a remote interpreter using SSH.

Open the Settings/Preferences dialog Ctrl+Alt+S, go to the Language & Frameworks | Ruby SDK and Gems page, click the button and select Remote Interpreter or Version Manager from the list:
In the invoked dialog, select SSH Credentials and specify parameters in the following way:
- SSH configuration: Click the ellipsis button to create an SSH configuration for connecting to a remote machine.
- Ruby or version manager path: Here you should specify the path to the Ruby interpreter or the version manager executable. In this tutorial, we use rbenv on a remote machine.
After you have specified all the settings, click OK.
If you specified a path to the version manager executable in the previous dialog, RubyMine suggests selecting the required Ruby interpreter. In this step, you need to choose the interpreter used to run a remote application.
Click OK and select the added SDK in the Ruby SDK and Gems page.
The final thing you need to do is to specify mappings between files of a local and remote project. To do this, click the Edit Path Mappings button. In the Edit Project Path Mappings dialog, specify the local and remote project root paths.
tip
If necessary, you may specify not project root paths but only folders containing sources required for debugging.
In our case, the paths will look as follows:
- Local Path: /Users/jetbrains/RubymineProjects/sample_rails_app
- Remote Path: /home/deploy/sample_rails_app
Click OK in this dialog and then click OK in the Settings/Preferences dialog. Now we are ready to attach to a remote process and debug the application.

Attach to a remote process

Now we are ready to debug a remote application.

Open the users_controller.rb file and set a breakpoint within the create method next to the line where a new user is created.
Click Run in the main menu and select the Attach to Process… command.
In the invoked dialog, select the remote connection in the SSH group (sample-web-server@22 in our case) and choose the puma process:
The Console tab will display the debugger output:

Debug an application

To debug an application, open the browser on a local machine and specify the application address. In our case, it will be http://sample-web-server:3000.

Click the Sign up now! button. On the Sign up page, enter the required user parameters and click Create my account.

The debugger pauses its session on a breakpoint and enables you to examine the remote application state.

For instance, you can check user parameters specified on the Sign up page.

Troubleshooting

If you encounter any issues on an attempt to attach to a process, try the following solutions:

Make sure that the remote application is run with the same Ruby interpreter as configured for a debugged project.
Try to use the latest debugging gems. To do this, press Ctrl+Shift+A, start typing Experimental Features, and enable the ruby.use.experimental.debugger option.
Try to increase the debug connection timeout. To do this, open the Settings/Preferences dialog Ctrl+Alt+S, go to the Build, Execution, Deployment | Debugger page, and use the Debug connection timeout option.

warning
The Experimental Debugger feature is currently not available if you're using Ruby 3.0.

Thanks for your feedback!

Was this page helpful?

Tutorial: Attach to a remote process﻿

Prerequisites﻿

tip

Clone and run a remote application﻿

Clone a project on a local machine﻿

Configure a remote interpreter﻿

tip

Attach to a remote process﻿

Debug an application﻿

Troubleshooting﻿

warning