ngrok
What is ngrok?
Ngrok is a connectivity service that allows you to expose your local server ports to the Internet. You can use ngrok to expose your workflows to the Relay server from your local workstation while behind a firewall. This allows you to do develop by editing and running code on your local workstation. You might find it helpful to use ngrok mainly when you are developing and initially testing your workflows, because edit+save+restart is really quick and easy on a local workstation. You likely don't want to use the free version of ngrok for long-term hosting because the external address that ngrok gives you expires after 2 hours, and you would have to restart ngrok to replace the expired address and re-register your workflow with the new hostname.
When you are ready to test your workflow, you can expose your local server ports to the Relay server with ngrok by implementing the following steps.
Setting up with ngrok
You can install ngrok on your machine with the following command:
# Download from https://dashboard.ngrok.com/get-started/setup after creating an account at ngrok.com
# Use the ngrok.com web dashboard to add an SSH key, so you can start a tunnel without downloading or running the ngrok agent and instead use `ssh -R`.
$ npm install -g ngrok
For the Node shell command, the -g flag allows you to use install the ngrok tool globally so it can be invoked from any directory. If you installed without the -g flag and run into the error "command 'ngrok' not found", try reinstalling ngrok with the global flag.
Installing a workflow with ngrok
Next, you need to choose a local port that you would like your local server to run on. In the Hello World workflow, our workflow has a websocket server listening on local port 8080. But since we are likely behind a firewall in the office or at home, the Relay server isn't going to be able to reach our local port 8080. So we'll start the ngrok tool that will use one of ngrok's servers on the external internet to listen on its https regular port 443, and forward that traffic to our local port 8080:
$ ngrok http 8080
Run the ngrok http command in a different shell window than the one where you will be running your workflow code, so that you can keep ngrok running while you install and run your workflows. After typing in the command, you will see information about your session including two forwarding addresses. It should look like the following:
ngrok by @inconshreveable (Ctrl+C to quit)
Session Status online
Session Expires 1 hour, 59 minutes
Version 2.3.40
Region United States (us)
Web Interface http://127.0.0.1:4040
Forwarding http://8adb-8-48-95-57.ngrok.io -> http://localhost:8080
Forwarding https://8adb-8-48-95-57.ngrok.io -> http://localhost:8080
Connections ttl opn rt1 rt5 p50 p90
0 0 0.00 0.00 0.00 0.00
Now, when you are ready to register a workflow on the Relay server, you can copy the address that ngrok has given you and paste it into the websocket URL that you would like to use for your workflow. Be sure to change the "https" or "http" to "wss". And include the path part of your workflow in the URL. For example:
relay workflow create button --trigger=single --name broadcast-button --uri 'wss://8adb-8-48-95-57.ngrok.io/broadcast' --install 990007560012345
When you run your workflow on a device, you should see updates on the ngrok terminal you left open. The ngrok address that you use expires after 2 hours, so you would need to Ctrl+C out of the ngrok window to end the session, and use the ngrok http 8080 command again to start a new session. You would also need to re-run the relay workflow:create CLI command again to configure the workflow for the updated URL (specifically the hostname).
As you make changes to your workflow source code, you'll want to stop (Ctrl-C) your workflow app and restart it to pick up changes, but you don't need to stop and restart the ngrok tool as your listening port number isn't changing.
When you no longer want your local port 8080 to be reachable from the internet, just stop the ngrok tool, such as using Ctrl+C.
We aren't recommending any specific providers, but since ngrok is common we'd like to share our lessons learned to help you get up and running quickly.
Updated 9 months ago