Ngrok Spring Boot Starter

What is Ngrok?

tldr; Ngrok can create a http tunnel and give you a public URL with redirection to specified port on your local machine, which in our case will be a standard springs http://localhost:8080 or whatever you set as server.port springs property. Tunnels created with free version will be available for 2 hours, so it is a great tool for development and testing purposes! For more details you can check out their site.

What this starter gives to you?

This starter will automatically download Ngrok binary corresponding to your operating system (Windows, Linux, OSX or even Docker) and then cache it into home_directory/.ngrok3. If Ngrok binary is already present in the PATH, download will be skipped. Then every time you will run your Spring Boot application, Ngrok will automatically build http tunnel pointing to your springs web server, and you will get pretty logs with the remote links, just like it's done below 👇

Code of demo application is available here for spring-boot v2 and here for v3.

Dependency

• maven:

<dependency>
  <groupId>io.github.kilmajster</groupId>
  <artifactId>ngrok-spring-boot-starter</artifactId>
  <version>0.9.2</version>
</dependency>

• or gradle:

compile('io.github.kilmajster:ngrok-spring-boot-starter:0.9.2')

Configuration

🚀 Minimal configuration

ngrok.enabled

To enable this starter, add following property:

ngrok.enabled=true

ngrok.authToken

Ngrok requires authToken to be defined, to obtain one visit https://dashboard.ngrok.com/get-started/your-authtoken and then add it like below:

ngrok.authToken=<YOUR PERSONAL AUTH TOKEN>

If you got already configured auth token in your ngrok config file there is no need to define this property.

✅ All done, configuration is ready!

What will happen now?

If you are using default spring configuration of server port, which is 8080, then ngrok will be downloaded, extracted and cached into user default directory(eg. /home/user/.ngrok3) and then executed on application startup, so final command executed in background as child process, should look like:

/home/user/.ngrok3/ngrok http 8080

if you are using different server port, it will be picked up automatically from server.port property. If ngrok binary is already present in path, download will be skipped

⚙️ Advanced configuration

ngrok.config - ngrok configuration file(s)

If you want to start ngrok with configuration file or files, you can use ngrok.config property:

ngrok.config=/home/user/custom-ngrok-config.yml

or if you've got multiple configuration files, use semicolon (;) as separator, like below:

ngrok.config=/home/user/custom-ngrok-config.yml;/home/user/another-ngrok-config.yml

then generated ngrok command, should look like this:

/home/user/.ngrok3/ngrok http -config /home/user/custom-ngrok-config.yml 8080
# or for multiple configs, could be something like this:
/home/user/.ngrok3/ngrok http -config /home/user/custom-ngrok-config.yml -config /home/user/another-ngrok-config.yml 8080

configuration from Classpath

If you prefer to keep ngrok configuration file inside your app, just add it as resource file and prefix ngrok.config property with classpath:, so for config in standard springs resources root dir src/main/resources/ngrok.yml, it should look like following:

ngrok.config=classpath:ngrok.yml

ngrok.command - ngrok custom command attributes

If you want to achieve something more complex, you can use ngrok.command property to provide ngrok execution attributes, example:

# to run default behavior
ngrok.command=http 8080
# should result with command = /home/user/.ngrok3/ngrok http 8000

# or some more specific
ngrok.command=http -region=us -hostname=dev.example.com 8000
# should be = /home/user/.ngrok3/ngrok http -region=us -hostname=dev.example.com 8000

Optional properties & descriptions

# if you want to use ngrok v2
ngrok.legacy=true

# if you want to force download ngrok binary instead of using local one even if it's present in the PATH
ngrok.useFromPath=false

# if you've got already running Ngrok instance somewhere else, you can specify its host & port, whoch defaults are:
ngrok.host=http://127.0.0.1
ngrok.port=4040

# if you want to use Ngrok directory location different than default, which are:
#  - for Windows C:\Users\user\.ngrok3
#  - for unix systems ~/.ngrok3
# use ngrok.directory property, like below:
ngrok.directory=C:\\Users\\user\\Desktop\\ngrok

# if for some reason Ngrok starting takes longer than really quick, you can override time 
# of waiting for ngrok startup:
ngrok.waitForStartup.millis=3000

# or just specify custom location as fallback:
ngrok.binary.custom=http://not-exist.com/custom-ngrok-platform-bsd-arm-sth.zip

Issues & contributing

If you've got any troubles or ideas, feel free to report an issue or create pull request with improvements 🙂.

References

• https://ngrok.com/
• https://spring.io/projects/spring-boot
• https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#using-boot-starter