RubyMine 2022.3 Help

Tutorial: Attach to a remote process

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.

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:

Remote session

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: Clone a repository from the Welcome Screen. In URL, insert the following address: https://github.com/JetBrains/sample_rails_app.git. Then click Clone.

Get from Version Control dialog

Configure a remote interpreter

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

  1. Open the Settings dialog Ctrl+Alt+S, go to the Language & Frameworks | Ruby SDK and Gems page, click the Add button and select Remote Interpreter or Version Manager from the list:

    New remote
  2. In the invoked dialog, select SSH Credentials and specify parameters in the following way:

    Configure Remote Ruby Interpreter
    • 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.

  3. 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.

    Select Distribution

    Click OK and select the added SDK in the Ruby SDK and Gems page.

    Ruby SDK and Gems
  4. 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 Edit Path Mappings button. In the Edit Project Path Mappings dialog, specify the local and remote project root paths.

    Edit Project Path Mappings

    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 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.

  1. Open the users_controller.rb file and set a breakpoint within the create method next to the line where a new user is created.

    Set a breakpoint
  2. Click Run in the main menu and select the Attach to Process… command.

  3. In the invoked dialog, select the remote connection in the SSH group (sample-web-server@22 in our case) and choose the puma process:

    Attach to remote process

    The Console tab will display the debugger output:

    Debug console

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.

Sign up page

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

User credentials

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

Debugging a remote application

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 dialog Ctrl+Alt+S, go to the Build, Execution, Deployment | Debugger page, and use the Debug connection timeout option.

Last modified: 19 January 2023