Skip to content

Hosting own infrastructure

This page covers how to set up necessary centralised infrastructure that bootstraps peer-to-peer communication for Waytale.

Once you have set up some infrastructure, please refer to the documentation of Waytale space configuration for how to integrate it into your Waytale spaces.

Wait, servers for peer-to-peer technology?

Every decentralised technology needs to answer the question of how individual peers can find each other without knowing about each other initially. Usually, this involves a server that helps establish the connection between peers and any subsequent data exchange happens solely between peers.

Waytale makes heavy use of peer-to-peer technology, hence some minimal supporting infrastructure (public servers) is required. This infrastructure already exists and it is possible to use existing servers for free (at least as long as traffic and user numbers are small). However, it is very much encouraged to set up your own infrastructure for better control, independence, privacy, and load balancing.

Infrastructure for WebRTC

Waytale uses WebRTC for the communication between browsers of people visiting the same Waytale space. WebRTC involves a number of different protocols and servers in a non-trivial connection protocol (see diagram here). In particular, two kinds of servers are relevant for Waytale:

  • Signalling Server: In order to communicate with each other, WebRTC peers are connected via a signalling server. Frequently, a signalling server takes the role of a broker in a publish-subscribe model. A signalling server is required to use Waytale.

  • STUN/TURN Servers: Because there are so many different ways networks can be configured (and restricted), peers can sometimes have a hard time connecting with each other. To help with such difficulties, so-called Interactive Connectivity Establishment (ICE) servers can be used. ICE servers use the STUN and TURN protocols and are sometimes referred to as STUN/TURN servers. Although STUN and TURN solve different problems, they are often considered together due to their similar integration. You do not strictly need ICE servers to use Waytale, but it will greatly improve compatibility and accessibility for many people if you do.

Generally, there are at least three approaches here: Use an existing public server, install by yourself, or cloud-based hosting. Using an existing public server gets you started quickly, but has some disadvantages. Self-hosting is useful for local (non-public) or development setups, but can mean a lot of work otherwise. Cloud-based hosting introduces an additional dependency, but offers a good, reliable compromise.

In case you are unsure where to go next: In most cases, cloud-based hosting is what you want.

Setting up a signalling server

WebRTC generally requires a signalling server, but each web application using WebRTC comes with its own kind of signalling server. Waytale uses the default signalling server provided by the y-webrtc repository. This is a relatively simple NodeJS application that should run on most server configurations without much tweaking.

Public servers

The y-webrtc repository states that public signalling servers are available. Similarly, there may be public signalling servers hosted elsewhere compatible with the y-webrtc network communication protocol.

However, such services need maintenance and on the long run it is (unfortunately) difficult to rely on availability and reliability of such publicly announced services, if anybody may use and abuse them. In short, it may work, but for infrastructure you depend on, you may want to consider a solution you have more control over.

Custom installation

The general steps for running a signalling server are: Cloning the repository, installing dependencies, and running the server script. System requirements here are NodeJS and NPM.

git clone https://github.com/yjs/y-webrtc
cd y-webrtc
npm install
node bin/server.js

For a local development setup, you usually do not just want to run a signalling server, but also run a web server. In this case, you may want to consider using the waytale program from the toolbox repository, which provides a combined solution doing the steps above for you and a little more.

Cloud-based hosting remarks

The easiest way to host a public signalling server is to use some cloud-based hosting service. A signalling server does not need a lot of resources, so often the free tier of a hosting service is sufficient. So-called "serverless" offers from various providers are usually enough. The specific setup depends on the specific hosting service, but in the technical parts it boils down to the commands described under "manual installation".

Watch out for service availability: Usually cloud-based hosters shut down a running application after some time of inactivity, but it will be spun up again upon the next incoming request. The only downside of this is when visiting a Waytale space, there may be a little delay until other peers become visible. A workaround may be creating a cronjob on some always-on host or a web service that regularly pings the signalling server.

There are many fish in the sea and likely you can simply pick your favourite cloud provider. For example, the official y-webrtc repository provides a configuration for Fly.io and some people reported success with Deno Deploy.

Cloud-based hosting example

This section provides an example for how to do this using Render. This is not a general recommendation, merely Render offered a free tier sufficient for a signalling server, does not require specifying a credit card during registration, and it worked. The steps below should be transferrable to other providers as well.

To set up a signalling server using Render (as of June 2026):

  1. Log in to Render (register first if needed).
  2. On the top right, hit the button New, then Web Service.
  3. For Source Code, select the Public Git Repository: https://github.com/yjs/y-webrtc
  4. Fill in the following details:
    • Name: any name you like, e.g. "herbaltea123"
    • Language: "Node"
    • Branch: "master" (default)
    • Region: any region you like, but keep it to a single one (not multiple)
    • Root Directory: leave empty
    • Build Command: npm install
    • Start Command: node bin/server.js
    • Instance Type: "Free" is sufficient
    • Environment Variables: leave empty
    • Advanced: not needed
  5. Confirm by hitting Deploy Web Service. See notes below to ensure everything went well.
  6. Use the adapted URL of the signalling server (see notes below) in the configuration of a Waytale space.

Please wait briefly and watch the log lines that appear. If there is a line that says "Signaling server running on localhost" and a green label says "Live", you are good to go.

On the top of the page it should read the name you entered earlier, e.g. "herbaltea123". A few lines below that, there should be the public URL to the service you have just created, e.g. https://herbaltea123.onrender.com. You get the URL to your signalling server, by replacing the https with wss, i.e. wss://herbaltea123.onrender.com in the running example.

Setting up an ICE server (STUN/TURN)

ICE servers for STUN or TURN solve a general problem of peer connectivity, so related software works independently of any Waytale-related specifics. There are different ways to use or set up an ICE server, described in the next sections.

To verify connectivity of your newly set up ICE server, there are a couple of online tools to help, for example the Trickle ICE tool. The configuration of ICE servers is generally (i.e. also in Waytale's case) specified as a JSON array of objects, where each object describes a STUN or TURN server. For example:

{
  ...
  "iceServers": [
    {
      "urls": "stun:stun.example.com:80"
    },
    {
      "urls": "turn:turn.example.com:80",
      "username": "great_username",
      "credential": "secure_token"
    },
    {
      "urls": "turn:turn.example.com:80?transport=tcp",
      "username": "great_username",
      "credential": "secure_token"
    }
  ]
  ...
}

Public servers

There are various lists of public STUN/TURN servers scattered across the internet. Some are curated, some collected by individuals (e.g. here or here), and projects that rotate servers.

The same disclaimer as described in the signalling server section applies here even more: Servers need maintenance to guarantee some degree of availability and reliability, which cannot always be expected for public services. While a public server may be good to get started, it will probably not be a lasting solution.

Custom installation

It is possible to self-host a STUN/TURN server, e.g. using the Coturn software and many others. This may be useful for local testing, but generally it should not be necessary to self-host a public STUN/TURN server. Aside from the complexities of maintaining a public server, the internet connection usually needs to be fast and allow for sufficient throughput as well, which can get costly fast.

For local testing of Waytale spaces or within local networks, a STUN/TURN server is generally not needed.

Cloud-based hosting

There are various providers that offer ICE servers, which can be found with a quick internet search. The first list above with curated public servers also provides some examples. That list is provided by Metered, which offers free STUN/TURN servers after registering a (free) account.

To set up a STUN/TURN server with Metered (as of June 2026):

  1. Log in to Metered (register first if needed).
  2. Follow the assistant to create a new app. Choose a name (metered domain) of your liking.
  3. In the sidebar, select TURN Server and then the Free Trial Global plan.
  4. Scroll down to TURN Credentials and hit Click Here to Generate Your First Credential.
  5. Note down the displayed Username and Password or hit the button Show ICE Servers Array and copy from there (see notes below).
  6. Use the address and credentials of the STUN/TURN server in the configuration of a Waytale space (see intro to this section).

At the time of writing, the Show ICE Servers Array button displayed the configuration of ICE servers as JavaScript code, whereas Waytale spaces store their ICE configuration in JSON format (space.json). Please account for necessary changes, e.g. quote object keys accordingly.