diff --git a/docs/ides/gateway.md b/docs/ides/gateway.md index cb5b62be53..3f2afbd9b5 100644 --- a/docs/ides/gateway.md +++ b/docs/ides/gateway.md @@ -1,43 +1,62 @@ # JetBrains Gateway -JetBrains Gateway is a compact desktop app that allows you to work remotely with a JetBrains IDE without even downloading one. [See JetBrains' website to learn about and Gateway.](https://www.jetbrains.com/remote-development/gateway/) +JetBrains Gateway is a compact desktop app that allows you to work remotely with +a JetBrains IDE without even downloading one. [See JetBrains' website to learn +about and Gateway.](https://www.jetbrains.com/remote-development/gateway/) -Gateway can connect to a Coder workspace by using Coder's Gateway plugin or manually setting up an SSH connection. +Gateway can connect to a Coder workspace by using Coder's Gateway plugin or +manually setting up an SSH 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). +> 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. Open Gateway and click the Coder icon to install the Coder plugin. +1. Click the "Coder" icon under Install More Providers at the bottom of the + Gateway home screen +1. Click "Connect to Coder" at the top of the Gateway home screen to launch the + plugin ![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) +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` +> Note the JetBrains IDE is remotely installed into +> `~/.cache/JetBrains/RemoteDev/dist` + +### Update a Coder plugin version + +1. Click the gear icon at the bottom left of the Gateway home screen and then + "Settings" +1. In the Marketplace tab within Plugins, type Coder and if a newer plugin + release is available, click "Update" and "OK" ![Gateway Settings and +Marketplace](../images/gateway/plugin-settings-marketplace.png) ### 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: +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: +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 @@ -52,8 +71,8 @@ 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: +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 @@ -77,37 +96,37 @@ keytool -import -alias coder -file cacert.pem -keystore /Applications/JetBrains\ ## Manually Configuring A JetBrains Gateway Connection -> This is in lieu of using Coder's Gateway plugin which automatically performs these steps. +> 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. 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. 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. 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. +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) + > 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 @@ -121,7 +140,9 @@ 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. +> 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) +[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. diff --git a/docs/images/gateway/plugin-connect-to-coder.png b/docs/images/gateway/plugin-connect-to-coder.png index 11cecf4ad6..295efa7897 100644 Binary files a/docs/images/gateway/plugin-connect-to-coder.png and b/docs/images/gateway/plugin-connect-to-coder.png differ diff --git a/docs/images/gateway/plugin-ide-list.png b/docs/images/gateway/plugin-ide-list.png index 40b9f2f71b..0f767abfd0 100644 Binary files a/docs/images/gateway/plugin-ide-list.png and b/docs/images/gateway/plugin-ide-list.png differ diff --git a/docs/images/gateway/plugin-select-ide.png b/docs/images/gateway/plugin-select-ide.png index b138b7b2a4..bc4e6cb1ee 100644 Binary files a/docs/images/gateway/plugin-select-ide.png and b/docs/images/gateway/plugin-select-ide.png differ diff --git a/docs/images/gateway/plugin-session-token.png b/docs/images/gateway/plugin-session-token.png index c233fd0c27..b13d2fe128 100644 Binary files a/docs/images/gateway/plugin-session-token.png and b/docs/images/gateway/plugin-session-token.png differ diff --git a/docs/images/gateway/plugin-settings-marketplace.png b/docs/images/gateway/plugin-settings-marketplace.png index 58ccf81559..7973fa9981 100644 Binary files a/docs/images/gateway/plugin-settings-marketplace.png and b/docs/images/gateway/plugin-settings-marketplace.png differ