Skip to content

πŸš€ Spring Boot tunneling with Ngrok made easy! No matter if you are using Windows, Mac OS X, Linux or even Docker - ngrok binary will be chosen automatically πŸ€– so you don't need to care about environment changing etc. auto-configuration magic πŸ§™β€β™‚οΈ

License

Notifications You must be signed in to change notification settings

kilmajster/ngrok-spring-boot-starter

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Ngrok Spring Boot Starter
CI status badge Github last commit badge Maven Central MIT license badge
CI on Windows CI on Ubuntu CI on MacOS

ngrok overview

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 πŸ‘‡

demo gif

Code of demo application available here.

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

About

πŸš€ Spring Boot tunneling with Ngrok made easy! No matter if you are using Windows, Mac OS X, Linux or even Docker - ngrok binary will be chosen automatically πŸ€– so you don't need to care about environment changing etc. auto-configuration magic πŸ§™β€β™‚οΈ

Topics

Resources

License

Stars

Watchers

Forks

Languages