Expose Clojure Service using Ngrok
Exposing a local running services can be valuable when writing apps and web-hooks for Cloud API products, e.g. Slack, Atlassian Confluence, Hasura, Salesforce, etc.
ngrok exposes local networked services behinds NATs and firewalls to the public internet over a secure tunnel.
Create a free ngrok account to get an authorisation token for use with the ngrok agent to create a secure tunnel. Or add an SSH public key to use SSH reverse tunnel with the ngrok service.
ngrok has additional paid services, although they are not required for exposing local services.
Example Clojure Serviceλ︎
Practicalli Clojure CLI Config defines the :project/create alias to generate a new project from a template. The practicalli/service template creates a project for developing web services with a REST API.
Create a project called gameboard using donut system to manage service components
clojure -T:project/create :template practicalli/service :name practicalli/gameboard :component donut
Change into the gameboard directory
make run (clojure -M:run/service) to run the service locally, serving an API endpoint on http://localhost:8080
Alternatively,
make docker-buildto run the service via a docker container (assuming Docker is running locally).
Install ngrokλ︎
Linux (apt) operating system, add a ngrok repository key and install the ngrock package
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | \
sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null && \
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | \
sudo tee /etc/apt/sources.list.d/ngrok.list && \
sudo apt update && sudo apt install ngrok
MacOS install with HomeBrew:
Ngrok download page for other installation options or use an SSH reverse tunnel without need to install the ngrok agent.
Setup ngrokλ︎
Create an account with multi-factor authentication.
Login to the Ngrok dashboard to obtain the Authtoken (tunnel credential) for the ngrok account. The token is used by the ngrok agent to log into the ngrok account when starting a tunnel.
Claim a free static domain to avoid random URLs. Creating a domain of your own choosing is a paid service on ngrok.
ngrok config fileλ︎
Use a configuration file to define one or more tunnels for use with the ngrok agent.
Open the default ngrok configuration file for editing:
Or open the yaml file from the default configuration location
- Linux:
~/.config/ngrok/ngrok.yml - MacOS (Darwin):
~/Library/Application Support/ngrok/ngrok.yml
authtoken: ***************************_*********************
version: 2
tunnels:
custom_tunnel_name:
proto: http
hostname: free-static-domain-name.ngrok-free.app
addr: 127.0.0.1:8080
# -------------------------
# Additional options
# -------------------------
# auth: "username:password"
# host_header: rewrite
# inspect: true
# bind_tls: true
Start the tunnel using the command line.
Or start all tunnels in the configuration file
Inspecting trafficλ︎
Open http://localhost:4040 to view the ngrok web interface, allowing inspection of traffic over the secure HTTP tunnel (TCP & TLS tunnel inspection not supported).
The web interface lists each request through the tunnel and selecting a request shows all the details of that request.
- Request body validation (JSON, XML data)
- Filter requests on request path, response status code, response body size, request duration, or any header value
- Replay requests, optionally modifying a request first
- ngrok agent status to help with troubleshooting the tunnel connetion
Ngrok web inspection interface
SSH reverse tunnelλ︎
ngrok can be used with SSH reverse tunneling (ssh -R), avoiding the need to install the ngrok agent.
Add an SSH public key to the ngrok dashboard, Tunnels > SSH Public Keys
Run the command to open an SSH reverse tunnel to ngrok
ngrok Docker serviceλ︎
Use a Docker image containing ngrok to avoid installing the ngrok agent.
ngrok provides the ngrok/ngrok docker image. Practicalli recommends using the alpine image variant for minimal resource use.
docker run -it -e NGROK_AUTHTOKEN=$NGROK_AUTH_TOKEN ngrok/ngrok:alpine http 8080 --domain=free-static-domain-name.ngrok-free.app
Add an ngrok service to Docker compose.yaml, optionally adding a volume and port configuration.
To manage ngrok configuration effectively, add an ngrok.yml configuration to the root of the directory where the ngrok image is to be run. The ngrok.yml config is mounted to /etc/ngrok.yml in the Docker container, allowing an simple way to update the config.
services:
ngrok:
image: ngrok/ngrok:alpine
restart: unless-stopped
command:
- "start"
- "--all"
- "--config"
- "/etc/ngrok.yml"
volumes:
- ./ngrok.yml:/etc/ngrok.yml
ports:
- 4040:4040
Run all the services defined in the Docker compose.yml file, optionally with the --detatch flag to run in the background of the shell.
Or run only the ngrok service
Add an ngrok service to a Docker compose configuration to build & run the clojure service in conjunction with a multi-stage dockerfile.
Secure public endpointsλ︎
ngrok agent allows security to be dynamically added to any public endpoint, with IP restrictions
- HTTP Basic Authentication
- OAuth 2.0
- OpenID Connect
- SAML
- Webhook Verification
- Mutual TLS
Summaryλ︎
ngrok is a secure way to expose locally running services that integrate with cloud services and can help speed development by providing faster feedback than running a full deployment cycle.
ngrok agent works on multiple operating systems and can be run in a Docker container. An SSH reverse tunnel can be used for zero agent install approach.
Using ngrok only because the continuous integration process is very time consuming is a strong indication that time should be invested in improving the CI workflow, ensuring the minimal amount of work is required to create a repeatable build.
practicalli GitHub profile I @practical_li
Thank you.
Practical.li Website