opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): Added macOS self-signed cert add step and moved plugin docs to top (#7859)

Browse Source
This commit is contained in:
sharkymark
2023-06-05 19:59:01 -04:00
committed by GitHub
parent fa8f50a169
commit 8e655b42b1
1 changed files with 74 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ides/gateway.md
+74 -66
View File
@@ -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
<Gateway installation directory>/jbr/lib/security/cacerts
# macOS
<Gateway installation directory>/jbr/lib/security/cacerts
/Library/Application Support/JetBrains/Toolbox/apps/JetBrainsGateway/ch-0/<app-id>/JetBrains Gateway.app/Contents/jbr/Contents/Home/lib/security/cacerts # Path for Toolbox installation
# Windows
C:\Program Files (x86)\<Gateway installation directory>\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 <certificate> -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 <version>/jbr/bin/keytool.exe' 'C:\Program Files\JetBrains\JetBrains Gateway <version>/jre/lib/security/cacerts' -import -alias coder -file <cert>
# command for Toolbox installation
& '%USERPROFILE%\AppData\Local\JetBrains\Toolbox\apps\Gateway\ch-0\<VERSION>\jbr\bin\keytool.exe' '%USERPROFILE%\AppData\Local\JetBrains\Toolbox\bin\jre\lib\security\cacerts' -import -alias coder -file <cert>
```
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
<Gateway installation directory>/jbr/lib/security/cacerts
# macOS
<Gateway installation directory>/jbr/lib/security/cacerts
/Library/Application Support/JetBrains/Toolbox/apps/JetBrainsGateway/ch-0/<app-id>/JetBrains Gateway.app/Contents/jbr/Contents/Home/lib/security/cacerts # Path for Toolbox installation
# Windows
C:\Program Files (x86)\<Gateway installation directory>\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 <certificate> -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 <version>/jbr/bin/keytool.exe' 'C:\Program Files\JetBrains\JetBrains Gateway <version>/jre/lib/security/cacerts' -import -alias coder -file <cert>
# command for Toolbox installation
& '%USERPROFILE%\AppData\Local\JetBrains\Toolbox\apps\Gateway\ch-0\<VERSION>\jbr\bin\keytool.exe' '%USERPROFILE%\AppData\Local\JetBrains\Toolbox\bin\jre\lib\security\cacerts' -import -alias coder -file <cert>
```