/ngrok-spring-boot-starter

🚀 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 🧙‍♂️

Primary LanguageJavaMIT LicenseMIT

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. For simply usage any account is not needed. 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/.ngrok2. 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.6.0</version>
</dependency>
  • or gradle:
compile('io.github.kilmajster:ngrok-spring-boot-starter:0.6.0')

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/.ngrok2) and then executed on application startup, so final command executed in background as child process, should look like:

/home/user/.ngrok2/ngrok http 8080

if you are using different server port, it will be picked up automatically from server.port property.

⚙️ 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/.ngrok2/ngrok http -config /home/user/custom-ngrok-config.yml 8080
# or for multiple configs, could be something like this:
/home/user/.ngrok2/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/.ngrok2/ngrok http 8000

# or some more specific
ngrok.command=http -region=us -hostname=dev.example.com 8000
# should be = /home/user/.ngrok2/ngrok http -region=us -hostname=dev.example.com 8000
Optional properties & descriptions
# 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\.ngrok2
#  - for unix systems ~/.ngrok2
# 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

# if for some reason Ngrok binary file address has changed you can override it 
# by property corresponding to your OS
ngrok.binary.windows32=https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-windows-386.zip
ngrok.binary.linux32=https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-linux-386.zip
ngrok.binary.osx32=https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-darwin-386.zip

ngrok.binary.windows=https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-windows-amd64.zip
ngrok.binary.linux=https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-linux-amd64.zip
ngrok.binary.osx=https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-darwin-amd64.zip

# 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