From 46f9a4a1ee2ec5b4161081fcee1645a238a2f006 Mon Sep 17 00:00:00 2001
From: Ammar Bandukwala <ammar@ammar.io>
Date: Sun, 7 Aug 2022 22:14:05 +0000
Subject: [PATCH] docs: fix up port-forwarding

- Improve English
- Make new page live in manifest.json
- Add icon
- Outdent page to root
---
 docs/ides.md                             |  7 ++---
 docs/ides/configuring-port-forwarding.md | 34 ------------------------
 docs/images/icons/port-forward.svg       |  1 +
 docs/manifest.json                       |  6 +++++
 docs/port-forwarding.md                  | 33 +++++++++++++++++++++++
 5 files changed, 42 insertions(+), 39 deletions(-)
 delete mode 100644 docs/ides/configuring-port-forwarding.md
 create mode 100644 docs/images/icons/port-forward.svg
 create mode 100644 docs/port-forwarding.md

diff --git a/docs/ides.md b/docs/ides.md
index 59cfb970fae6c..a74ab59144441 100644
--- a/docs/ides.md
+++ b/docs/ides.md
@@ -79,9 +79,6 @@ Connection and connect to your Coder workspace.](./ides/configuring-gateway.md)
 
 Web IDEs (code-server, JetBrains Projector, VNC, etc.) are defined in the template. See [configuring IDEs](./ides/configuring-web-ides.md).
 
-## Port Forwarding
+## Up next
 
-Port Forwarding lets developers securely access processes on their Coder
-workspace from a local machine. A common use case is testing front-end
-applications in a browser at `http://localhost:<yourforwardedport>` See
-[configuring Port Forwarding](./ides/configuring-port-forwarding.md).
+- Learn about [Port Forwarding](./port-forwarding.md)
diff --git a/docs/ides/configuring-port-forwarding.md b/docs/ides/configuring-port-forwarding.md
deleted file mode 100644
index bda25b1f97554..0000000000000
--- a/docs/ides/configuring-port-forwarding.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# Configuring Port Forwarding
-
-There are two ways to forward ports:
-
-- The Coder CLI port-forward command
-- SSH
-
-## The Coder CLI and port-forward
-
-For example:
-
-```console
-coder port-forward mycoderworkspacename --tcp 8000:8000
-```
-
-For more examples, type `coder port-forward --help`
-
-## SSH
-
-Use the Coder CLI to first [configure SSH](../ides.md#ssh-configuration) on your
-local machine. Then run `ssh`. For example:
-
-```console
-ssh -L 8000:localhost:8000 coder.mycoderworkspacename 
-```
-
-## Accessing the forwarded port
-
-After completing either Port Forwarding method, open a web browser on your local
-machine to access the Coder workspace process.
-
-```console
-http://localhost:<yourforwardedport>
-```
diff --git a/docs/images/icons/port-forward.svg b/docs/images/icons/port-forward.svg
new file mode 100644
index 0000000000000..ed916d513e827
--- /dev/null
+++ b/docs/images/icons/port-forward.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 0 24 24" width="24"><path d="M0 0h24v24H0z" fill="none"/><path d="M6 3H3v3c1.66 0 3-1.34 3-3zm8 0h-2c0 4.97-4.03 9-9 9v2c6.08 0 11-4.93 11-11zm-4 0H8c0 2.76-2.24 5-5 5v2c3.87 0 7-3.13 7-7zm0 18h2c0-4.97 4.03-9 9-9v-2c-6.07 0-11 4.93-11 11zm8 0h3v-3c-1.66 0-3 1.34-3 3zm-4 0h2c0-2.76 2.24-5 5-5v-2c-3.87 0-7 3.13-7 7z"/></svg>
diff --git a/docs/manifest.json b/docs/manifest.json
index bd238f03334d5..8a65569c0afb8 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -94,6 +94,12 @@
         }
       ]
     },
+    {
+      "title": "Port Forwarding",
+      "description": "Learn how to forward ports in Coder",
+      "path": "./port-forwarding.md",
+      "icon_path": "./images/icons/port-forward.svg"
+    },
     {
       "title": "Dotfiles",
       "description": "Learn how to personalize your workspace",
diff --git a/docs/port-forwarding.md b/docs/port-forwarding.md
new file mode 100644
index 0000000000000..5e925b8dedbfa
--- /dev/null
+++ b/docs/port-forwarding.md
@@ -0,0 +1,33 @@
+# Port Forwarding
+
+Port forwarding lets developers securely access processes on their Coder
+workspace from a local machine. A common use case is testing web
+applications in a browser.
+
+There are two ways to forward ports in Coder:
+
+- The `coder port-forward` command
+- SSH
+
+The `coder port-forward` command is generally more performant.
+
+## coder port-forward
+
+Forward the remote TCP port `8080` to local port `8000` like so:
+
+```console
+coder port-forward myworkspace --tcp 8000:8080
+```
+
+For more examples, see `coder port-forward --help`.
+
+## SSH
+
+First, [configure SSH](../ides.md#ssh-configuration) on your
+local machine. Then, use `ssh` to forward like so:
+
+```console
+ssh -L 8080:localhost:8000 coder.myworkspace
+```
+
+You can read more on SSH port forwarding [here](https://www.ssh.com/academy/ssh/tunneling/example).