How to Setup Ngrok for Local Application Development

Published:22 March 2022 - 6 min. read

Uzma Younas Image

Uzma Younas

Read more tutorials by Uzma Younas!

If you’re developing a web application hosted on localhost and you want to validate it on different browsers, ngrok is definitely worth a try. You can simply start your application, expose it to the internet over ngrok, and test your website on a different device or a VM.

In this tutorial, you’ll learn to set up ngrok and how it facilitates the testing application development process locally.

Read on and start your local application development without overly exerting efforts!

Prerequisites

This tutorial comprises hands-on demonstrations. To follow along, be sure you have the following:

  • An ngrok account – This tutorial uses an ngrok account linked to a GitHub account.
  • A Windows PC – This tutorial uses Windows 10 64-bit (32-bit also works), but other operating systems will work.
  • Apache installed on your Windows PC.

Downloading and Authenticating ngrok

Before setting up ngrok for local application development, you’ll first need to download the ngrok agent on your machine. Unlike other agents/clients, you’ll only need to extract the ngrok agent without installing it, but it’s best to log in to your ngrok account first.

1. Open your favorite web browser and log in to your ngrok account.

2. Once logged in, click Download for Windows on the home page to download the ngrok agent in a ZIP file.

Since ngrok works on other operating systems, choose the one you’re familiar with at the right-most part of the home page.

Downloading Ngrok Installer
Downloading Ngrok Installer

3. Extract the ZIP file to your preferred location, and run the ngrok.exe file to start ngrok’s terminal, as shown below.

Launching ngrok
Launching ngrok

4. Now, scroll down on ngrok’s home page, and copy the command under the Connect your account section.

The command contains the authtoken for your account, which connects the ngrok agent on your system to your ngrok account. An AuthToken is required to start a tunnel for local applications.

Retrieving the authtoken
Retrieving the authtoken

5. Finally, switch to ngrok’s terminal and paste the command in the following format. This command authenticates and connects your ngrok agent to your ngrok account. Running this command also grants you access to more features and longer session times.

ngrok authtoken {your-authtoken}

The ngrok config file (ngrok.yml) is available in the user directory (C:\Users\USERNAME/.ngrok2/ngrok.yml), as shown below, where you can view the config file containing the authtoken.

Authenticating ngrok Agent with authtoken
Authenticating ngrok Agent with authtoken

Starting a Tunnel for the Local Host

Once you’ve authenticated your ngrok agent, you’re free to start a tunnel for the localhost. You’ll have to tell ngrok which port your web server is listening on to expose your webserver to the internet from your local machine. But for this demo, you’ll use the default port (80) for HTTP.

1. Run the following ngrok command to create a session that points to the port (80) where your local server is running.

ngrok http 80

After running the command, ngrok creates a tunnel to the localhost:80, and you’ll see a list of forwarding URLs that will point to your local server, as shown below.

Note the Web Interface URL to test it later (step three).

Generating URLs Pointing to Local Server
Generating URLs Pointing to Local Server

2. Next, click on the Status menu at the left panel on ngrok’s dashboard to access the status page. You’ll see the currently active URLs and client IP addresses like the one below on the status page.

Viewing Active Tunnel Endpoints
Viewing Active Tunnel Endpoints

3. Lastly, navigate to the Web Interface URL you noted in step one, and you’ll see the following page that lists your tunnel URLs. Click any of the links to test if they are accessible based on the response of the GET requests.

Accessing Web Interface URL
Accessing Web Interface URL

As you see below, you get a 502 Bad Gateway error since you don’t have an application running on port 8080 yet.

Switch back to your ngrok terminal, and press Ctrl + C to exit from the current ngrok session. You’ll start a new session after creating a local application in an HTML file in the following section.

Getting 502 Bad Gateway Error when Accessing Tunnel URLs
Getting 502 Bad Gateway Error when Accessing Tunnel URLs

If you’re only interested in inspecting some of them, you can filter the requests by many options. Click the Filter bar for filtering options like in the screenshot below, and you can apply as many filters as you want.

Applying Filters on Requests
Applying Filters on Requests

Testing HTTP Requests with Apache Web Server

Getting the 502 Bad Gateway error doesn’t mean it’s the end of the world. If no application is running on port 80, why not create one? You’ll create an index.html page in the Apache webserver for testing HTTP requests to the webserver.

If you have any other server running on port 80, which works with HTTP requests like an XAMPP server, you can test ngrok using that server instead.

1. Create an index file name index.html in the default Apache directory (Apache/htdocs), and add the following code to the index.html file.

The code below prints a header text (Testing Local Website with Ngrok Proxy) on a web page.

<html> 
   <body>  
      
     <h2>Testing Local Website with Ngrok Proxy</h2> 
   
  </body> 
</html>

2. Next, launch your ngrok agent, and rerun the below command to start a new ngrok session that points to port 80.

ngrok http 80

Not all services are HTTP-based. Ngrok TCP tunnels allow you to expose any networked service over TCP with this command: ngrok tcp 1234

3. Navigate to the Web Interface URL again on your browser as you did in the “Starting a Tunnel for the Local Host” section (step three).

Click on any of the links listed, and a new tab opens, redirecting your local webpage (index.html), as shown below.

Testing Local Website
Testing Local Website

4. Lastly, switch back to ngrok Web Interface, and you’ll see the 200 OK message, which indicates the GET request succeeded.

Viewing Successful Response to GET Request
Viewing Successful Response to GET Request

Perhaps you’re looking to see more information about the running tunnels. If so, click on the Status tab, and you’ll see a page like the one below. The Status page lets you inspect detailed tunnel information you can use for configuration.

Viewing all Tunnel Status
Viewing all Tunnel Status

Replaying Requests with Modifications

You’ve tested your tunnels and verified a successful response from the requests. But what if you plan to re-test the tunnels after modifying the same request? ngrok’s Web Interface lets you modify requests in a developer-friendly fashion to test new behavior in an application server.

But did you know that you can replay a particular request with a single click? Yes! And the request comes with every aspect of HTTP requests, including the method, path, headers, trailers, and request body.

Click on the drop-down arrow next to the Replay button, then click on Replay with Modifications, as shown below. A pop-up page opens where you can modify requests.

Initiating Modifying Requests
Initiating Modifying Requests

Now click on the minus (-) buttons to remove headers or + Add Header to add more, then click on the Replay button at the bottom of the Modify Request page.

At this point, you can keep modifying requests to your heart’s content.

Modify Request Attributes
Modify Request Attributes

Conclusion

In this tutorial, you’ve learned how to set up ngrok on your system. You’ve exposed a locally hosted web application over the internet and tested your endpoints are accessible. ngrok establishes both HTTP and HTTPS endpoints, making it useful for testing integrations with third-party services or APIs.

Moreover, the replay functionality of ngrok is highly beneficial in testing API calls or webhooks as you can quickly inspect all headers and request/response data in one place.

Now, why not run ngrok on Mac/Windows/Linux and share your environment with anyone outside your network?

Hate ads? Want to support the writer? Get many of our tutorials packaged as an ATA Guidebook.

Explore ATA Guidebooks

Looks like you're offline!