This page is a guide on how to host the SynthARium project and make it available to users from the internet.

The first step to successfully hosting SynthARium is using SSL/TLS. Most browsers only allow access to media devices (webcam, microphone, ...) if the website is localhost or reached via HTTPS. Additionally, websites served over HTTPS can not make requests to HTTP servers. Therefore a SSL certificate is required to access the backend from other devices.

Place the certificate and private key in backend/certificate and make sure ssl_cert and ssl_key in config.json are set correctly. Then set https to true and start the server.

In case the frontend dev server is used, make sure to update the backend server address there to use https. Make sure to also switch the frontend server over to HTTPS. See frontend configuration.

If you want to conduct an experiment, you need to get a trusted SSL Certificate. One way to get free SSL certificates is Let's Encrypt.

A bash script using openssl to generate a self signed certificate can be found at: backend/certificate/generate_certificate.sh. You can check if openssl is installed using: openssl version.

In case openssl is not an option, take a look at Generating self-signed certificates on Windows.

When using a self signed certificate, your browser will likely warn you about it. To allow the frontend to connect to the server, you must manually "accept the risk" by directly opening the backend in the browser. The backend server will tell you its address after starting, it will look something like: https://127.0.0.1:8080.

You have multiple options to make sure your SynthARium instance will be available from the internet. But this step will highly dependent on your network setup (private, corporate, university, etc.). Therefore we will just roughly outline some options here. To make sure other users can access the website, look at the options below. Additionally the WebRTC connection needs to be able to establish a connection between the participant and the backend. To make sure that also works, make sure to add ICE (STUN or TURN) servers when configuring the hub. Free STUN and TURN servers can be found here.

You can use port-forwarding to make sure your server is accessible from outside of your network. Be sure you understand what port-forwarding is and the potential risks involved.

1. Create a port-forwarding entry in router
2. Change the host in backend/config.json to your local IP address
3. Start the server
4. Find out the public IP of your network. e.g. using this site
5. Your SynthARium instance should now be available on https://<public-ip>:<port used for forwarding>

Cloudflared can create a tunnel from the internet to your local server.

1. Install cloudflared
2. Start the backend server
3. Expose the backend server by creating a temporary tunnel: cloudflared tunnel --no-tls-verify --url https://127.0.0.1:8080
4. You should see a random url generated through which the backend server is now accessible on the Internet. Note that you do not need to add a port to this url.

If you are using the frontend development server you need to do these additional steps:

1. Copy the url generated above (backend server url) into the variable REACT_APP_BACKEND in the frontend/.env file.
2. Start frontend server
3. Expose frontend server by creating a temporary tunnel: cloudflared tunnel --no-tls-verify --url https://127.0.0.1:3000
4. Now your hub should be available using the second random url.

Ngrok is offer's a reverse proxy and is another alternative that can be used to access your local server from outside networks.

1. Sign up for ngrok
2. Download or install ngrok
   macOS: brew install ngrok/ngrok/ngrok
   windows: choco install ngrok
   linux: curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null && echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list && sudo apt update && sudo apt install ngrok \
3. Authenticate ngrok through the terminal by accessing your authentication token through the dashboard under "Your Authtoken".
4. In a terminal run the following command: ngrok config add-authtoken YOUR_TOKEN_GOES_HERE
5. Once complete, run ngrok with the following command (if running with backend development server, for frontend use port 3000): ngrok http http://localhost:8080
6. Note the random url generated in the terminal window. You can run the backend normally and access the SynthARium page through this link. Your participant links will also be based on this link and accessible on the Internet.