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:
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.
Configure a remote interpreter
In this part, we’ll configure a remote interpreter using SSH.
Open the Settings 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.
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.
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.debuggeroption.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.