In some use cases, we might need or want to expose our service running in local to public. So it is accessible via internet. Whether it is only for demo to client, troubleshooting staging environment, or just a weekend project. Ngrok can be quite helpful in these use cases.
Installation
Ngrok can be installed either using homebrew or manually download the binary then put in your $PATH directory. e.g: /usr/local/bin
To install using Homebrew, use this command brew cask install ngrok.
You can see all available options after your installation completed
❯ ngrok
NAME:
ngrok - tunnel local ports to public URLs and inspect traffic
DESCRIPTION:
ngrok exposes local networked services behinds NATs and firewalls to the
public internet over a secure tunnel. Share local websites, build/test
webhook consumers and self-host personal services.
Detailed help for each command is available with 'ngrok help <command>'.
Open http://localhost:4040 for ngrok's web interface to inspect traffic.
EXAMPLES:
ngrok http 80 # secure public URL for port 80 web server
ngrok http -subdomain=baz 8080 # port 8080 available at baz.ngrok.io
ngrok http foo.dev:80 # tunnel to host:port instead of localhost
ngrok http https://localhost # expose a local https server
ngrok tcp 22 # tunnel arbitrary TCP traffic to port 22
ngrok tls -hostname=foo.com 443 # TLS traffic for foo.com to port 443
ngrok start foo bar baz # start tunnels from the configuration file
VERSION:
2.3.35
AUTHOR:
inconshreveable - <alan@ngrok.com>
COMMANDS:
authtoken save authtoken to configuration file
credits prints author and licensing information
http start an HTTP tunnel
start start tunnels by name from the configuration file
tcp start a TCP tunnel
tls start a TLS tunnel
update update ngrok to the latest version
version print the version string
help Shows a list of commands or help for one command
Testing
Let’s create 1 example service using python http server. We will use /tmp for this example. Here are the steps.
- Create 1 directory in /tmp named testing then create 1 html file and insert sample content
mkdir -p /tmp/testing
touch /tmp/testing/index.html
cat << EOF > /tmp/testing/index.html
<!doctype html>
<html lang="en">
<head>
<!-- Required meta tags -->
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<!-- Bootstrap CSS -->
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css" integrity="sha384-JcKb8q3iqJ61gNV9KGb8thSsNjpSL0n8PARn9HuZOnIxN0hoP+VmmDGMN5t9UJ0Z" crossorigin="anonymous">
<title>Hello, world!</title>
</head>
<body>
<h1>Hello, world!</h1>
<!-- Optional JavaScript -->
<!-- jQuery first, then Popper.js, then Bootstrap JS -->
<script src="https://code.jquery.com/jquery-3.5.1.slim.min.js" integrity="sha384-DfXdz2htPH0lsSSs5nCTpuj/zy4C+OGpamoFVy38MVBnE+IbbVYUew+OrCXaRkfj" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.1/dist/umd/popper.min.js" integrity="sha384-9/reFTGAW83EW2RDu2S0VKaIzap3H66lZH81PoYlFhbGU+6BZp6G7niu735Sk7lN" crossorigin="anonymous"></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/js/bootstrap.min.js" integrity="sha384-B4gt1jrGC7Jh4AgTPSdUtOBvfO8shuf57BaghqFfPlYxofvL8/KUEfYiJOMMV+rV" crossorigin="anonymous"></script>
</body>
</html>
EOF
- Run python http server inside /tmp/testing directory
cd /tmp/testing
python3 -m http.server
serving HTTP on :: port 8000 (http://[::]:8000/)
- Test the result in browser and make sure it is accessible
- Expose to public using ngrok
ngrok http http://localhost:8000
- Wait until the
Session Statusbecomes online. And see theForwardingfield. You can test either using the one with http or https
ngrok by @inconshreveable (Ctrl+C to quit)
Session Status online
Account Frans Caisar Ramadhan (Plan: Free)
Version 2.3.35
Region United States (us)
Web Interface http://127.0.0.1:4040
Forwarding http://52e029757f0d.ngrok.io -> http://localhost:8000
Forwarding https://52e029757f0d.ngrok.io -> http://localhost:8000
Connections ttl opn rt1 rt5 p50 p90
0 0 0.00 0.00 0.00 0.00
- Test by opening the public URL. In above example we will test with
https://52e029757f0d.ngrok.io
Conclusion
- Ngrok is a powerful tool to expose your locally running services to public. This can be helpful during early bootstraping, do client demo, or just hosting your public blog locally.
- Ngrok also provides paid options with some additional feature. Such as reserved domain names, custom subdomains, Google Apps SSO, End to end TLS tunnels, etc. Detailed information can be seen in Pricing page.