A complete Hypothesis stack consists of several components, several of which have references to the others in the form of URLs. At a minimum these include the Hypothesis client and service.
During local development, these URLs point to the development system using localhost. For example the h service is accessible at http://localhost:5000 by default and the client's development server at http://localhost:3000.
In order to test and debug a local version of Hypothesis on a different device, or a virtual machine, you need to be able to access the service/client from that device and also make sure that any URLs that the services use to refer to one another in HTTP responses sent to the browser are also resolvable from the testing device. For example http://localhost:5000/embed.js redirects to the client's development server at http://localhost:3001/hypothesis. Both of these URLs need to work on the testing device.
There are two ways to achieve this:
-
Change all the URLs so that they can be accessed on the device you are testing on. For example if the device and development system are on the same network change "http://localhost:{port}" to "http://{hostname or IP of development server}:{port}". If the testing device is a VirtualBox VM and the development system is the host, change the URLs to "http://10.0.2.2:{port}", where 10.0.2.2 is the IP of the host within the VM.
-
Set up port forwarding, so that requests to eg. "http://localhost:5000" on the testing device get forwarded to port 5000 on the development system where h is running.
If you are only testing one part of Hypothesis, such as web pages rendered by h, simply using a different URL on the testing system will usually be the easiest way. If you are doing something that involves multiple Hypothesis services (eg. the client, h and Bouncer), setting up port forwarding is often the easiest method because it doesn't require making changes in several places.
Setting up port forwarding involves the following steps:
-
Run an SSH server on the development system, and make sure that port forwarding is allowed (it usually is by default). From the command-line, you can run an OpenSSH server temporarily using:
sudo /usr/sbin/sshd -DOn macOS you can also enable SSH by enabling the "Remote Login" feature under System Preferences => Sharing.
-
On the testing device, run an SSH client which connects to the SSH server on the development system. Popular clients include:
-
On the testing device, configure the SSH client to connect to the IP/hostname of the development server and also add a port forwarding configuration. The port forwarding configuration should be as follows, you can omit services you are not using:
Purpose Local port Destination IP/host and port h service 5000 localhost:5000 client dev server 3000 localhost:3000 client dev server 3001 localhost:3001 Via 9080 localhost:9080 Note that the destination IP/host is resolved on the system where the SSH server (and also h, the client etc.) is running, so "localhost" refers toe the development system.
Setting up port forwarding on Windows using PuTTY
In PuTTY port forwarding is managed under Connection => SSH => Tunnels. You can save configurations for future use in the Session page.
Setting up port forwarding on macOS / Ubuntu
On macOS and Ubuntu you can create an SSH connection with port forwarding enabled by using the -L {local port}:{destination}:{destination port} syntax:
ssh -L 5000:10.0.2.2:5000 user@10.0.2.2
Setting up port forwarding on iOS
Termius has a "Port Forwarding" connection page. Once port forwarding is active, you can browse to a forwarded port in the Safari app.