Often when developing demos for conferences, writing blog posts and “how-tos” or creating a guide for our developer portal we need to expose our local developer environment to the public internet so that it is reachable by the Vonage APIs.
ngrok diagra
Our developer relations team is remote, and often travelling so sometimes we’re working from home, or we might be in our office in London or in a coffee shop. In order to receive inbound webhooks we would need to set up a local server, forward the correct ports, ensure the DNS has our new public IP and is propagated, configure SSL, and so on. This is not only impractical but probably impossible in certain situations. But with ngrok we can expose our local server, on its own subdomain with https support in a single command.
ngrok in terminal
Please do note however if you are on a corporate network you should not be creating any remote tunnels without first running it past your network administrator. Check the section below on security concerns for more details.
The other option is to deploy our code to a remote server. With the likes of Heroku and Digital Ocean this is getting easier all the time, but there is still some setup and normally some cost involved. But if all I want to do is serve an NCCO (Call Control Object) JSON file it is unlikely any other service can be easier than;
The ngrok site has downloads available for most major operating systems, it also has instructions for how to install ngrok, which essentially consists of unzipping it. I tend to move the ngrok binary into /usr/local/bin (or another directory on my $PATH) on Mac/Linux so I can easily invoke it from the command line without specifying the complete path to the binary. How-to Geek has a great article on editing your System PATH in windows if you’d like to do similar on a Windows machine.
Once installed running ngrok is as easy as running the following, where 8000 is the port number your local server is running on
This will start ngrok in your terminal.
Once started you should see the public URLs ngrok has created for you, as well as some other information such as the region your tunnel is running in, how many current connections it has and a log of HTTP requests received.
As ngrok runs in your terminal you will likely need to have a terminal window open for your local server and a separate terminal window for ngrok. Alternatively you could use GNU Screen or tmux. The documentation for both are pretty dense reading. You can find some good information on the basics of screen by searching for “quickstart GNU screen <operating system>”
One of the most useful features of ngrok is the ability to replay requests.
ngrok web console
When you start ngrok one of the URLs listed is for the web interface. This web interface runs locally on your machine, normally on port 4040 and it provides a whole swathe of information about your running tunnel include metrics about requests.
On the inspect tab there is also a list of all requests received. This list includes the type of request (GET, POST, HEAD, etc), what URL was requested and what HTTP response code was sent by your local server (200, 404, etc). Clicking on a request will display more information including the headers and even the raw request/response. This can be invaluable when debugging API interactions.
After selecting a request from the list you can replay that request. This will resend the request to your local server! So for example if you are developing an application that uses the Vonage SMS API for inbound SMS, rather than having to send another SMS to trigger the webhook, you can simply replay the last inbound SMS request.
ngrok has a lot of extra features, including an API, so I highly recommend you read their documentation to familiarize yourself with everything that is available as I’m only going to run through some of the more common features we use during development.
HTTPS only - By default ngrok will open endpoints for both http and https traffic.
-bind-tls=truewill only listen for https requestsSwitch region - By default ngrok will use the us - United States (Ohio) region, but you can pick between several different regions that may be closer
Adding HTTP Basic Auth - This feature requires an ngrok account, so you will have to sign up and authorise your ngrok client first
Everything we’ve discussed so far has been available without an ngrok account or with a free account. The following features are only available with a paid ngrok subscription, but we think they’re super useful so I’ve included them.
Custom and reserved domains. By default ngrok will assign a random hexadecimal name to the tunnel for you. This name will change each time you restart ngrok (by accidentally closing your terminal for example). Having to update all your webhook URLs whenever you restart your terminal is an annoyance. By using a custom or reserved domain then your URL will remain the same each time you run ngrok. You can take this a step further by using your own custom domain.
IP whitelisting (configured via the ngrok dashboard). Creating a tunnel into your local network is not without its security concerns, you can help to mitigate these by whitelisting only those IP addresses which should be able to access your local server. You can find a list of the Vonage IP ranges you should whitelist in our knowledge base.
If you want to ruin a network administrator's day tell them you want to run an open reverse proxy into their local network. ngrok is a fantastic application which we use daily here at Vonage, but you should be aware of the security implications of tunneling through your network firewall. Speak to your network administrator before using ngrok on your work network.
If running at home, coffee shop, somewhere else without a network administrator you can speak to, or where you are the network administrator, then we recommend using ngrok with HTTP Basic Auth, IP whitelisting and HTTPS forced on.
You can find information on using HTTP Basic Auth with Vonage, as well as our public IP addresses in our knowledge base.
Aaron was a developer advocate at Nexmo. A seasoned software engineer and wannabe digital artist Aaron is frequently found creating things with code, or electronics; sometimes both. You can customarily tell when he's working on something new by the smell of burning components in the air.
