From e1f93202b4d6527de2c249ec77581c1cac12d875 Mon Sep 17 00:00:00 2001 From: hosted-fornet Date: Wed, 22 May 2024 11:48:32 -0700 Subject: [PATCH 1/2] add hosted-node user guide --- src/SUMMARY.md | 1 + src/hosted-nodes.md | 87 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+) create mode 100644 src/hosted-nodes.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index bb18000e..24b518c8 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -69,3 +69,4 @@ - [Timer API](./apis/timer.md) - [VFS API](./apis/vfs.md) - [WebSocket API](./apis/websocket_authentication.md) +- [Hosted Nodes User Guide](./hosted-nodes.md) diff --git a/src/hosted-nodes.md b/src/hosted-nodes.md new file mode 100644 index 00000000..f5d3a01b --- /dev/null +++ b/src/hosted-nodes.md @@ -0,0 +1,87 @@ +# Hosted Nodes User Guide + +Kinode DAO runs a Kinode hosting service for users who do not want to run a Kinode themselves. +These hosted Kinodes are useful for both end users and for developers. +This guide is largely targeted at developers who want to develop Kinode applications using their hosted Kinode. +End users may also find the [Managing Your Kinode](#managing-your-kinode) section useful. + +Here, we use `ssh` extensively. +This guide is specifically tailored to `ssh`s use for the Kinode hosting service. +A more expansive guide can be found [here](https://www.digitalocean.com/community/tutorials/ssh-essentials-working-with-ssh-servers-clients-and-keys). + +## Managing Your Kinode + +[Valet](https://valet.kinode.org/) is the interface for managing your Kinode. +Once logged in, `Your Kinodes` will be displayed: clicking on the name of a Kinode will navigate to the homepage for that Kinode. +Clicking on the gear icon will open a modal with some information about the Kinode. +Click `Show advanced details` to reveal information for accessing your Kinode's terminal. + +## Accessing Your Kinode's Terminal + +As discussed in [Managing Your Kinode](#managing-your-kinode), navigate to: +1. https://valet.kinode.org/ +2. `Your Kinodes` +3. Gear icon +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 | kexampleuser@template.hosting.kinode.net +SSH Password | 123456789 +Local HTTP Port | 8099 + +To access your Kinode remote instance, open a terminal and +```bash +ssh kexampleuser@template.hosting.kinode.net +``` +where `kexampleuser@template.hosting.kinode.net` should be the `user@kinode_name.hosting.kinode.net` in your `SSH Address`. +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. + +### Using SSH keys + +Rather than typing in a password to create a SSH connection, you can use a keypair. + +#### 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 + +#### `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 + +#### SSH Config + +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 + +## 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. +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. + +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 kexampleuser@template.hosting.kinode.net -f -N +``` +or, if you've added your host to your [`~/.ssh/config`](#ssh-config), +```bash +ssh -L 9090:localhost:8099 template -f -N +``` + +Now, `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. From c1fa8e1d4e5d0ce574eb76b6b39b16df19a8f945 Mon Sep 17 00:00:00 2001 From: "nick.kino" <79381743+nick1udwig@users.noreply.github.com> Date: Wed, 22 May 2024 12:52:43 -0700 Subject: [PATCH 2/2] Update hosted-nodes.md --- src/hosted-nodes.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/hosted-nodes.md b/src/hosted-nodes.md index f5d3a01b..da481ead 100644 --- a/src/hosted-nodes.md +++ b/src/hosted-nodes.md @@ -1,7 +1,7 @@ # Hosted Nodes User Guide Kinode DAO runs a Kinode hosting service for users who do not want to run a Kinode themselves. -These hosted Kinodes are useful for both end users and for developers. +These hosted Kinodes are useful for both end users and developers. This guide is largely targeted at developers who want to develop Kinode applications using their hosted Kinode. End users may also find the [Managing Your Kinode](#managing-your-kinode) section useful. @@ -11,7 +11,8 @@ A more expansive guide can be found [here](https://www.digitalocean.com/communit ## Managing Your Kinode -[Valet](https://valet.kinode.org/) is the interface for managing your Kinode. +[Valet](https://valet.kinode.org/) is the interface for managing your Kinode hosted by Kinode DAO. +Kinode DAO plans to open-source the hosting code so there will be other hosting options in the future. Once logged in, `Your Kinodes` will be displayed: clicking on the name of a Kinode will navigate to the homepage for that Kinode. Clicking on the gear icon will open a modal with some information about the Kinode. Click `Show advanced details` to reveal information for accessing your Kinode's terminal.