Ngrok Tutorial: A Brief Introduction With Installation And Setup

This Tutorial Explains What Is Ngrok and How Can You Set Up and Install It:

Ngrok is a useful utility to create secure tunnels to locally hosted applications using a reverse proxy. It is a utility to expose any locally hosted application over the web.

In simple terms, it provides a publicly accessible web URL to any locally hosted application i.e. be it a Spring boot or nodejs based web application or a webhook for a chat application, etc.

List Of Tutorials In This Ngrok Series:

Tutorial #1: Introduction to Ngrok: Installation and Setup [This Tutorial]
Tutorial #2: Ngrok in Action: Ngrok in Spring Boot and nodejs Based Application
Tutorial #3: Ngrok Alternatives

Overview

Ngrok is available for free use by signing through email or GitHub/Gmail account. The paid version has few enhanced features like Custom subdomains, whitelisting, support, etc.

However, the free version is sufficient for all practical needs. Also, an interesting piece is how it is pronounced i.e. some say it as “N G rok” while a lot of people prefer “en-grok”

Few Applications Of Ngrok

Let us try to understand a few use cases where this utility can be used:

#1) Suppose you are developing a web application, hosted on localhost and you want to verify/validate it on all the browsers / OS combinations. You can be on Mac and want it to test on Internet Explorer, then you can simply start your application and expose it over ngrok. Anyone with a Windows PC can access that link and you can test your website.

Look at the other use cases of testing on mobile browsers which could be achieved using the exposed weblink.

#2) For use cases such as Webhooks, where you rely on an external system to notify about a certain event. For Example, Payment service webhooks which are triggered upon successful payment completion. To validate this integration you would require the triggering application to access this webhook i.e. a publicly accessible URL that can be achieved using ngrok.

#3) Another very important use case is if you want to demo/showcase your web application to your end-users and/or clients, then you can use it to generate a public url and share it.

How Does Ngrok Work?

Given below is the step by step process which illustrates the functionality of this utility.

A brief description of the numbered arrows above is given below:

1. Run the local app, so that it can be accessed at your localhost.  Example: http://localhost:8080
2. Now with ngrok executable (available for different platforms like Mac, Windows, etc.) initiate a tunnel to the localhost on the desired port. We will see this detail in the upcoming sections.
3. Once ngrok sets up the tunnel, it provides a web-accessible URL.
4. Now share the publicly accessible url with the end-users who would hit the locally hosted application.
5. End users hit the web URL on the internet.
6. When the request arrives at the ngrok server (As the URL is in a subdomain of ngrok.com the requests will initially land to ngrok server), and it will resolve the URL to the app that it needs to tunnel to.
7. Ngrok forwards the request to the tunnel created in Step 2.
8. The forwarded request connects to the locally hosted app.

Mentioned above is the sequence of steps that take place when a locally hosted app is accessed using ngrok.

Installation

Here is a Video Tutorial:

Installing this utility is a simple process that just involves downloading ngrok binary and unzipping it.

Follow the steps given below to install Ngrok:

#1) First create a free account on Ngrok to get an auth token for your account. Without an auth token, you will not be able to start tunnels for the locally hosted applications.

#2) Download client library depending on the OS you are on.

#3) Unzip the downloaded package.

#4) Update the ngrok configuration file with your auth token by running the following command on the terminal/command prompt.

./ngrok authtoken {your-auth-token}

You can visit/view the config file to see if your auth token has been updated or not. The Ngrok config file is available in the user directory at location – ~/.ngrok2/ngrok.yml

#5) Once the auth token gets updated, you should be able to start the tunnel for your locally hosted applications.

#6) To start the tunnel on port 80 for localhost, simply execute the below command.

./ngrok http 80

Once the above command gets executed, a tunnel gets created to the localhost:80 (Whatever application is running on this port should be accessible through the tunneled URL as shown in the below figure).

Conclusion

In this tutorial, we saw what Ngrok is, and how you can set up and install it on your desktop or laptop. It is a great handy utility that allows you to expose any locally hosted application over the web.

We also walked through how does this utility works right from starting the tunnel until an end-user request reaches back to the locally hosted application.

In the upcoming tutorial, we will see Ngrok in action with a few sample applications.

NEXT Tutorial