Getting started with remote development
You can connect to a remote server using the SSH connection to develop, run and deploy your project.
Prerequisites
Before you start developing on the remote machine, make sure you have the following:
Remote machine (a target for an IDE) meets the minimum recommended requirements that can be found in IDEs articles.
You have installed a compatible SSH server on the Linux platform.
The Linux platform has any recent Linux AMD64 distribution such as Ubuntu 16.04+, RHEL/Centos 7+, and so on. There is no arm64 support yet. We recommend using machines with 2+ cores, 4GB+ of RAM, and 5GB+ of disk space.
You need to have the sftp subsystem enabled on the remote host. In the current implementation, we use it for the backend deployment.
JetBrains Gateway
JetBrains Gateway is a lightweight launcher that connects a remote server with your local machine, downloads necessary components on the backend, and opens your project in JetBrains Client.
You can use JetBrains Gateway as a standalone launcher or as an entry point from your IDE to connect to a remote server.
Launch JetBrains Gateway and connect to a remote server
Download and install the JetBrains Gateway app.
Alternatively, you can access JetBrains Gateway from the welcome screen of your IDE through the Remote Development option.
In the Remote Development wizard, click Connect via SSH.
On the next page of the wizard, specify the SSH configuration through which you want to connect to a remote server.
Alternatively, click
to open the SSH Configurations dialog and configure the SSH settings.
In the SSH Configurations dialog, add the following information:
Host: specify the address of your remote server.
Port: specify the SSH port, which defaults to
22
.Local port: specify the outgoing port.
For example,
TCP 10.101.0.1:50705->13.49.137.87:22 (ESTABLISHED)
.User name: specify the name of a user that will be used to connect to the remote server.
Authentication type: select one of the following authentication methods:
Password: to access the host with a password. To save the password in PhpStorm, select the Save password checkbox.
Key pair (OpenSSH or PuTTY): to use SSH authentication with a key pair. To apply this authentication method, you must have a private key on the client machine and a public key on the remote server. PhpStorm supports private keys that are generated with the OpenSSH utility.
Specify the path to the file where your private key is stored and type the passphrase (if any) in the corresponding fields. To have PhpStorm remember the passphrase, select the Save passphrase checkbox.
Parse config file ~/.ssh/config: select this option if you want JetBrains Gateway to use the
.ssh/config
file.
Test Connection: click this button to see whether the connection is established.
Connection Parameters: use this section to configure additional parameters for the connection.
HTTP/SOCKS Proxy: use this section to configure proxy settings. For more information, refer to Proxy settings.
Click OK to save the changes and return to the Welcome to JetBrains Gateway dialog.
Click Check Connection and Continue to check whether the connection is established.
On the next page, specify the PhpStorm version to download to the remote server. JetBrains Gateway displays a list of the IDEs versions that are available for downloading and the already installed ones.
You can also use "Other options" for setting the alternative sources of IDE installers.
The version of JetBrains Client downloaded to your local machine always matches the remote IDE version.
![the IDE version the IDE version](https://resources.jetbrains.com/help/img/idea/2022.1/ps_remote_dev_ide_version.png)
By default, the downloaded PhpStorm is located in the following folder on the remote server: ~/.cache/JetBrains/RemoteDev/dist. However, you can change it and install PhpStorm into a custom location with the following steps:
Click Other options and select the Customize install path option.
In the Install path field add the needed location for the installation.
![Install to custom location Install to custom location](https://resources.jetbrains.com/help/img/idea/2022.1/rd_install_to_custom_location.png)
Add the path to your project on the remote host.
![Path to remote project Path to remote project](https://resources.jetbrains.com/help/img/idea/2022.1/ps_remote_dev_path_to_remote_project.png)
Click Download and Start IDE.
JetBrains Gateway downloads the IDE, and opens your remote project in JetBrains Client. The connection is shown in the JetBrains Gateway window, from which you can connect to other IDEs or disable the connection. This window is hidden to tray by default.
![Gateway window Gateway window](https://resources.jetbrains.com/help/img/idea/2022.1/ps_remote_dev_gateway_window.png)
Open recent projects
In the JetBrains Gateway wizard, select SSH from the options on the left.
In the search field enter the name of your project to quickly navigate to it.
If you need to quickly access the terminal, click
.
Stop the running instance
In the JetBrains Gateway wizard, select SSH from the options on the left.
When your remote session is active, the Running indicator is displayed next to the project.
Click
next to the project and select Stop Instance to stop the remote session for that project.
You can also select Remove from Recent Projects to remove the project listed on the page altogether.
Connect to a remote project at manually launched remote IDE
If you already have PhpStorm installed on your remote server, you can launch it manually and connect to the remote project started in that IDE. It works the same way as from JetBrains Gateway.
Use this approach if your company has a custom orchestration or in case your remote IDE starts automatically on its side.
In short, the process can be described as "Start backend project in remote IDE -> select one of the connection links generated by the backend -> open it on your local machine".
The main script to run a remote IDE is "remote-dev-server.sh", located in the "bin" subdirectory of your unpacked IDE.
Connect to remote IDE
Ensure you have downloaded and installed standalone or an IDE with this bundled plugin on your local machine.
Ensure you have an SSH connection to the remote machine and the PhpStorm IDE on it.
In the remote server's terminal, run the following command:
remote-dev-server.sh run /path_to_project/ --ssh-link-host host_server_address --ssh-link-user remote_side_user --ssh-link-port ssh_connection_portSee example:
If you don't pass the parameters, the script will use the default ones: 22 for port, system user's username, and host from the "hostname" command.
~/.cache/JetBrains/RemoteDev/dist/f8a03266ddbb1_PhpStorm-213.5744.147/bin/remote-dev-server.sh run ~/PhpstormProjects/phpstorm-workshop/ --ssh-link-host ec2-13-50-136-85.eu-north-1.compute.amazonaws.comIf the project starts successfully, as an output, you receive in the terminal 3 links:
Join link: tcp://127.0.0.1:5990...[ ] - contains the local address and port where the remote IDE is listening now.
To use it, ensure the remote machine should be accessible by this local address - for example, for inside-Docker IDE with forwarded/open ports.
Http link: https://code-with-me.jetbrains.com/remoteDev...[ ] - contains information about your host-port-user, IDE and its version.
When opening in your local browser, it displays a welcome page and tries to call the local Gateway application with pre-filled connection settings values.
If no Gateway app is found on the local machine, you'll be able to download it from the welcome page.
Gateway link: jetbrains-gateway://connect#idePath... [ ] - also contains information about your host-port-user, IDE and its version.
When opening in your local browser, it launches the local Gateway app directly without a welcome page.
Copy the generated link and paste it into your local browser and allow it to launch Open JetBrains Gateway
All these links can be open also in the already launched JetBrains Gateway.
For this, on the Gateway welcome screen, paste a link in the "Connect to a Running IDE" field, click Connect.
PhpStorm downloads JetBrains Client of the required version and opens the remote project in it.
Connect to Gitpod
JetBrains Gateway supports integration with Gitpod, an open-source orchestration and provisioning platform for automated developer environments.
Gitpod is available in JetBrains Gateway as a plugin that you can use to connect to the existing Gitpod workspaces or create a new one and work with it in PhpStorm.
Connect to your workspace on Gitpod
Launch JetBrains Gateway.
Select Remote Development from the options on the left.
In the Install More Providers section, locate Gitpod and click Install Plugin.
The installed plugin is added and you can locate it under the Remote Development node as well as in the Install More Providers section.
After the plugin installation, from the options on the right, locate Gitpod and click Connect to Gitpod. .
In the window that opens, select the IDE with which you want to work.
Click New Workspace.
JetBrains Gateway connects you to your Gitpod workspace in browser. Gitpod prepares the workspace and displays a notification about opening the workspace inside JetBrains Client.
Click Allow and then Yes in the authentication dialog.
The connection is established and the workspace with the project is opened in JetBrains Client where you can work further inside the IDE.
The created workspace is added to the Recent workspaces section. If you have existing workspaces they are added to the list of recent workspaces and you can connect to them at any time by clicking Connect against the needed workspace.
If you want to connect to JetBrains Gateway directly from the Gitpod, follow the Gitpod documentation.
Install plugins
You can install plugins that you need on the remote server. Note that plugins are installed per project. Each time you create a remote connection for a new project, you need to install the desired plugin.
Based on the scenario that you use for downloading PhpStorm on the remote server, you either install the plugin via the command line or use the UI of a remote project for your installation.
Install a plugin via the command line
If you manually configure PhpStorm on the remote server, use the following steps to add plugins:
From the JetBrains Marketplace page, find a page of the required plugin, select the Versions tab, and click any version to copy
pluginId
(short name such asNodeJS
) of the plugin you want to install.Open the remote server go to the PhpStorm instance where your project resides, and for which you want to download and install a third-party plugin.
By default, the downloaded PhpStorm instances are located in the following directory:
~/.cache/JetBrains/RemoteDev/distAdd the following command:
bin/remote-dev-server.sh installPlugins PROJECT_PATH pluginId(where
PROJECT_PATH
is a path to your remote project andpluginId
is an ID you got from the JetBrains Marketplace page.)After the installation, unpack the downloaded plugin's archive.
By default, the installed plugin is placed into the following folder on the backend:
~/.cache/JetBrains/RemoteDev-IU/PROJECT_PATH/plugins/Continue with launching JetBrains Gateway and opening the remote project with the remotely installed plugin.
Install a plugin via UI
If you use JetBrains Gateway to download PhpStorm to a remote server, use the following steps to install plugins.
Open a remote project in JetBrains Client.
Press Ctrl+Alt+S to open the IDE settings and select
.Download the needed plugin the same way as you would in a regular PhpStorm project.
For more information on regular plugin installation, refer to Install plugins.
After you download and enable the plugin, click OK to save the changes.
The plugin is installed remotely. However, keep in mind that the plugin is installed per project.
Work inside the remote project
A remote project gets opened in JetBrains Client as it would be opened in your local PhpStorm IDE. You can develop it like any other local project: edit code, run applications, debug, and deploy.
If you want to find more about the Remote Development processes and architecture in general, refer to Remote development overview.
Add VM options
You can adjust VM options for the remote project, especially if you want to increase the -Xmx
memory size when working with a larger project. You need to perform those actions and save your changes on the remote server.
From the main menu, select
.Edit the
phpstorm64.vmoptions
file.For example, change the
-Xmx2048
option to-Xmx3072
.For more detailed information on VM options, refer to Advanced configuration.
Restart your IDE on the remote server to see the changes.
Close the Remote Development session
Click
to close the remote session window.
You are returned to the JetBrains Gateway welcome screen where you can use the Recent SSH projects page to reconnect to your remote session or stop the running instance.
Create multiple connections
You can create multiple connections to the same remote host and the same version of the IDE. You can also have connections with different IDE versions and remote hosts.
Connect and open a remote session.
Since JetBrains Gateway is constantly active once you have connected to the remote server, you can click its icon to open the JetBrains Gateway welcome screen and configure other connections.
If you connect to the same IDE version, then JetBrains Client will be opened as an instance of the same process. If you connect to a different remote host or IDE version, a different remote session will be launched.
Backend control center
When you work with your remote project, you can check the status of the remote server. That means you can check the CPU load, disk, and memory consumption on your backend. You can also add heap size and restart the remote backend right from JetBrains Client.
After opening your remote project, the name of your backend, memory and latency indicators are displayed on the main toolbar.
![main toolbar main toolbar](https://resources.jetbrains.com/help/img/idea/2022.1/backend_toolbar.png)
Work with the control center window
In JetBrains Client, on the main toolbar, click the name of the remote server to open the Connection Details window.
On the Performance tab, check the status of CPU load, memory consumptions, and the disk space.
Ping: this is a time indicator that shows how much time it takes to transfer data between JetBrains Client and the remote server using RD protocol.
CPU Load: this is an indicator of how many processes are executed by CPU.
Memory (RAM): this is an indicator that shows the RAM state of the remote server. If the memory limit is reached, you need to access your remote server and increase RAM or terminate processes that consume it.
Disk: this is an indicator of how much disk space is used by the remote server.
Click the Output tab to see the last 2500 symbols of the log file from the remote server.
This information helps you to see the end of log file and potential errors or issues that might have occurred.
If you want to increase the heap memory size, click the Settings tab and in the Maximum heap size field, add the needed amount of memory and click Save and Restart to apply the changes. Alternatively, you can click Save if you don't want to restart the backend immediately.
If you encounter a problem working in JetBrains Client, you can open a main tool window of the backend IDE and try to fix your problem there.
Access the backend IDE UI
In JetBrains Client, on the main toolbar, click the name of the remote server to open the Connection Details window.
In Connection Details window, click
and select Show Main Window.
The main window of the backend IDE gets projected. Now you can use it to access remote settings and configure various remote options if you couldn't do that in JetBrains Client.
SSH forwarding settings
The SSH forwarding settings let you use SSH key forwarding to authenticate access to Git repositories from your remote server. Alternatively, you can use the SSH-agent helper to achieve the same result.
Access SSH forwarding settings
Press Ctrl+Alt+S to open the IDE settings and select
.From the options on the right, select Enable SSH agent Forwarding and click OK to save the changes.