Quarkus - Ngrok

This Quarkus extension integrates ngrok into Quarkus Dev Mode thus allowing users to expose their application to the public internet while they are still developing it.

The extension has absolutely no impact on the production Quarkus application

Installation

If you want to use this extension, you need to add the io.quarkiverse.ngrok:quarkus-ngrok extension first. In your pom.xml file, add:

<dependency>
    <groupId>io.quarkiverse.ngrok</groupId>
    <artifactId>quarkus-ngrok</artifactId>
</dependency>

Usage

  1. Add the extension to the application’s dependencies ./mvnw quarkus:add-extension -Dextensions="io.quarkiverse.ngrok:quarkus-ngrok"

  2. Get a ngrok auth token and configure it using ngrok or set it via quarkus.ngrok.auth-token

  3. A short while after the application has started, you should see something in the application logs like:

    ngrok is running and its web interface can be accessed at: 'http://localhost:4040'
The application can be accessed publicly over the internet using: 'https://4f59-68-81-186-238.ngrok-free.app'

  4. Use the .ngrok-free.app URL to access the running application from the public internet

Use a stable domain/url

You can get a stable url by setting quarkus.ngrok.domain to a domain you own and have configured in ngrok.

Tip: ngrok at current time of writing offer a free domain per user for free. See details at https://ngrok.com/blog-post/free-static-domains-ngrok-users.

Use ngrok custom configuration

For further customization of ngrok, assign quarkus.ngrok.tunnel-name to a named tunnel specified in your ngrok configuration file for your operating system. Quarkus will then utilize that configuration instead.

Example, set this in your application.properties:

quarkus.ngrok.tunnel-name=${quarkus.application.name}

And lets say your app is named quarkus-my-app then in your ngrok.yml file:

version: 2
tunnels:
    quarkus-my-app:
        proto: http
        addr: 8080
        bind_tls: true
        basic_auth:
            - "bob:bobpassword"
        domain: my-app.ngrok.io

Then Quarkus will launch ngrok using ngrok start quarkus-my-app and use that specific named tunnel configuration.

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.ngrok.enabled

Whether ngrok should be started when Quarkus dev-mode is launched.

Environment variable: QUARKUS_NGROK_ENABLED

boolean

true

quarkus.ngrok.directory

The directory into which to save the ngrok binary if it doesn’t exist.

Environment variable: QUARKUS_NGROK_DIRECTORY

string

${user.home}/.quarkus/ngrok

quarkus.ngrok.download-url

Specify a download URL where the ngrok distribution will be obtained from. If not set, the platform default will be used.

Environment variable: QUARKUS_NGROK_DOWNLOAD_URL

string

quarkus.ngrok.auth-token

The authentication token used to authenticate this client when it connects to the ngrok.com service.

Environment variable: QUARKUS_NGROK_AUTH_TOKEN

string

quarkus.ngrok.region

The region where the ngrok agent will connect to host its tunnels.

Environment variable: QUARKUS_NGROK_REGION

united-states, europe, asia-pacific, australia, south-america, japan, india

quarkus.ngrok.port

The port where ngrok will be serving the local web interface and API.

Environment variable: QUARKUS_NGROK_PORT

int

quarkus.ngrok.domain

The domain or hostname to use instead of the one ngrok generates. See https://ngrok.com/blog-post/free-static-domains-ngrok-users

Environment variable: QUARKUS_NGROK_DOMAIN

string

quarkus.ngrok.tunnel-name

Name of the tunnel to start from ngrok default config instead of Quarkus configuration. Useful to use extended ngrok configuration.

Environment variable: QUARKUS_NGROK_TUNNEL_NAME

string

quarkus.ngrok.api-key

API key for ngrok if you need to perform any API operations such as delete-certificate-management-policy.

Environment variable: QUARKUS_NGROK_API_KEY

string

quarkus.ngrok.delete-certificate-domain-id

Reserved domain unique identifier for revoking certificate upon startup. Example: 'rd_2hrGw0rqFLOm9pcXf4dlbdNfrus' If this value is not null the certificate will be revoked upon dev service startup.

Environment variable: QUARKUS_NGROK_DELETE_CERTIFICATE_DOMAIN_ID

string