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.
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:
Note that we’ll attach a debugger to the puma server later using the allocated process identifier (7538 on the screen).
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: Checking 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 New remote from the list:
In the invoked dialog, select SSH Credentials and specify parameters in the following way:
Host: The hostname or IP address of a remote machine. In our tutorial, the hostname is sample-web-server, and the Port is set to the default value.
User name: The username used to authenticate on a remote machine.
Authentication type: In this field, select the Password value to authenticate a user with a password.
Password: Specify a user's password.
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 RVM 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/jetbrains/apps/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 with the identifier allocated during the web server launching (see Clone a project on a local machine):
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.
For instance, you can check user parameters specified on the Sign up page.
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 Enable Experimental Debugger, and make sure that this option is enabled.
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.