Skip to content

Commit

Permalink
Changed text and added exit code section in networking guide
Browse files Browse the repository at this point in the history
  • Loading branch information
AtibQur committed Dec 9, 2024
1 parent 259fbc6 commit 3185e62
Show file tree
Hide file tree
Showing 2 changed files with 59 additions and 10 deletions.
63 changes: 56 additions & 7 deletions sites/cheerpx/src/content/docs/11-guides/Networking.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ CheerpX supports networking scenarios via Tailscale, which is a VPN technology u

[Tailscale](https://tailscale.com/) is based on the [WireGuard](https://www.wireguard.com/) protocol. It includes a control plane that manages the WireGuard keys of all the machines in the network and takes care of authenticating users. Using this service provides extensive control over the network, user connections, authentication, security etc.

### Why Tailscale?
## Why Tailscale?

To support networking beyond same origin requests, it is necessary to host a proxy server. CheerpX cannot become responsible for the user's traffic as every application is different and its networking traffic should be managed internally and according to their needs.

Expand All @@ -22,21 +22,70 @@ Native networking in the browser is extremely limited, only allowing HTTP connec
> 2. The browser always enforces cross-origin rules and cross-domain requests are only allowed by a small subset of domains, making it very unlikely that an aribitrary application could work when attempting HTTP traffic via fetch.
> These limitations necessitate a more comprehensive networking solution that can provide a full TCP/IP stack.
#### The need for a VPN solution
### The need for a VPN solution

To overcome these limitations, CheerpX uses Tailscale, which provides a VPN solution via WebSockets. This approach allows CheerpX to implement a complete TCP/IP stack, enabling applications inside the VM to perform networking operations as they would on a regular machine.

Networking with WebVM always happens via Tailscale. To give access to your local or development machine as part of the Tailscale internal network, you need to install Tailscale locally. The setup is effectively the same as with internet-enabled configurations; you can just skip enabling the exit node if you only need internal network access.

It's important to note that WebVM-to-WebVM networking can be achieved via Tailscale without the need for any exit node. This solution could be useful for client/server applications running entirely without WebVM and peer-to-peer applications such as multiplayer games.
> [!note] Note
> WebVM-to-WebVM networking can be achieved via Tailscale without the need for any exit node. This solution could be useful for client/server applications running entirely without WebVM and peer-to-peer applications such as multiplayer games.
For a more detailed explanation of why Tailscale was chosen and how it works with WebVM, you can read our [blog post on WebVM networking via Tailscale](https://labs.leaningtech.com/blog/webvm-virtual-machine-with-networking-via-tailscale).

### Client applications with existing backends
## Setting up an exit node

The easiest way to connect a client application running in CheerpX with traditional backends, either on the public internet or private network), is to [install Tailscale](https://tailscale.com/kb/1017/install) on your backend server. This way the client can connect to your private Tailscale network via an auth key, and then talk to your server via the VPN.
An exit node is a device on the Tailscale network that routes internet traffic from other Tailscale devices through its connection, making it appear as if the traffic originates from the exit node's location. This can be useful for security purposes or to access content that is restricted to certain regions.

### Connecting your application to a Tailscale network
### When do you need an exit node?

You only need an exit node if you want to:

- Access the internet and appear as if it's coming from a specific location.
- Enhance security by routing traffic through a trusted system.
- Connect to services that restrict access based on a certain IP address or region.

If your use case only involves internal access within the Tailscale network (for example, WebVM-to-WebVM communication or connecting to local network services), you do **not** need to set up an exit node.

### How to set up an exit node

Tailscale can be downloaded, installed, and updated in different ways depending on your system. For detailed instructions, refer to the [install Tailscale](https://tailscale.com/kb/1347/installation) guide and choose the appropriate method for your system.

1. Advertise a device as an exit node

On the device you want to use as the exit node, run:

```bash
sudo tailscale up --advertise-exit-node
```

This makes the device available as an exit node for other Tailscale devices.

2. Use the exit node

To route traffic through the exit node, use the following command:

```bash
sudo tailscale set --exit-node=<exit-node-ip>
```

Replace `<exit-node-ip>` with the Tailscale IP address of your exit node.

3. Stop using an exit Node (Optional)

If you want to disconnect from the exit node and use a direct connection instead, run:

```bash
sudo tailscale up --exit-node=
```

For more details on configuring and using exit nodes, refer to Tailscale’s [Exit nodes](https://tailscale.com/kb/1103/exit-nodes) documentation.

## Client applications with existing backends

The easiest way to connect a client application running in CheerpX with traditional backends (either on the public internet or private network), is to [install Tailscale](https://tailscale.com/kb/1017/install) on your backend server. This way the client can connect to your private Tailscale network via an auth key, and then talk to your server via the VPN.

## Connecting your application to a Tailscale network

Connecting the CheerpX application client to your Tailscale network is as simple as providing client authentication via `CheerpX.Linux.create()`:

Expand Down Expand Up @@ -84,6 +133,6 @@ What is happening here?

- `loginUrlCb` expects the base URL of a control server that will continue and finish the login process. This callback is executed when it is time to prompt the user to log in to Tailscale via the UI.

### Self-hosting Headscale
## Self-hosting Headscale

Headscale is an open-source and self-hosted implementation of the Tailscale control server. The upstream version of Headscale does not yet properly support the WebSocket transport. For the time being, please use [our fork](https://github.com/leaningtech/headscale).
6 changes: 3 additions & 3 deletions sites/cheerpx/src/content/docs/20-faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,8 @@ For more information on how to setup a HTTP server, please see our [server setup
[SharedArrayBuffer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
[cross-origin isolated]: https://web.dev/articles/why-coop-coep

## Do I need an Exit Node for WebVM networking?
## When Do I Need an Exit Node for WebVM Networking?

You do not need to create an exit node for WebVM. WebVM relies on tailscale to handle networking, allowing acces to your local or development machine as part of the Tailscale network.
You do **not** need to create an exit node for WebVM if your goal is to access other devices within your Tailscale network, including other WebVM instances and your local development machine. Tailscale takes care of routing and connecting your WebVM to other devices on the Tailscale network seamlessly.

For a detailed overview of WebVM networking and setup instructions, refer to our [Networking Guide](/docs/guides/Networking).
For a detailed overview of WebVM networking and setup instructions, refer to our [Networking Guide](/docs/guides/Networking#setting-up-an-exit-node).

0 comments on commit 3185e62

Please sign in to comment.