Tunnelling your Local Development Environment with Ngrok

Sometimes you may want to test out your local dev features or code changes on other devices than your local development machine, or perhaps you want another colleague to be able to try out your code. You could push it to your QA or Staging environment, but it might not be ready and you’d have to wait for your CI to run. Instead, you can do this using tunnels with ngrok.

If you’re developing a web application, you will need to create three tunnels, usually for your:

• Database
• Backend server (e.g Python Flask API)
• Client app (usually served with Webpack)

You should have all of these up and running locally and note down the port numbers they’re running on.

Step by Step Instructions

1. Sign up and create a free account on Ngrok
2. Now, download ngrok by following these instructions for your operating system. Make sure that ngrok is recognisable in your terminal. You can test this our by trying out the command ngrok — version in your terminal which should result in something like:

If you’ve installed ngrok successfully on your local machine, you should be able to execute this command.

3. Create a .yml file and give it a name, here we’ll call it ngrok_unibuddy.yml. This YAML below tells ngrok to tunnel my webpack client app at port 4300, my backend server on port 5000 and database on port 27017. You will need to use your auth_token to replace <your_auth_token> in the file. You can find in your ngrok dashboard, by clicking on “Auth” and then finding it under tunnel token.

authtoken: <your_auth_token>
tunnels:
    your_client_app:
       proto: http
       addr: 4300
       host_header: localhost:4300
       bind_tls: false
    your_server:
       proto: http
       addr: 5000
       host_header: localhost:5000
       bind_tls: false
    your_database:
       proto: tcp
       addr: 27017

Note: By default ngrok creates both a tls and non-tls tunnel, we’re specifying non-tls tunnels in this YAMl to get around the ngrok free account limit which only allows 4 tunnels. If you need both or simply need more tunnels, then you will have to upgrade your account.

4. Start your tunnels by executing the following command from the directory that contains your ngrok_unibuddy.yml:

ngrok start --all -config=./ngrok_unibuddy.yml

To learn more about the ngrok start command and others, see the ngrok docs.

You will now have three tunnels running and your terminal should look similar to this:

Tunnels up and running!

5. Lastly, you will need to point your client app to the tunnelled server (in the image of my terminal above it’s the ngrok.io address pointing to localhost:5000). Depending on your client application, you either have this hard coded (not recommended) and will need to change that or like me, you have the client app URL set based on an environmental variable. I simply have to do a yarn start while setting the API_URL env var- this points my client app to the new tunnelled server:

API_URL="http://b189cc87.ngrok.io" yarn start

Open your web app on any device

If you’ve done everything correctly you can now open your client app (use the tunnel ngrok.io address pointing to it) on any device. Simply share the client app ngrok address with a team member or friend to try out your shiny new code or feature that’s still in development on your local machine!

Now when I open up my client app using the address from the example from above: http://02dad245.ngrok.io/unibuddy/test-event

I see my client app successfully! 🎉

Our Live Event client app at Unibuddy

You can create tunnels for other apps or servers similarly by modifying the YAML, once again — the ngrok docs are your friend!