diff --git a/docs/ides/gateway.md b/docs/ides/gateway.md index 43d848331e..cb5b62be53 100644 --- a/docs/ides/gateway.md +++ b/docs/ides/gateway.md @@ -4,7 +4,80 @@ 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 +## Using Coder's JetBrains Gateway Plugin + +> 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" +1. In the Marketplace tab within Plugins, type Coder and then click "Install" and "OK" + ![Gateway Settings and Marketplace](../images/gateway/plugin-settings-marketplace.png) +1. Click the new "Coder" icon on the Gateway home screen + ![Gateway Connect to Coder](../images/gateway/plugin-connect-to-coder.png) +1. Enter your Coder deployment's Access Url and click "Connect" then paste the Session Token and click "OK" + ![Gateway Session Token](../images/gateway/plugin-session-token.png) +1. Click the "+" icon to open a browser and go to the templates page in your Coder deployment to create a workspace +1. If a workspace already exists but is stopped, click the green arrow to start the workspace +1. Once the workspace status says Running, click "Select IDE and Project" + ![Gateway IDE List](../images/gateway/plugin-select-ide.png) +1. Select the JetBrains IDE for your project and the project directory then click "Start IDE and connect" + ![Gateway Select IDE](../images/gateway/plugin-ide-list.png) + ![Gateway IDE Opened](../images/gateway/gateway-intellij-opened.png) + +> Note the JetBrains IDE is remotely installed into `~/.cache/JetBrains/RemoteDev/dist` + +### 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: + +```console +Failed to configure connection to https://coder.internal.enterprise/: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target +``` + +To resolve this issue, you will need to add Coder's certificate to the Java trust store +present on your local machine. Here is the default location of the trust store for +each OS: + +```console +# Linux +/jbr/lib/security/cacerts + +# macOS +/jbr/lib/security/cacerts +/Library/Application Support/JetBrains/Toolbox/apps/JetBrainsGateway/ch-0//JetBrains Gateway.app/Contents/jbr/Contents/Home/lib/security/cacerts # Path for Toolbox installation + +# Windows +C:\Program Files (x86)\\jre\lib\security\cacerts +%USERPROFILE%\AppData\Local\JetBrains\Toolbox\bin\jre\lib\security\cacerts # Path for Toolbox installation +``` + +To add the certificate to the keystore, you can use the `keytool` utility that ships +with Java: + +```console +keytool -import -alias coder -file -keystore /path/to/trust/store +``` + +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 + +# 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) @@ -52,68 +125,3 @@ cd /opt/idea/bin [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). - -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" -1. In the Marketplace tab within Plugins, type Coder and then click "Install" and "OK" - ![Gateway Settings and Marketplace](../images/gateway/plugin-settings-marketplace.png) -1. Click the new "Coder" icon on the Gateway home screen - ![Gateway Connect to Coder](../images/gateway/plugin-connect-to-coder.png) -1. Enter your Coder deployment's Access Url and click "Connect" then paste the Session Token and click "OK" - ![Gateway Session Token](../images/gateway/plugin-session-token.png) -1. Click the "+" icon to open a browser and go to the templates page in your Coder deployment to create a workspace -1. If a workspace already exists but is stopped, click the green arrow to start the workspace -1. Once the workspace status says Running, click "Select IDE and Project" - ![Gateway IDE List](../images/gateway/plugin-select-ide.png) -1. Select the JetBrains IDE for your project and the project directory then click "Start IDE and connect" - ![Gateway Select IDE](../images/gateway/plugin-ide-list.png) - ![Gateway IDE Opened](../images/gateway/gateway-intellij-opened.png) - -> Note the JetBrains IDE is remotely installed into `~/.cache/JetBrains/RemoteDev/dist` - -## Configuring Gateway 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: - -```console -Failed to configure connection to https://coder.internal.enterprise/: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target -``` - -To resolve this issue, you will need to add Coder's certificate to the Java trust store -present on your local machine. Here is the default location of the trust store for -each OS: - -```console -# Linux -/jbr/lib/security/cacerts - -# macOS -/jbr/lib/security/cacerts -/Library/Application Support/JetBrains/Toolbox/apps/JetBrainsGateway/ch-0//JetBrains Gateway.app/Contents/jbr/Contents/Home/lib/security/cacerts # Path for Toolbox installation - -# Windows -C:\Program Files (x86)\\jre\lib\security\cacerts -%USERPROFILE%\AppData\Local\JetBrains\Toolbox\bin\jre\lib\security\cacerts # Path for Toolbox installation -``` - -To add the certificate to the keystore, you can use the `keytool` utility that ships -with Java: - -```console -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: - -```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 - -# 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 -```