Skip to main content

Quickstart: ngrok-go

This quickstart will use the ngrok-go Agent SDK to put a Go app on the internet and secure it so that only you can access it.

What is ngrok-go?​

ngrok-go is an open-source, idiomatic Go package for embedding secure ingress directly into your Go applications. If you’ve used the ngrok agent before, you can think of ngrok-go as the agent packaged as a Go library.

ngrok-go enables you to serve Go applications on the internet in a single line of code without configuring network minutia like routing, load balancers, certificates, or ports. Applications using ngrok-go listen on ngrok’s global network and your app gets the same net.Listener interface it would get if it had listened on a local port. This makes it incredibly simple to drop ngrok-go into any existing Go code.

You may want to open the ngrok-go package documentation on pkg.go.dev as you work through this guide.

Step 1: Install ngrok-go​

Create a new Go module and install ngrok-go. This guide assumes you already have Go installed.

mkdir ngrok-go-quickstart
cd ngrok-go-quickstart
go mod init ngrok-go-quickstart
go get golang.ngrok.com/ngrok

Step 2: Create your app​

In the ngrok-go-quickstart directory, create the following main.go file:

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"

	"golang.ngrok.com/ngrok"
	"golang.ngrok.com/ngrok/config"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	listener, err := ngrok.Listen(ctx,
		config.HTTPEndpoint(),
		ngrok.WithAuthtokenFromEnv(),
	)
	if err != nil {
		return err
	}

	log.Println("App URL", listener.URL())
	return http.Serve(listener, http.HandlerFunc(handler))
}

func handler(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "<h1>Hello from ngrok-go!</h1>")
}
In this code
  • Lines 20-23: connect to ngrok and create a net.Listener for a randomly-assigned HTTP endpoint URL
  • Line 22: use the value of the NGROK_AUTHTOKEN environment variable to auth with ngrok
  • Line 29: serve a simple http handler using Go's net/http.Serve function

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>" go run main.go

Your terminal will print out your app's URL. Visit the URL in a browser and confirm you see "Hello from ngrok-go!". Your Go 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 ngrok.Listen function call to use it. Stop your app with Ctrl+C, update your code and then rerun it:

	listener, err := ngrok.Listen(ctx,
		config.HTTPEndpoint(
			config.WithDomain("jumpy-red-mollusk.ngrok-free.app"),
		),
		ngrok.WithAuthtokenFromEnv(),
	)

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.go file to:

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"

	"golang.ngrok.com/ngrok"
	"golang.ngrok.com/ngrok/config"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	listener, err := ngrok.Listen(ctx,
		config.HTTPEndpoint(
			config.WithOAuth("google",
				config.WithAllowOAuthEmail("alan@example.com"),
			),
		),
		ngrok.WithAuthtokenFromEnv(),
	)
	if err != nil {
		return err
	}

	log.Println("App URL", listener.URL())
	return http.Serve(listener, http.HandlerFunc(handler))
}

func handler(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w,
		"<h1>Hello from ngrok-go, %s.</h1>",
		r.Header.Values("ngrok-auth-oauth-email"),
	)
}
In this code

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.

Here's the full result:

ngrok go in action

Next Steps​