Merge pull request #208 from kinode-dao/hf/hosted-nodes-edits

hosted nodes edits

src/SUMMARY.md

@@ -32,6 +32,7 @@
   - [`dev-ui`](./kit/dev-ui.md)
   - [`inject-message`](./kit/inject-message.md)
   - [`run-tests`](./kit/run-tests.md)
+  - [`connect`](./kit/connect.md)
   - [`reset-cache`](./kit/reset-cache.md)
   - [`boot-real-node`](./kit/boot-real-node.md)
 - [My First Kinode Application](./build-and-deploy-an-app.md)

src/hosted-nodes.md

@@ -26,19 +26,12 @@ As discussed in [Managing Your Kinode](#managing-your-kinode), navigate to:
 4. `Show advanced details`
 
 In the advanced details, note the `SSH Address` and `SSH Password`.
-Here and below, the following SSH details will be assumed (you'll need to replace them with yours from `advanced details`):
-
-Field           | Value
---------------- | -----
-SSH Address     | [email protected]
-SSH Password    | 123456789
-Local HTTP Port | 8099
 
 To access your Kinode remote instance, open a terminal and
 ```bash
-ssh [email protected]
+ssh <SSH Address>
 ```
-where `[email protected]` should be the `user@kinode_name.hosting.kinode.net` in your `SSH Address`.
+where `<SSH Address>` should be replaced with the one from your Valet advanced details.
 You will be prompted for a password: copy-paste the `SSH Password`.
 
 You should now have a different terminal prompt, indicating you have `ssh`d into the remote instance hosting your Kinode.
@@ -49,40 +42,50 @@ Rather than typing in a password to create a SSH connection, you can use a keypa
 
 #### Generating Keypair
 
-https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key
+[How to generate a keypair](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key)
 
 #### `ssh-agent`
 
-https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent
+[How to use `ssh-agent` to store a keypair](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent)
 
 #### SSH Config
 
-https://www.digitalocean.com/community/tutorials/ssh-essentials-working-with-ssh-servers-clients-and-keys#defining-server-specific-connection-information
+[How to use `~/.ssh/config` to make SSH easier to use](https://www.digitalocean.com/community/tutorials/ssh-essentials-working-with-ssh-servers-clients-and-keys#defining-server-specific-connection-information)
 
 #### Adding Public Key to Remote Node
 
-https://www.digitalocean.com/community/tutorials/ssh-essentials-working-with-ssh-servers-clients-and-keys#copying-your-public-ssh-key-to-a-server-with-ssh-copy-id
+[How to add the public key to a remote node to allow login with it](https://www.digitalocean.com/community/tutorials/ssh-essentials-working-with-ssh-servers-clients-and-keys#copying-your-public-ssh-key-to-a-server-with-ssh-copy-id)
 
 ## Using `kit` With Your Hosted Node
 
 `kit` interacts with a Kinode through the Kinode's HTTP RPC.
-However, Kinode limits HTTP RPC access to localhost: remote requests are rejected.
+However, Kinode limits HTTP RPC access to localhost — remote requests are rejected.
 The local limit is a security measure, since the HTTP RPC allows injection of arbitrary messages with "root" capabilities.
 
 To use `kit` with a hosted node, you need to create a SSH tunnel, which maps a port on your local machine to a port on the Kinode's remote host.
 HTTP requests routed to that local port will then appear to the remote host as originating from its localhost.
 
+It is recommended to use [`kit connect`](./kit/connect.md) to create and destroy a SSH tunnel.
+Otherwise, you can also follow the instructions below to do it yourself.
+
 Create a SSH tunnel like so (again, replacing [assumed values with those in your `advanced details`](#accessing-your-kinodes-terminal)):
 ```bash
-ssh -L 9090:localhost:8099 [email protected] -f -N
+ssh -L 9090:localhost:<HTTP port> <SSH address>
+```
+e.g.,
+``` bash
+ssh -L 9090:localhost:8099 [email protected]
 ```
+
 or, if you've added your host to your [`~/.ssh/config`](#ssh-config),
 ```bash
-ssh -L 9090:localhost:8099 template -f -N
+ssh -L 9090:localhost:<HTTP port> <Host>
 ```
-
-Now, `kit` requests sent to `9090` will be routed to the remote Kinode, e.g.,
+You should see a `ssh` session open.
+While this session is open, `kit` requests sent to `9090` will be routed to the remote Kinode, e.g.,
 ```
 kit s foo -p 9090
 ```
 will function the same as for a locally-hosted Kinode.
+
+Closing the `ssh` connections with `Ctrl+D` or typing `exit` will close the tunnel.

src/kit-dev-toolkit.md

@@ -15,5 +15,6 @@
 * [`kit dev-ui`](./kit/dev-ui.md)
 * [`kit inject-message`](./kit/inject-message.md)
 * [`kit run-tests`](./kit/run-tests.md)
+* [`kit connect`](./kit/connect.md)
 * [`kit reset-cache`](./kit/reset-cache.md)
 * [`kit boot-real-node`](./kit/boot-real-node.md)

src/kit/connect.md

@@ -0,0 +1,83 @@
+# `kit connect`
+
+`kit connect` is a thin wrapper over `ssh` to make creating SSH tunnels to remote nodes easy.
+
+## Example Usage
+
+Without any configuration, get your SSH Address from Valet, as discussed [here](../hosted-nodes.md#accessing-your-kinodes-terminal).
+Then use
+```
+kit connect --host <SSH Address>
+```
+and paste in the password when prompted.
+You will be prompted for your password twice.
+This is to first determine the port to create the SSH tunnel to, and then to create the tunnel.
+You can also provide the port (Valet displays it as Local HTTP Port) and only be prompted for password once:
+```
+kit connect --host <SSH Address> --port <Valet Local HTTP Port>
+```
+
+It is recommended to [set up your SSH configuration on your local machine and the remote host]()../hosted-nodes.md#using-ssh-keys.
+Then `kit connect` usage looks like:
+```
+kit connect --host <Host>
+```
+where `<Host>` here is defined in your `~/.ssh/config` file.
+
+To disconnect a SSH tunnel, use the `--disconnect` flag and the local port bound, by default, `9090`:
+```
+kit connect 9090 --disconnect
+```
+
+## Discussion
+
+See discussion of why SSH tunnels are useful for development with `kit` [here](../hosted-nodes.md#using-kit-with-your-hosted-node).
+Briefly, creating a SSH tunnel allows you to use `kit` with a remote hosted node in the same way you do with a local one.
+Setting up your SSH configuration will make `kit connect` work better.
+You can find instructions for doing so [here](../hosted-nodes.md#using-ssh-keys).
+
+## Arguments
+
+```
+$ kit connect --help
+Connect (or disconnect) a ssh tunnel to a remote server
+
+Usage: kit connect [OPTIONS] [LOCAL_PORT]
+
+Arguments:
+  [LOCAL_PORT]  Local port to bind [default: 9090]
+
+Options:
+  -d, --disconnect        If set, disconnect an existing tunnel (default: connect a new tunnel)
+  -o, --host <HOST>       Host URL/IP Kinode is running on (not required for disconnect)
+  -p, --port <HOST_PORT>  Remote (host) port Kinode is running on
+  -h, --help              Print help
+```
+
+### Optional positional arg: `LOCAL_PORT`
+
+The local port to bind for the SSH tunnel.
+This is the port to direct `kit` commands to in order to have them routed to the hosted node.
+
+Defaults to `9090`.
+
+### `--disconnect`
+
+short: `-d`
+
+If set, disconnect the tunnel with given `LOCAL_PORT`.
+Else, connect a new tunnel.
+
+### `--host`
+
+short: `-o`
+
+Connect tunnel to this host.
+Required when connecting a new tunnel; not required when disconnecting.
+
+### `--port`
+
+short: `-p`
+
+The remote port to tunnel to.
+If not given when creating a new tunnel, `kit` will first determine the remote port by creating a short-lived SSH connection to the remote host, then use that port.