Skip to main content

Download ngrok

ngrok is your app’s front door—and the fastest way to put anything on the internet.

SDK

Java

Installation

Setup an example by making a directory:

mkdir hello-ngrok && cd hello-ngrok

Install OpenJDK on your system here or use Homebrew:

brew install openjdk

Setup an example project:

mvn archetype:generate \
  -DgroupId=com.example \
  -DartifactId=demo-simple \
  -Dversion=1.0-SNAPSHOT \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DinteractiveMode=false

Edit your pom.xml to include ngrok-java dependencies:

demo-simple/pom.xml

<properties>
		...
		<ngrok.version>0.5.0</ngrok.version>
		<maven.compiler.source>YOUR_VERSION_HERE</maven.compiler.source>
	 	<maven.compiler.target>YOUR_VERSION_HERE</maven.compiler.target>
		...
</properties>
<dependencies>
		...
		<dependency>
			<groupId>com.ngrok</groupId>
			<artifactId>ngrok-java</artifactId>
			<version>${ngrok.version}</version>
		</dependency>
		<dependency>
			<groupId>com.ngrok</groupId>
			<artifactId>ngrok-java-native</artifactId>
			<version>${ngrok.version}</version>
			<classifier>${os.detected.classifier}</classifier>
			<scope>runtime</scope>
		</dependency>
		...
</dependencies>
<build>
		...
		<!-- add your preferred build plugins: maven-jar-plugin, exec-maven-plugin, etc -->
		<extensions>
				<extension>
						<groupId>kr.motd.maven</groupId>
						<artifactId>os-maven-plugin</artifactId>
						<version>1.7.0</version>
				</extension>
		</extensions>
		...
</build>

Put your app online

demo-simple/src/main/java/com/example/App.java

package com.example;

import com.ngrok.Session;

import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.charset.Charset;


public class App {
	public static void main(final String[] args) throws IOException {
		// Session.withAuthtokenFromEnv() will create a new session builder, pulling NGROK_AUTHTOKEN env variable.
		// You can get your authtoken by registering at https://dashboard.ngrok.com
		final var sessionBuilder = Session.withAuthtokenFromEnv().metadata("my session");
		// UTF-8 for encoding
		final Charset utf8 = Charset.forName("UTF-8");
		// Session.Builder let you customize different aspects of the session, see docs for details.
		// After customizing the builder, you connect:
		try (final var session = sessionBuilder.connect()) {
			// Creates and configures http listener that will be using oauth to secure it
			final var listenerBuilder = session.httpEndpoint().metadata("my listener");

			// Now start listening with the above configuration
			try (final var listener = listenerBuilder.listen()) {
				System.out.println("ngrok url: " + listener.getUrl());
				final var buf = ByteBuffer.allocateDirect(1024);

				while (true) {
					// Accept a new connection
					final var conn = listener.accept();

					// Read from the connection
					buf.clear();
					conn.read(buf);

					System.out.println(utf8.decode(buf));

					// Or write to it
					buf.clear();
					buf.put("HTTP/1.0 200 OK\n\nHello from ngrok!".getBytes(utf8));
					buf.flip();
					conn.write(buf);
					conn.close();
				}
			}
		}
	}
}

Run your Java app with your ngrok authtoken as an environment variable. for a free account to get your authtoken.

NGROK_AUTHTOKEN=<token> mvn clean install