Skip to content

chore(docs): add JetBrains Gateway macOS cert step and move plugin docs to top #7859

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 5, 2023
Merged

chore(docs): add JetBrains Gateway macOS cert step and move plugin docs to top #7859

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 61 additions & 53 deletions docs/ides/gateway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.<workspace name>`
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"
Expand All @@ -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:
Expand Down Expand Up @@ -108,12 +59,69 @@ with Java:
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:
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)
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.<workspace name>`
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.