Self‑Host ngrok: Build Your Own Public Tunnel for Front‑End Development

What is ngrok?

ngrok is an open‑source tool that creates a secure tunnel from a local machine to the public internet, allowing HTTP or TCP services to be accessed via a generated sub‑domain.

Prerequisites

You need a publicly reachable server with a domain name pointing to it.

1. Install Go on the server

sudo yum install golang

Verify with go version and set environment variables in ~/.zshrc or ~/.bash_profile:

export GOPATH=$HOME/go
PATH=$PATH:$HOME/.local/bin:$HOME/bin:$GOPATH/bin

Reload the shell:

source ~/.zshrc

2. Install Git

Install Git (details omitted) to clone the source code.

3. Fork and clone the ngrok repository

$ mkdir -p ~/go/src/github.com/mamboer
$ cd ~/go/src/github.com/mamboer
$ git clone https://github.com/mamboer/ngrok.git

4. Patch the source

Edit src/ngrok/log/logger.go and replace the import

code.google.com/p/log4go → github.com/alecthomas/log4go

5. Generate a self‑signed certificate

Assume the base domain is ngrok.fex.im. Run:

$ cd ngrok
$ openssl genrsa -out rootCA.key 2048
$ openssl req -x509 -new -nodes -key rootCA.key -subj "/CN=ngrok.fex.im" -days 5000 -out rootCA.pem
$ openssl genrsa -out device.key 2048
$ openssl req -new -key device.key -subj "/CN=ngrok.fex.im" -out device.csr
$ openssl x509 -req -in device.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out device.crt -days 5000

The command creates six files in the ngrok directory.

6. Replace default certificates

cp rootCA.pem assets/client/tls/ngrokroot.crt
cp device.crt assets/server/tls/snakeoil.crt
cp device.key assets/server/tls/snakeoil.key

7. Compile the server and client

$ make release-server   # builds ngrokd
$ make release-client   # builds ngrok

The binaries appear in the bin folder. Move ngrokd to ~/go/bin for easy access.

8. Run the ngrok server

ngrokd -domain="ngrok.fex.im" -httpAddr=":8088" -httpsAddr=":8089"

The server logs show it is listening on ports 8088 (HTTP), 8089 (HTTPS) and 4443 (control).

9. Add DNS records

Create two A records for ngrok.fex.im and *.ngrok.fex.im pointing to the server’s IP.

10. Build the client on macOS (if needed)

Install Go via Homebrew:

brew update
brew install go

Clone the same source, compile, and place the resulting ngrok binary in $GOPATH/bin.

11. Verify the setup

Create ngrok.cfg:

server_addr: "ngrok.fex.im:4443"
trust_host_root_certs: false

Run the client to expose a local service:

$ ngrok -subdomain demo -config=/path/to/ngrok.cfg 8080

Serve a test site (e.g., using node-static and a cloned repo).

Visit demo.ngrok.fex.im:8088 in a browser – the site should appear.

Open localhost:4040 to view request logs.

Important notes

The server_addr value in the client config must exactly match the -domain flag and the certificate’s NGROK_BASE_DOMAIN; otherwise the server will reject the connection with a “bad certificate” error.

Using the public ngrok service

Download the pre‑built client ( http://fex.im/files/ngrok for Linux or the macOS release from GitHub) and place it in /usr/local/bin. Set ownership and permissions:

sudo chown $(whoami):staff ngrok
sudo chmod 777 ngrok

Run with the same configuration as above.