diff --git a/docs/ides/gateway.md b/docs/ides/gateway.md index 43d848331e00d..cb5b62be53f3f 100644 --- a/docs/ides/gateway.md +++ b/docs/ides/gateway.md @@ -4,58 +4,9 @@ JetBrains Gateway is a compact desktop app that allows you to work remotely with Gateway can connect to a Coder workspace by using Coder's Gateway plugin or manually setting up an SSH connection. -## Creating a new JetBrains Gateway Connection - -1. [Install Gateway](https://www.jetbrains.com/help/idea/jetbrains-gateway.html) -1. [Configure the `coder` CLI](../ides.md#ssh-configuration) -1. Open Gateway, make sure "SSH" is selected under "Remote Development" -1. Click "New Connection" - ![Gateway Home](../images/gateway/gateway-home.png) -1. In the resulting dialog, click the gear icon to the right of "Connection:" - ![Gateway New Connection](../images/gateway/gateway-new-connection.png) -1. Hit the "+" button to add a new SSH connection - ![Gateway Add Connection](../images/gateway/gateway-add-ssh-configuration.png) - -1. For the Host, enter `coder.` -1. For the Port, enter `22` (this is ignored by Coder) -1. For the Username, enter your workspace username -1. For the Authentication Type, select "OpenSSH config and authentication - agent" -1. Make sure the checkbox for "Parse config file ~/.ssh/config" is checked. -1. Click "Test Connection" to validate these settings. -1. Click "OK" - ![Gateway SSH Configuration](../images/gateway/gateway-create-ssh-configuration.png) -1. Select the connection you just added - ![Gateway Welcome](../images/gateway/gateway-welcome.png) -1. Click "Check Connection and Continue" - ![Gateway Continue](../images/gateway/gateway-continue.png) -1. Select the JetBrains IDE for your project and the project directory. - SSH into your server to create a directory or check out code if you haven't already. - ![Gateway Choose IDE](../images/gateway/gateway-choose-ide.png) - > Note the JetBrains IDE is remotely installed into `~/. cache/JetBrains/RemoteDev/dist` -1. Click "Download and Start IDE" to connect. - ![Gateway IDE Opened](../images/gateway/gateway-intellij-opened.png) - -## Using an existing JetBrains installation in the workspace - -If you would like to use an existing JetBrains IDE in a Coder workspace (or you -are air-gapped, and cannot reach jetbrains.com), run the following script in the -JetBrains IDE directory to point the default Gateway directory to the IDE -directory. This step must be done before configuring Gateway. - -```sh -cd /opt/idea/bin -./remote-dev-server.sh registerBackendLocationForGateway -``` - -> Gateway only works with paid versions of JetBrains IDEs so the script will not be located in the `bin` directory of JetBrains Community editions. - -[Here is the JetBrains article](https://www.jetbrains.com/help/idea/remote-development-troubleshooting.html#setup:~:text=Can%20I%20point%20Remote%20Development%20to%20an%20existing%20IDE%20on%20my%20remote%20server%3F%20Is%20it%20possible%20to%20install%20IDE%20manually%3F) -explaining this IDE specification. - ## Using Coder's JetBrains Gateway Plugin -> The Coder plugin is an alpha state. If you experience problems, please [create a GitHub issue](https://github.com/coder/coder/issues) or share in [our Discord channel](https://discord.gg/coder). +> If you experience problems, please [create a GitHub issue](https://github.com/coder/coder/issues) or share in [our Discord channel](https://discord.gg/coder). 1. [Install Gateway](https://www.jetbrains.com/help/idea/jetbrains-gateway.html) 1. Open Gateway and click the gear icon at the bottom left and then "Settings" @@ -75,7 +26,7 @@ explaining this IDE specification. > Note the JetBrains IDE is remotely installed into `~/.cache/JetBrains/RemoteDev/dist` -## Configuring Gateway to use internal certificates +### Configuring the Gateway plugin to use internal certificates When attempting to connect to a Coder deployment that uses internally signed certificates, you may receive the following error in Gateway: @@ -108,8 +59,8 @@ with Java: keytool -import -alias coder -file -keystore /path/to/trust/store ``` -On Windows, you can use `keytool` that ships with the JetBrains Gateway installation. -For example: +You can use `keytool` that ships with the JetBrains Gateway installation. +Windows example: ```powershell & 'C:\Program Files\JetBrains\JetBrains Gateway /jbr/bin/keytool.exe' 'C:\Program Files\JetBrains\JetBrains Gateway /jre/lib/security/cacerts' -import -alias coder -file @@ -117,3 +68,60 @@ For example: # command for Toolbox installation & '%USERPROFILE%\AppData\Local\JetBrains\Toolbox\apps\Gateway\ch-0\\jbr\bin\keytool.exe' '%USERPROFILE%\AppData\Local\JetBrains\Toolbox\bin\jre\lib\security\cacerts' -import -alias coder -file ``` + +macOS example: + +```sh +keytool -import -alias coder -file cacert.pem -keystore /Applications/JetBrains\ Gateway.app/Contents/jbr/Contents/Home/lib/security/cacerts +``` + +## Manually Configuring A JetBrains Gateway Connection + +> This is in lieu of using Coder's Gateway plugin which automatically performs these steps. + +1. [Install Gateway](https://www.jetbrains.com/help/idea/jetbrains-gateway.html) +1. [Configure the `coder` CLI](../ides.md#ssh-configuration) +1. Open Gateway, make sure "SSH" is selected under "Remote Development" +1. Click "New Connection" + ![Gateway Home](../images/gateway/gateway-home.png) +1. In the resulting dialog, click the gear icon to the right of "Connection:" + ![Gateway New Connection](../images/gateway/gateway-new-connection.png) +1. Hit the "+" button to add a new SSH connection + ![Gateway Add Connection](../images/gateway/gateway-add-ssh-configuration.png) + +1. For the Host, enter `coder.` +1. For the Port, enter `22` (this is ignored by Coder) +1. For the Username, enter your workspace username +1. For the Authentication Type, select "OpenSSH config and authentication + agent" +1. Make sure the checkbox for "Parse config file ~/.ssh/config" is checked. +1. Click "Test Connection" to validate these settings. +1. Click "OK" + ![Gateway SSH Configuration](../images/gateway/gateway-create-ssh-configuration.png) +1. Select the connection you just added + ![Gateway Welcome](../images/gateway/gateway-welcome.png) +1. Click "Check Connection and Continue" + ![Gateway Continue](../images/gateway/gateway-continue.png) +1. Select the JetBrains IDE for your project and the project directory. + SSH into your server to create a directory or check out code if you haven't already. + ![Gateway Choose IDE](../images/gateway/gateway-choose-ide.png) + > Note the JetBrains IDE is remotely installed into `~/. cache/JetBrains/RemoteDev/dist` +1. Click "Download and Start IDE" to connect. + ![Gateway IDE Opened](../images/gateway/gateway-intellij-opened.png) + +## Using an existing JetBrains installation in the workspace + +If you would like to use an existing JetBrains IDE in a Coder workspace (or you +are air-gapped, and cannot reach jetbrains.com), run the following script in the +JetBrains IDE directory to point the default Gateway directory to the IDE +directory. This step must be done before configuring Gateway. + +```sh +cd /opt/idea/bin +./remote-dev-server.sh registerBackendLocationForGateway +``` + +> Gateway only works with paid versions of JetBrains IDEs so the script will not be located in the `bin` directory of JetBrains Community editions. + +[Here is the JetBrains article](https://www.jetbrains.com/help/idea/remote-development-troubleshooting.html#setup:~:text=Can%20I%20point%20Remote%20Development%20to%20an%20existing%20IDE%20on%20my%20remote%20server%3F%20Is%20it%20possible%20to%20install%20IDE%20manually%3F) +explaining this IDE specification.