Using ngrok is a great way to quickly demo/show your development to other people or for other purposes that you can think of by creating a tunnel from your local computer to the internet and the best part is it is free, you don’t even need to sign up to use its service although signing up will provide you with additional features and you can even pay for even more additional features available for paid user. You can read more about the features from ngrok official website: https://ngrok.com.

And oh, did I mention that it is actually open source? You can even run ngrok from your own server if you want to, maybe to get better latency (I think ngrok official server is locatedin US) or just to have your very own personal tunnel server which you can control. So with that said, let’s get started and run ngrok in your own server.

First you will need to install the build tools first in your linux installation if you haven’t done so since you are going to build and compile your own ngrok’s server and client. I’m using Ubuntu in this tutorial, so you can install it by running the following command:

sudo apt-get install build-essential

Next you will need to install go language tools as well since ngrok is developed using go language.

sudo apt-get install golang

Ngrok also relies on mercurial (version control) so you will need to have it installed in your system otherwise it won’t build.

sudo apt-get install mercurial
Install all the required tools/packages

Once you have everything installed, you are set to build and compile your own ngrok’s server and client. So, clone ngrok’s github into your working directory (or whatever directory you wanted), and run the following command to clone ngrok’s github and change your working directory to ngrok:

git clone https://github.com/inconshreveable/ngrok.git ngrok
cd ngrok
Clone ngrok repository

By the way, you can find ngrok’s github page here: https://github.com/inconshreveable/ngrok

Once it has finished cloning ngrok to your local machine, there is yet another thing you will need to do before you can build and compile your very own ngrok server and client and that is to create your own self-signed SSL certificate and this is required because ngrok provides the secure tunnel via TLS and in order for both the client and server to work you will need to build and compile ngrok using your self signed SSL certificate and these are linked to each other. So you cannot connect to your self-signed ngrokd server via the official ngrok client as both the server and client need to be signed using the same certificate.

So let’s get  started by creating the SSL certificate. You can create the certificate by running the following command:

openssl genrsa -out base.key 2048
openssl req -new -x509 -nodes -key base.key -days 10000 -subj "/CN=[NGROK_BASE_DOMAIN]" -out base.pem
openssl genrsa -out server.key 2048
openssl req -new -key server.key -subj "/CN=[NGROK_BASE_DOMAIN]" -out server.csr
openssl x509 -req -in server.csr -CA base.pem -CAkey base.key -CAcreateserial -days 10000 -out server.crt
Generate certificate pair for ngrok server and client

Replace [NGROK_BASE_DOMAIN] (tunnel.svenbit.com in the screenshot) in the command stated above with the base domain of your choice where you wish to run your ngrok from. For example if you are planning to run your ngrok tunnels from [whatever-tunnel].yourdomain.com, set the [NGROK_BASE_DOMAIN] to yourdomain.com, or if you are planning to run your ngrok tunnels from *.ngrok.yourdomain.com subdomain, set the [NGROK_BASE_DOMAIN] to ngrok.yourdomain.com. And if you notice the following files will be generated as a result of the commands that we run earlier above:

- base.key
- base.pem
- base.srl
- server.crt
- server.csr
- server.key

With that said you also need to setup wildcard ( * ) A record that points to your ngrok’s server IP address, configuration may vary on different domain registrars so you may want to check with your domain registrar about the details. I’m using namecheap for as my domain registrar and I’m going to run ngrok from tunnel subdomain (svenbit.com), so all I need to do is to add a wildcard A record under that subdomain that points to my ngrok’s server:

Setup host record for ngrok

Here’s a few more example:

Ngrok Base Domain Hostname Ngrok Tunnel Url
yourdomain.com * [ngrok-generated-url].yourdomain.com
tunnel.yourdomain.com *.tunnel [ngrok-generated-url].tunnel.yourdomain.com
ngrok.yourdomain.com *.ngrok [ngrok-generated-url].tunnel.yourdomain.com
tunnel.ngrok.yourdomain.com *.tunnel.ngrok [ngrok-generated-url].tunnel.ngrok.yourdomain.com

Now that you have generated your own certificate and configured your domain all you need to do left is to build/make ngrok, but first you will need to replace ngrok’s default client certificate file located at assets/client/tls/ngrokroot.crt** with the one that you have just created:

cp base.pem assets/client/tls/ngrokroot.crt
Replace default ngrok client certificate with the one that you have just created

Now build/make the executable for both the server (release-server) and client (release-client), it may takes a while:

make release-server release-client
Make ngrok server and client

Once it is done, the executable will be available inside /bin directory: ngrok is the client executable and ngrokd is the server executable. You may need to make the file executable first by running the following command:

chmod +x ngrokd
chmod +x ngrok

And also, take note that the default executable generated is for Linux.

Running Ngrok Server

To start ngrok server, you will need server.key and server.crt that we generated earlier, so I suggest copying the executable (ngrokd) to some directory or to the server you wish to start ngrok server from along with the server.key and server.crt files together in one directory to make it easier (I have uploaded ngrokd executable along with the certificate files to my public server in the screenshot below):

Place the ngrokd (server) executable and the certificates together

And then you can start ngrok server by running the following command (you may need root permission, run with sudo or su or whatever . . .):

./ngrokd -tlsKey=server.key -tlsCrt=server.crt -domain="[NGROK_BASE_DOMAIN]" -httpAddr=":8080" -httpsAddr=":8081"
Fire up that ngrokd server!

Again, replace [NGROK_BASE_DOMAIN] with the very same domain that you specify when you generate the certificate file earlier. You can change the httpAddr port and httpsAddr to any port that you wanted, just make sure that it is accessible and is not used by other services.

Your ngrok server should now be accessible from the domain ([NGROK_BASE_DOMAIN]) and port that you specify. To test it out try accessing it from your web browser:

http://[Insert-random-word-here].[NGROK_BASE_DOMAIN]:[NGROK_PORT]

For example, since my ngrok base domain is tunnel.svenbit.com and I set the httpAddr port to 8080 I can test my ngrok server by accessing the following url:

http://putanythinghere.tunnel.svenbit.com:8080
Note: Cat is not included in ngrok default page

Note: Cat is not included in ngrok default page

Also, if you notice from the screenshot ngrok server and its tunnels will only be accessible via the subdomain of the base domain that you specified ([<strong>NGROK_BASE_DOMAIN]), so ngrok server will catch all any request (wildcard) made to the subdomains under ngrok base domain that you specified, and not the base domain itself.

And now that the server is running, next is to connect to the server using the client executable.

Running Ngrok Client

Now that you have run ngrok server, you can connect to the server using ngrok executable generated earlier. Again, this client can only be used to the ngrok server that you created earlier and cannot be use to connect to the official ngrok server due to the certificate pairing (they are made for each other @[email protected]). Copy ngrok client executable to the server or computer that you want to connect from. And create a configuration file in the same directory with the ngrok client executable, you can name it anything you want (config.txt, ngrok.cfg, my.config, etc. . .).

Just paste the following text into the configuration file:

server_addr: [NGROK_BASE_DOMAIN]:4443
trust_host_root_certs: false
Creating ngrok client configuration file #1

Creating ngrok client configuration file #2

Creating ngrok client configuration file #2

Again, for the million times, replace [NGROK_BASE_DOMAIN</b><strong>] with your own base domain. And if you are wondering trust_host_root_certs is set to false because the certificate is self-signed, and server_addr is well, where your ngrok server located at along with the port number where 4443 is the default access port for ngrok.

Once the config file is in place you can connect to your own ngrok server by running the following command, please replace [YOUR_CONFIG_FILE_NAME] with the name of the configuration file that you have just created:

./ngrok -subdomain testing -config=[YOUR_CONFIG_FILE_NAME] 80

The command above will allow you to connect to your local 80 port from  testing subdomain of your ngrok server, in this case it will be accessible from http://testing.tunnel.svenbit.com:8080. If you did not specify the -subdomain parameter ngrok will generate one for you.

Running ngrok client

Ngrok client in action

Ngrok tunnel test page

You can even use ngrok to tunnel tcp connection to specific port, for example for your MySQL Server, like so:

./ngrok -subdomain mydatabaseserver -config=[YOUR_CONFIG_FILE_NAME] -proto tcp 3306

For other usages, I suggest you read more about it from ngrok’s official page: https://ngrok.com/usage.

Well that’s it, now you have your own ngrok server which you can use for development purposes or anything that you find applicable.