Overview (java8-ngrok 1.4.14 API)

Packages
Package	Description
com.github.alexdlaird.exception	This package contains exceptions that can be thrown by `java-ngrok`.
com.github.alexdlaird.http	This package contains a simple, generic HTTP client, which can be used to interact with `ngrok`'s APIs.
com.github.alexdlaird.ngrok	This package contains functionality related to `ngrok`.
com.github.alexdlaird.ngrok.conf	This package contains functionality related to `java-ngrok` configuration.
com.github.alexdlaird.ngrok.installer	This package contains functionality related to downloading and installing `ngrok`.
com.github.alexdlaird.ngrok.process	This package contains functionality related to managing the `ngrok` process.
com.github.alexdlaird.ngrok.protocol	This package contains POJOs for interacting with `ngrok`.
com.github.alexdlaird.util	This package contains utility functions.

java-ngrok is a Java wrapper for ngrok that manages its own binary, making ngrok available via a convenient Java API.

ngrok is a reverse proxy tool that opens secure tunnels from public URLs to localhost, perfect for exposing local web servers, building webhook integrations, enabling SSH access, testing chatbots, demoing from your own machine, and more, and its made even more powerful with native Java integration through java-ngrok.

Useful Links

Installation

java8-ngrok is available on Maven Central.

If we want ngrok to be available from the command line, pyngrok can be installed using pip to manage that for us.

Getting Around

NgrokClient - Get started using java-ngrok, most common uses cases just require the default client behavior
JavaNgrokConfig - Configure the NgrokClient, NgrokProcess, NgrokInstaller, and other parts of java-ngrok
NgrokProcess - Advanced usage of the ngrok process

Integration Examples

java-ngrok is useful in any number of integrations, for instance to test locally without having to deploy or configure. Here are some common usage examples.

`ngrok` Version Compatibility

java-ngrok is compatible with ngrok v2 and v3, but by default it will install v3. To install v2 instead, set the version with JavaNgrokConfig.Builder.withNgrokVersion(NgrokVersion) and CreateTunnel.Builder.withNgrokVersion(NgrokVersion).

Java 8

Java 8 support is not actively maintained, this is the custom 1.4.x branch, where a compatible build of this project exists for Java 8. Use the maintained java-ngrok dependency from Maven Central and the main branch for Java 11 and above.

The Process API was introduced in Java 9, so certain convenience methods around managing the ngrok process are not available in the Java 8 build. For instance, without the Process API, java8-ngrok cannot teardown the external ngrok process for us. So even though the Java process will terminate gracefully, ngrok will not. On a Unix-like system, we can remedy this with:

Runtime.getRuntime().addShutdownHook(new Thread(() -> {
    try {
        // Java 8 doesn't properly manage its child processes, so ensure it's killed
        Runtime.getRuntime().exec("killall -9 ngrok");
    } catch (final IOException e) {
        LOGGER.error("An error occurred while shutting down ngrok", e);
    }
}));

But killall is not available on all platforms, and even on Unix-like systems this workaround is limited and has side effects.