Accessing remotely via ngrok

You may want to develop your sketches on a laptop, and have your Five Server running there, but run the sketches in a browser on a different device, most obviously your phone.

In this guide, we’ll use ngrok to help us 1. access sketches over the internet and 2. load sketches over HTTPS.

As an alternative, you can host and edit your code online. See Getting started.

URLs and addressing

When Five Server starts, it opens a Terminal at the bottom of Visual Studio Code, spitting out something like:

Five Server running at:
> Local:    http://localhost:5500
> Network:  http://192.168.0.140:5500

There are three key components of these URLs. The scheme, or protocol (http), the hostname or IP (localhost, 192.168.0.140) and the port 5500.

The scheme/protcol defines what ‘language’ to use when talking to a machine. In our cases, we use HTTP (web), HTTPS (secure web) and WSS (secure websockets).

The next part of the URL identifies which machine of all the machines on the network/internet. When names are used, its called a hostname, or when a numeric identifier is used, its the IP address.

A hostname of ‘localhost’ or IP of ‘127.0.0.1’ always refers to the same device, a so-called ‘loopback’ address. It’s basically a reference like the words ‘me’ or ‘self’. These URLs work fine when we have the server and browser running on the same machine but do not work when accessing from a different device, because their ‘localhost’ or ‘127.0.0.1’ refers to themselves, not your server.

So far we can determine how to talk to a machine, and which machine to talk to. The next port determines which of the many services a machine may host we want to connect to. A given machine may have multiple web servers for example, and we need to be able to indicate which to use.

Only one service at a time can use a given port. Five Server defaults to port 5500, but you may note it use a different port if you mistakenly have it already running in another window or some other service is sitting on port 5500.

HTTPS

To make for a more secure world, browsers don’t allow a lot of features if the code is loaded over the unsecure, HTTP protocol.

To simplify life for tinkers, browsers skip those policies if you are loading code from ‘localhost’ or ‘127.0.0.1’ - the thinking is that if the code is already on your own machine it can be trusted more than random things from the internet.

However, if we want to access our sketches remotely, we can’t access them from loopback addresses, and thus need to use HTTPS.

One way of solving it is to generate a self-signed SSL certificate, set Five Server to use it and install it on all your devices. Another option might be to put your code on a service like Glitch.com, and open it from there, since everything is hosted over HTTPS.

But for the best editing experience, we want to edit and store our code locally. A way of doing this is to add a tunneling service, in this case one called ‘ngrok’.

Tunneling service: Ngrok

Ngrok is a server that runs on your computer and connects to whatever service you want to make available over HTTPS and on the internet. In our case, that’s the existing Five Server.

Once booted up, ngrok allows your server to be accessed on the internet. So a browser connects to ngrok which in turn forwards the request to your local Five Server.

Setting up ngrok

Go to ngrok.com and create an account or sign in with an existing account (eg using GitHub)
Install ngrok following the instructions
Make a note of the ‘authtoken’ that is listed in step 2 of the instructions (eg: 12PMWdaefa3234...)
Install ngrok for VSCode extension
Edit ngrok.yml which is in the same directory as this file, and paste in your token. When done, it should look something like this:
```
authtoken: 12SYCNNGx6KpoAtafEHE_1xKUN52C6ZrmJP5RZoMZK
tunnels:
  ixfx:
    proto: http
    addr: 5500
```
…but obviously with your ‘authtoken’

Now ngrok should be ready to use.

Using ngrok

To start ngrok, open a terminal (via VS Code you can go View > Terminal) and run:

ngrok start --all --config ./ngrok.yml

Tip: if you have Node.js installed, you can also use npm run ngrok

When it starts, should see Account with your account name. You’ll also see a Forwarding URL.

Remember, to access your sketches remotely, you have to access them via the generated ngrok URL, eg ‘https://abfe-4-186-119-23.ngrok-free.app’.

It’s a good idea to stop ngrok when you are not using it, because it does expose your Five Server to the world (although someone would have to guess the URL to find it). To stop it, click in the terminal, and press CMD (or CTRL) and C.

Using Ngrok with websockets

If you have Node.js installed and serving your sketches via npm run serve, the default ngrok config won’t tunnel websockets.

To fix this:

Stop ngrok (CMD or CTRL + C in the terminal it is running), stop the Five Server VS Code extension
Open ngrok.yml

Add in the ws block you see below, keeping everything else the same

authtoken: 12SYCNNGx6KpoAtafEHE_1xKUN52C6ZrmJP5RZoMZK
tunnels:
  ixfx:
    proto: http
    addr: 5500
  ws:
    proto: http
    addr: 8080
version: "2"

Now that it’s configured, you can start the servers locally. We do this instead of the VS Code extension.

npm run serve

With the servers running, you can start ngrok:

npm run ngrok

Now there are two ‘Forwarding’ URLs, for example:

Forwarding       https://246d-80-208-67-54.ngrok-free.app -> http://localhost:5500
Forwarding       https://f612-80-208-67-54.ngrok-free.app -> http://localhost:8080

The one that points to the :5500 address is for your ‘Five Server’. This is the URL to open in your browser.

The one that points to the :8080 one is the websocket URL. We use this when initialising Remote:

const settings = Object.freeze({
  remote: new Remote({
    allowNetwork: true,
    websocket: `wss://f612-80-208-67-54.ngrok-free.app`
  })
});

Note also how wss:// is used, not https://.

With the free ngrok account unfortunately these URLs change each time you start ngrok.