move JetBrains offline steps to separate doc; update links

EdwardAngert · EdwardAngert · commit b5e80079762d · 2025-01-03T15:14:33.000Z
diff --git a/docs/changelogs/v2.1.5.md b/docs/changelogs/v2.1.5.md
@@ -54,7 +54,7 @@
 <!-- markdown-link-check-disable -->
 
 - Add
-[JetBrains Gateway Offline Mode](https://coder.com/docs/user-guides/workspace-access/jetbrains.md#jetbrains-gateway-in-an-offline-environment)
+[JetBrains Gateway Offline Mode](https://coder.com/docs/user-guides/workspace-access/jetbrains/jetbrains-offline.md)
 config steps (#9388) (@ericpaulsen)
 <!-- markdown-link-check-enable -->
 - Describe
diff --git a/docs/install/offline.md b/docs/install/offline.md
@@ -249,7 +249,7 @@ Coder is installed.
 ## JetBrains IDEs
 
 Gateway, JetBrains' remote development product that works with Coder,
-[has documented offline deployment steps.](../user-guides/workspace-access/jetbrains.md#jetbrains-gateway-in-an-offline-environment)
+[has documented offline deployment steps.](../user-guides/workspace-access/jetbrains/jetbrains-offline.md)
 
 ## Microsoft VS Code Remote - SSH
 
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -124,7 +124,14 @@
 						{
 							"title": "JetBrains IDEs",
 							"description": "Use JetBrains IDEs with Gateway",
-							"path": "./user-guides/workspace-access/jetbrains.md"
+							"path": "./user-guides/workspace-access/jetbrains/index.md",
+							"children": [
+								{
+									"title": "JetBrains Gateway in an offline environment",
+									"description": "Use JetBrains Gateway in an offline environment",
+									"path": "./user-guides/workspace-access/jetbrains/jetbrains-offline.md"
+								}
+							]
 						},
 						{
 							"title": "Remote Desktop",
diff --git a/docs/user-guides/workspace-access/index.md b/docs/user-guides/workspace-access/index.md
@@ -86,10 +86,10 @@ IDEs are supported for remote development:
 - Rider
 - RubyMine
 - WebStorm
-- [JetBrains Fleet](./jetbrains.md#jetbrains-fleet)
+- [JetBrains Fleet](./jetbrains/index.md#jetbrains-fleet)
 
-Read our [docs on JetBrains Gateway](./jetbrains.md) for more information on
-connecting your JetBrains IDEs.
+Read our [docs on JetBrains Gateway](./jetbrains/index.md) for more information
+on connecting your JetBrains IDEs.
 
 ## code-server
 
diff --git a/docs/user-guides/workspace-access/jetbrains/index.md b/docs/user-guides/workspace-access/jetbrains/index.md
@@ -223,163 +223,6 @@ 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.
 
-## JetBrains Gateway in an offline environment
-
-In networks that restrict access to the internet, you will need to leverage the
-JetBrains Client Installer to download and save the IDE clients locally. Please
-see the
-[JetBrains documentation for more information](https://www.jetbrains.com/help/idea/fully-offline-mode.html).
-
-### Configuration Steps
-
-The Coder team built a POC of the JetBrains Gateway Offline Mode solution. Here
-are the steps we took (and "gotchas"):
-
-### 1. Deploy the server and install the Client Downloader
-
-We deployed a simple Ubuntu VM and installed the JetBrains Client Downloader
-binary. Note that the server must be a Linux-based distribution.
-
-```shell
-wget https://download.jetbrains.com/idea/code-with-me/backend/jetbrains-clients-downloader-linux-x86_64-1867.tar.gz && \
-tar -xzvf jetbrains-clients-downloader-linux-x86_64-1867.tar.gz
-```
-
-### 2. Install backends and clients
-
-JetBrains Gateway requires both a backend to be installed on the remote host
-(your Coder workspace) and a client to be installed on your local machine. You
-can host both on the server in this example.
-
-See here for the full
-[JetBrains product list and builds](https://data.services.jetbrains.com/products).
-Below is the full list of supported `--platforms-filter` values:
-
-```console
-windows-x64, windows-aarch64, linux-x64, linux-aarch64, osx-x64, osx-aarch64
-```
-
-To install both backends and clients, you will need to run two commands.
-
-**Backends**
-
-```shell
-mkdir ~/backends
-./jetbrains-clients-downloader-linux-x86_64-1867/bin/jetbrains-clients-downloader --products-filter <product-code> --build-filter <build-number> --platforms-filter linux-x64,windows-x64,osx-x64 --download-backends ~/backends
-```
-
-**Clients**
-
-This is the same command as above, with the `--download-backends` flag removed.
-
-```shell
-mkdir ~/clients
-./jetbrains-clients-downloader-linux-x86_64-1867/bin/jetbrains-clients-downloader --products-filter <product-code> --build-filter <build-number> --platforms-filter linux-x64,windows-x64,osx-x64 ~/clients
-```
-
-We now have both clients and backends installed.
-
-### 3. Install a web server
-
-You will need to run a web server in order to serve requests to the backend and
-client files. We installed `nginx` and setup an FQDN and routed all requests to
-`/`. See below:
-
-```console
-server {
-        listen 80 default_server;
-        listen [::]:80 default_server;
-
-        root /var/www/html;
-
-        index index.html index.htm index.nginx-debian.html;
-
-        server_name _;
-
-        location / {
-                root /home/ubuntu;
-        }
-}
-```
-
-Then, configure your DNS entry to point to the IP address of the server. For the
-purposes of the POC, we did not configure TLS, although that is a supported
-option.
-
-### 4. Add Client Files
-
-You will need to add the following files on your local machine in order for
-Gateway to pull the backend and client from the server.
-
-```shell
-$ cat productsInfoUrl # a path to products.json that was generated by the backend's downloader (it could be http://, https://, or file://)
-
-https://internal.site/backends/<PRODUCT_CODE>/products.json
-
-$ cat clientDownloadUrl # a path for clients that you got from the clients' downloader (it could be http://, https://, or file://)
-
-https://internal.site/clients/
-
-$ cat jreDownloadUrl # a path for JBR that you got from the clients' downloader (it could be http://, https://, or file://)
-
-https://internal.site/jre/
-
-$ cat pgpPublicKeyUrl # a URL to the KEYS file that was downloaded with the clients builds.
-
-https://internal.site/KEYS
-```
-
-The location of these files will depend upon your local operating system:
-
-**macOS**
-
-```console
-# User-specific settings
-/Users/UserName/Library/Application Support/JetBrains/RemoteDev
-# System-wide settings
-/Library/Application Support/JetBrains/RemoteDev/
-```
-
-**Linux**
-
-```console
-# User-specific settings
-$HOME/.config/JetBrains/RemoteDev
-# System-wide settings
-/etc/xdg/JetBrains/RemoteDev/
-```
-
-**Windows**
-
-```console
-# User-specific settings
-HKEY_CURRENT_USER registry
-# System-wide settings
-HKEY_LOCAL_MACHINE registry
-```
-
-Additionally, create a string for each setting with its appropriate value in
-`SOFTWARE\JetBrains\RemoteDev`:
-
-![Alt text](../../images/gateway/jetbrains-offline-windows.png)
-
-### 5. Setup SSH connection with JetBrains Gateway
-
-With the server now configured, you can now configure your local machine to use
-Gateway. Here is the documentation to
-[setup SSH config via the Coder CLI](../../user-guides/workspace-access/index.md#configure-ssh).
-On the Gateway side, follow our guide here until step 16.
-
-Instead of downloading from jetbrains.com, we will point Gateway to our server
-endpoint. Select `Installation options...` and select `Use download link`. Note
-that the URL must explicitly reference the archive file:
-
-![Offline Gateway](../../images/gateway/offline-gateway.png)
-
-Click `Download IDE and Connect`. Gateway should now download the backend and
-clients from the server into your remote workspace and local machine,
-respectively.
-
 ## JetBrains Fleet
 
 JetBrains Fleet is a code editor and lightweight IDE designed to support various
diff --git a/docs/user-guides/workspace-access/jetbrains/jetbrains-offline.md b/docs/user-guides/workspace-access/jetbrains/jetbrains-offline.md
@@ -0,0 +1,156 @@
+# JetBrains Gateway in an offline environment
+
+In networks that restrict access to the internet, you will need to leverage the
+JetBrains Client Installer to download and save the IDE clients locally. Please
+see the
+[JetBrains documentation for more information](https://www.jetbrains.com/help/idea/fully-offline-mode.html).
+
+## Configuration Steps
+
+The Coder team built a POC of the JetBrains Gateway Offline Mode solution. Here
+are the steps we took (and "gotchas"):
+
+## 1. Deploy the server and install the Client Downloader
+
+We deployed a simple Ubuntu VM and installed the JetBrains Client Downloader
+binary. Note that the server must be a Linux-based distribution.
+
+```shell
+wget https://download.jetbrains.com/idea/code-with-me/backend/jetbrains-clients-downloader-linux-x86_64-1867.tar.gz && \
+tar -xzvf jetbrains-clients-downloader-linux-x86_64-1867.tar.gz
+```
+
+## 2. Install backends and clients
+
+JetBrains Gateway requires both a backend to be installed on the remote host
+(your Coder workspace) and a client to be installed on your local machine. You
+can host both on the server in this example.
+
+See here for the full
+[JetBrains product list and builds](https://data.services.jetbrains.com/products).
+Below is the full list of supported `--platforms-filter` values:
+
+```console
+windows-x64, windows-aarch64, linux-x64, linux-aarch64, osx-x64, osx-aarch64
+```
+
+To install both backends and clients, you will need to run two commands.
+
+**Backends**
+
+```shell
+mkdir ~/backends
+./jetbrains-clients-downloader-linux-x86_64-1867/bin/jetbrains-clients-downloader --products-filter <product-code> --build-filter <build-number> --platforms-filter linux-x64,windows-x64,osx-x64 --download-backends ~/backends
+```
+
+**Clients**
+
+This is the same command as above, with the `--download-backends` flag removed.
+
+```shell
+mkdir ~/clients
+./jetbrains-clients-downloader-linux-x86_64-1867/bin/jetbrains-clients-downloader --products-filter <product-code> --build-filter <build-number> --platforms-filter linux-x64,windows-x64,osx-x64 ~/clients
+```
+
+We now have both clients and backends installed.
+
+## 3. Install a web server
+
+You will need to run a web server in order to serve requests to the backend and
+client files. We installed `nginx` and setup an FQDN and routed all requests to
+`/`. See below:
+
+```console
+server {
+        listen 80 default_server;
+        listen [::]:80 default_server;
+
+        root /var/www/html;
+
+        index index.html index.htm index.nginx-debian.html;
+
+        server_name _;
+
+        location / {
+                root /home/ubuntu;
+        }
+}
+```
+
+Then, configure your DNS entry to point to the IP address of the server. For the
+purposes of the POC, we did not configure TLS, although that is a supported
+option.
+
+## 4. Add Client Files
+
+You will need to add the following files on your local machine in order for
+Gateway to pull the backend and client from the server.
+
+```shell
+$ cat productsInfoUrl # a path to products.json that was generated by the backend's downloader (it could be http://, https://, or file://)
+
+https://internal.site/backends/<PRODUCT_CODE>/products.json
+
+$ cat clientDownloadUrl # a path for clients that you got from the clients' downloader (it could be http://, https://, or file://)
+
+https://internal.site/clients/
+
+$ cat jreDownloadUrl # a path for JBR that you got from the clients' downloader (it could be http://, https://, or file://)
+
+https://internal.site/jre/
+
+$ cat pgpPublicKeyUrl # a URL to the KEYS file that was downloaded with the clients builds.
+
+https://internal.site/KEYS
+```
+
+The location of these files will depend upon your local operating system:
+
+**macOS**
+
+```console
+# User-specific settings
+/Users/UserName/Library/Application Support/JetBrains/RemoteDev
+# System-wide settings
+/Library/Application Support/JetBrains/RemoteDev/
+```
+
+**Linux**
+
+```console
+# User-specific settings
+$HOME/.config/JetBrains/RemoteDev
+# System-wide settings
+/etc/xdg/JetBrains/RemoteDev/
+```
+
+**Windows**
+
+```console
+# User-specific settings
+HKEY_CURRENT_USER registry
+# System-wide settings
+HKEY_LOCAL_MACHINE registry
+```
+
+Additionally, create a string for each setting with its appropriate value in
+`SOFTWARE\JetBrains\RemoteDev`:
+
+![Alt text](../../images/gateway/jetbrains-offline-windows.png)
+
+## 5. Setup SSH connection with JetBrains Gateway
+
+With the server now configured, you can now configure your local machine to use
+Gateway. Here is the documentation to
+[setup SSH config via the Coder CLI](../../user-guides/workspace-access/index.md#configure-ssh).
+On the Gateway side, follow our guide here until step 16.
+
+Instead of downloading from jetbrains.com, we will point Gateway to our server
+endpoint. Select `Installation options...` and select `Use download link`. Note
+that the URL must explicitly reference the archive file:
+
+![Offline Gateway](../../images/gateway/offline-gateway.png)
+
+Click `Download IDE and Connect`. Gateway should now download the backend and
+clients from the server into your remote workspace and local machine,
+respectively.
diff --git a/docs/user-guides/workspace-lifecycle.md b/docs/user-guides/workspace-lifecycle.md
@@ -55,7 +55,7 @@ contain some computational resource to run the Coder agent process.
 
 The provisioned workspace's computational resources start the agent process,
 which opens connections to your workspace via SSH, the terminal, and IDES such
-as [JetBrains](./workspace-access/jetbrains.md) or
+as [JetBrains](./workspace-access/jetbrains/index.md) or
 [VSCode](./workspace-access/vscode.md).
 
 Once started, the Coder agent is responsible for running your workspace startup
