How to setup self-hosting ngrok on Ubuntu with Mac OS X client
Beware this content is over a year old and considered stale. It may no longer be accurate and/or reflect the understanding of the author but remains here for reference only. Please keep this in mind as you use this content.
Note: This applies to ngrok v1.x - unfortunately ngrok 2.x hasn’t yet made their source code available.
We’ve been testing a third-party API that uses webhooks to notify your system when particular events take place that you might be interested in.
As you might appreciate, testing webhooks in a local development environment is tricky because these external APIs or sandbox developer environments have no way of pinging (sending a request to) your URI because its running on localhost which is not accessible to the outside world.
However, what if you needed to temporarily expose some code to the world for a short period of time? In our case, so you could actually test your reciever for the webhook?
Enter, ngrok. Out the box, it works. After you install the client binary, you tell it which port you want to expose and it generates a random URL for you.
At this point your local code at
http://localhost/webhook.php becomes accessible at
And that is all good and well for one-off hooks, but what if you needed to link to that endpoint reliably from time-to-time? Each time you run ngrok, it will generate a new random subdomain.
Well, as it turns out, you can specify a subdomain (testing.ngrok.io) but that means you’ll need to reserve that subdomain to avoid someone else using it. As it turns out, that will require a paid account.
OK, what’s my alternative? Host it yourself.
This is what you need to do to run a copy of your own ngrok so you can specify you’re own subdomains under a custom domain name you might own (ngrok.example.com).
You’ll need access to pick a domain name you have control over. Decide what the base domain name is going to be.
The most common approach is to use a subdomain. For example, if I own example.com, I would want to setup a subdomain ngrok.example.com so that all tunnels generated would be under that namespace.
It’s important that you check whether your domain name registrar or the interface you’re using to manage your domain name allows you to specify a wildcard entry for a domain name.
I have some domain names with 1&1, it seems their domain name mangement capability are very poor. It is currently impossible to create a wildcard subdomain entry.
You need to be able to create an A-Record entry with a wildcard (asterisk) like this:
Setup the A-Record so that any subdomain request points to the IP address of the server that will be hosting ngrok.
Make sure you have all the necessary build tools and Go langauge. The Mercurial version control is needed for the ngrok dependencies and Git is needed to clone the main repository.
sudo apt-get install build-essential golang mercurial git-core
Clone the repository to helpful location.
Before you compile, you’ll need to create your own self-signed SSL/TLS certificate to secure the link between the client and the server.
This means you cannot use the official or standard ngrok client as the built-in certificate is set to authenticate with the official ngrok server. We will have to compile a custom client with a self-signed certfiicate for this to work.
To generate the self-signed certificate, you can use this script as follows:
That should generate a collection of private keys and certicates which will expire in about 10,000 days (~27.4 years)!
Next, ensure the self-signed certificate replaces the standard certifciate included in the source code, so when the client is compiled, it uses this one instead.
Here we just move the original out of the way and symlink the one we want included.
Note, the following environment flags assume your server is Ubuntu 64-bit (you could omit the flags as the default is for Linux) and your client is Mac OS X 64-bit.
For other environment options, see here:
You should have the executable binaries which may need to made executable:
- Run Ngrok on Your Own Server Using Self-Signed SSL Certificate (svenbit)
- How to run your own ngrokd server (inconshreveable)
After you’ve setup you’re own copy of ngrok, you can swap it out for the one installed with Homebrew:
ngrok TLS script