Quickstart: ngrok-rust
This quickstart will use the ngrok-rust Agent SDK to put a Rust app on the internet and secure it so that only you can access it.
What is ngrok-rust?
ngrok-rust is an open-source, idiomatic Rust crate for embedding secure ingress directly into your Rust applications. If you’ve used the ngrok agent before, you can think of ngrok-rust as the agent packaged as a Rust crate.
ngrok-rust enables you to serve Rust services on the internet in a single line
of code without setting up low-level network primitives like IPs, certificates,
load balancers, and ports. Applications using ngrok-rust listen on ngrok’s
global ingress network and your app gets incoming streams with tokio’s
AsyncRead
and AsyncWrite
traits — compatible with
axum::Server::builder()
and hyper::Server::builder()
. This makes it
incredibly easy to drop ngrok-rust into any application that uses the popular
axum or hyper crates.
You may want to open the ngrok-rust package documentation on docs.rs as you work through this guide.
Step 1: Install ngrok-rust
First, create a new Rust app and install the ngrok
, axum
and tokio
crates. This guide assumes you already have Rust
installed.
mkdir ngrok-rust-quickstart
cd ngrok-rust-quickstart
cargo init
cargo add ngrok -F axum
cargo add axum
cargo add tokio -F rt-multi-thread -F macros
Step 2: Create your app
In the ngrok-rust-quickstart
directory, create the following main.rs
file:
use axum::{routing::get, Router};
use ngrok::prelude::*;
use std::error::Error;
#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
// build our application with a route
let app = Router::new().route("/", get(|| async { "Hello from ngrok-rust!" }));
// listen on ngrok ingress (i.e. https://myapp.ngrok.dev)
let listener = ngrok::Session::builder()
.authtoken_from_env()
.connect()
.await?
.http_endpoint()
.listen()
.await?;
println!("App URL: {:?}", listener.url());
axum::Server::builder(listener)
.serve(app.into_make_service())
.await?;
Ok(())
}
- Lines 11-17: connect to ngrok and listen for HTTP traffic on a randomly-assigned endpoint URL
- Line 18: print your app's endpoint url
- Line 19-21: start an axum web server handling connections from the ngrok listener
Step 3: Run it!
Copy the ngrok authtoken on your dashboard. You may need to sign up for ngrok if you haven't already.
Run your application with your authtoken in the environment:
NGROK_AUTHTOKEN="<TOKEN>" cargo r
Your terminal will print out your app's URL. Visit the URL in a browser and confirm you see "Hello from ngrok-rust!". Your Rust application is now live on the internet, with a URL that anyone on the internet can access. Test it out by sending it to a friend!
Step 4: Always use the same domain
If you want to keep the same URL each time you run your app, create a static
domain on your dashboard and
then update your Session::builder
chain to use it. Stop your app with
Ctrl+C
, update your code and then rerun it:
let listener = ngrok::Session::builder()
.authtoken_from_env()
.connect()
.await?
.http_endpoint()
.domain("jumpy-red-mollusk.ngrok-free.app")
.listen()
.await?;
Step 5: Secure your app
You may not want everyone to be able to access your application. ngrok can quickly add authentication to your app with a few lines of code.
If your Google account is alan@example.com
, you can restrict access only for
yourself by modifying your main.rs
file to:
use axum::{routing::get, Router};
use ngrok::prelude::*;
use ngrok::config::*;
use std::error::Error;
#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
// build our application with a route
let app = Router::new().route("/", get(|| async { "Hello World!" }));
// listen on ngrok ingress (i.e. https://my-rust-app.ngrok.dev)
let listener = ngrok::Session::builder()
.authtoken_from_env()
.connect()
.await?
.http_endpoint()
.oauth(OauthOptions::new("google").allow_email("alan@example.com"))
.listen()
.await?;
println!("App URL: {:?}", listener.url());
axum::Server::builder(listener)
.serve(app.into_make_service())
.await?;
Ok(())
}
- Line 17: Require visitors to authenticate with Google before they access your application. You can choose other providers. Only allow
alan@example.com
access to the application
Run your app again and visit the URL it prints in the terminal.
Anyone accessing your app will be prompted to log in with Google and only your account will be allowed to access it. Keep in mind that when you restarted ngrok, your app's URL changed, so make sure to visit the new one.
Next Steps
- Read the ngrok-rust package documentation on docs.rs
- Star the ngrok-rust GitHub repo and follow it for updates.
- Browse Rust examples of HTTP Endpoints of other ways ngrok can augment your application.
- Bring your own custom domain to ngrok
- Create connectivity for non-HTTP protocols such as SSH, RDP, or game servers using TCP Endpoints