What is ngrok and what is it used for?

Ngrok is an internet application, which enables one to securely expose their local computer (local development server) to the internet using a public url. In other words, you can make your local computer an internet server without having a dedicated IP address. All you need to do is install ngrok and have your computer connected to the internet.

By exposing your computer, we mean exposing the applications running in your computer, including databases, so that they are accessed from anywhere.  

Your machine will be accessed using a subdomain on ngrok.com domain. For instance, once you start ngrok service in a given computer, it will generate a URL like de345.ngrok.com, which you use to access the computer where ngrok is running in.

Ngrok is free for basic features with usage limitation. You can use the paid version to unlock more features such as custom subdomains and more.

The beauty is that you can instruct ngrok to expose your machine using any port e.g. if you have an app or service running on port 8000, ngrok can be instructed to run to expose that port.  

You can start ngrok on any port in your computer

The following diagram can enable you to understand better.

The relative position of all entities taking part in the use of ngrok application 

Objectives of this walk-through

  • To identify use cases of ngrok usage.
  • To provide a procedure of setting up and using ngrok in a windows computer to access both web and database applications.
  • To identify reasons why ngrok may not be working in your machine.  

Ngrok usage use cases

There are many reasons why you may want to access your local computer over the internet. The following are example of cases of ngrok usage.

1. Web application demo to the end users/clients

Suppose you are building a web application and you have to demo it to your end users (test users) or your clients. Instead of deploying to a live server, you can let ngrok generate a URL pointing to your computer and share it with your users.

However, note that the number of users who can access your local machine will depend on the processing power and memory of your computer as well as the ngrok plan you are using.

2. Testing a web application from different clients

If you are developing an application and you want to test it from a variety of clients, ngrok will generate a URL, which you can distribute to the target clients. In this same idea, if you are building an app, which has a mobile client (e.g. an android client), the ngrok generated URLs can simulate public URLs.

3. Testing Webhooks

A webhook or generally referred to as a callback URL, a methodology used in API integration i.e where 2 applications exchange information, and more specifically, application A must notify application B when some event occurs.

Suppose you are building an e-commerce system and you use an external payment system to accept payments. What happens is that you must put a URL in the payment system so that the payment system can use it to notify your e-commerce website when a user has made a payment. The ngrok generated URL can be used for this purpose to test the behavior of the system before deployment.  

Another example, which is discussed here, is delivering messages to your local server from Twilio.

3. Letting another application to access a database application in your local computer.

If you have an external application, which needs to access a database running in your local computer, it is possible with ngrok. We know Database Management Systems (DBMS) are TCP applications. The good news is, ngrok supports this protocol as we will discover in the next section.

Installing and using ngrok  

1. Visit this link (ngrok website) and click on "Download for windows". You will get a zip file downloaded.

2. Move the downloaded zip to a favorite location and extract it. Inside the folder from the extraction, you will see a small executable file, ngrok

3. Double-click on the ngrok file. It will open a cmd with the extracted folder as the present working directory, pwd. See below.

It can be observed that ngrok gives examples of usage of its commands. Our objective is to expose a local computer to the internet.

Additionally, you can observe that ngrok supports both http and tcp protocols.

4. To expose a web application  running in your computer on port 80, you can run this command on the terminal.

ngrok http 80

Below, you will see that ngrok will create a url of the form http(s)://<random_text>.ngrok.com, which is mapped to port 80 in your computer.

From the screenshot, there are at least 5 data points of interest;

i) You can stop the ngrok service by pressing ctrl + C.This command will kill ngrok service.

ii) Ngrok provides a web interface used to inspect its usage. The web interface is accessed using http://localhost:4040. If you are not sure if ngrok is running, you can use this url to test if its web interface is accessible.

iii) The public URLs provided are both http and https. Some applications, especially when testing web hooks (see use case 3 above), may require that you use https.

iv) Ngrok shows you the account details including the pricing plan that you are on.

v) Ngrok shows you the region where the server you are interacting with is located. In the example above, the region is United States (us).

Exposing database application

DBMS such as MYSQL and PostreSQL are tcp applications. Ngrok allows you to expose database applications on tcp protocol the same way we did with http applications, using the port number on which they are running.

Exposing MySQL database on default port i.e. port 3306

You will need to run the following command:

ngrok tcp 3306

The output of the above command is shown below.

If you are connecting to the database use 0.tcp.ngrok.io:13003 as your host name. Notice that we have not included tcp:// in the host name.

To expose Postgres database on the default port, then you will run the following command:

ngrok tcp 5432

Protecting your ngrok URLs using password

When you expose your computer on a public URL, it means that any person having access to the URL can access your computer even though that was not the intention. The URL may even be guessed.

If you had a select group, you would create a URL, which requires that users provide a username and password for them to access the service.

This can be achieved by running the ngrok command as follows:

ngrok http -auth="username here:password here" 80

When you share the public URL, users will be asked to enter a username and password as shown below

Modifying/re-writing request headers

You will realize that ngrok forwards any http headers as they come without changing anything. However, sometimes you may want to modify the headers.

The following examples explains why you may need to carry out the modification:

i) Modification - Rewriting the host header to something else. For instance, your local server is configured with virtual machines (VM) and you want to use a specific VM as your host.

In this case, you can have something like this:

ngrok http -host-header=decode.local.vh 80

Notice that decode.local.vh is the name of the VM with a service running on port 80.

ii) Configure ngrok's CORS headers

In cases where the hostname is different from that of forwarding host address, you can rewrite the hostname to match that of the forwarding address. For example, same address but different ports -  if the forwarding address' port number is 8080, then you can do it this way;-

ngrok http -host-header=rewrite 8080
//We have made the host port number to be similar to forwading address port number.

iii) Ngrok allows you to modify request headers via replaying, which is possible by using the web interface. You will need to select a request from the web interface, then click on 'Replay with modification'. You will see the interface below

Click on 'Replay' to resend the request. We have now re-sent the request with a new header, api.

Why Ngrok is not working in my computer?

Our earlier discussion showed that the main function of ngrok is to expose your local computer using a URL. But sometimes, it may not be working, and it may be because of any of the following reasons. Note that this list is not exhaustive.

  1. You are using a free ngrok plan with certain limitations. For instance, the free ngrok plan allows only 1 ngrok process, 4 tunnels (4 URLs) per ngrok process and 40 connections per minute.
  2. ngrok service may have stopped. We earlier noticed that you can use http://localhost:4040/ to check if ngrok web interface is reachable. If it is not reachable, then ngrok service is not running.  
  3. A problem with ngrok's CORS headers. For instance, if the host address is different from a forwarding address, there will be an error. Fortunately, ngrok allows you to re-write request headers as seen earlier.
  4. If you are accessing some service running in your local computer, then you may have forgotten to start such service. When accessing your machine using ngrok's generated public URL,  you are likely to see, Failed to complete tunnel connection, if the service you want to access was not started in the local machine.
  5. When testing a web hook, the API you are testing requires a url pointing to the application being tested. If you use https, it may not work with the self-signed certificate in your local computer. In this case, you may only use http. See an example here from Twilio.  

Conclusion

The discussion we have had here focused on the most common use cases of ngrok. Other features of interest on paid ngrok plans include:

  • You can use custom sub-domains instead of the randomly generated ngrok subdomains. And such sub-domains can be host in ngrok for as long as you want.
  • You can use your own custom domains, which are mapped by ngrok to your local computer.
  • And many more...

For a detailed analysis of what ngrok can do, check out the official documentation @ ngrok documentation.

I hope you enjoyed trying out ngrok.  

You can check out my other tutorials here.

You've successfully subscribed to Decoded For Devs
Welcome back! You've successfully signed in.
Great! You've successfully signed up.
Your link has expired
Success! Your account is fully activated, you now have access to all content.