Expose your local environment to the world with ngrok

June 28, 2016Matthieu Auger3 min read

thumbnail

Have you ever wanted to expose a local server to the entire internet? It may sound scary but can be really useful. Use-cases are infinite, here are a few:

  • You are developing a web application on your computer and you need to see instantly your modifications on a specific device or browser (smartphone, tablet, internet explorer...) without deploying it again and again.
  • You are developing an application which works with webhooks, for example GitHub webhooks.
  • You need to download some files from a coworker computer and you're far from him, or simply don't want to bother with a USB key.
  • You are out of the office and need to access an IP filtered server.

Multiple solutions exist, open-source or not but my favorite is ngrok and you can learn to use it in just 2 minutes. Installation is quite easy, head over to https://ngrok.com/download and follow instructions.

What does it do?

In two words: it takes a local port number in input, and offers you a unique URL, accessible by anyone. For example, let's assume you are building a very basic web application in php

echo "Hello World" > index.php
php -S localhost:8000

Now a web server is running your computer's port 8000. When you hit http://localhost:8000 on a browser, you can see your application.

server

How to expose it to the world? It's simple, just type:

ngrok http 8000

After a few seconds, ngrok will output a few informations, the most important one being "Forwarding": You now have a unique public URL bound to your local server. Paste it, share it, anyone can use it.

ngrok-up

Real-life use-cases

Making bugfix easier on mobile devices

Ever had this weird bug on this specific device that you can't reproduce anywhere else? Your responsive website is displaying badly on your blackberry's boss? Sometimes you just don't know what is the issue and need to code in the dark, test something, see what is happening and repeat. ngrok eases this kind of workflow by preventing you to deploy your modifications again and again.

Developing with webhooks

Webhooks are everywhere, GitHub, Slack, Mandrill, Trello, many applications use them. They allow you to build tools that will be notified when an event occurs. But these applications need public URL to send the payloads to. Tunneling your local environment with ngrok will help you during development process. The GitHub documentation is a good start if you want to get into it.

Dowload a large file from a remote coworker's computer

Your coworker has downloaded a large file and you want to get it? It can be anything, latest dump of your production database, a base virtual machine, heavy CSV. With ngrok, you can simply run a server (for example PHP built-in server) and expose your file:

  • Put your largefile.avi file into a folder
  • Run php -S localhost:8000 on that folder
  • Run ngrok http 8000 (let's assume generated URL is https://bc153101.ngrok.io)
  • Share the url https://bc153101.ngrok.io/largefile.avi

Access a secure server

Two weeks ago a coworker was out of the office and needed to quickly access one of his client's production server which is IP restricted. How do we managed to do that?

  • First I created him an account coworker on my laptop
  • Then I used ngrok to expose my SSH server: ngrok tcp 22. The result was: tcp://0.tcp.ngrok.io:15602
  • He logged into my machine with: ssh -A -p 15602 coworker@0.tcp.ngrok.io. The -Aoption ensured its SSH public key was forwarded in order to log into the production server.
  • Then he was able to run ssh hisclientserver

Conclusion

”I want to expose a local server behind a NAT or firewall to the internet”. The ngrok promise is simple yet powerful. You should definitively think about it next time you struggle with public/private networks, firewalls or just want to get your local environment available to someone. And of course please remain careful with what you expose, and to whom.

Any other use-case comes to your mind? Please feel free to tell us in the comment section.

Matthieu Auger

Matthieu Auger

Web Developer at Theodo