Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kilmajster/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 🧙♂️
https://github.com/kilmajster/ngrok-spring-boot-starter
development-tools docker http-tunnel java linux macos ngrok ngrok-tunnel port-forwarding spring spring-boot springboot springboot-starter testing-tools tool tunneling windows
Last synced: 13 days ago
JSON representation
🚀 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 🧙♂️
- Host: GitHub
- URL: https://github.com/kilmajster/ngrok-spring-boot-starter
- Owner: kilmajster
- License: mit
- Created: 2018-07-18T08:44:46.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-10-14T11:22:04.000Z (29 days ago)
- Last Synced: 2024-10-20T07:59:23.120Z (23 days ago)
- Topics: development-tools, docker, http-tunnel, java, linux, macos, ngrok, ngrok-tunnel, port-forwarding, spring, spring-boot, springboot, springboot-starter, testing-tools, tool, tunneling, windows
- Language: Java
- Homepage:
- Size: 9.63 MB
- Stars: 129
- Watchers: 3
- Forks: 17
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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](https://ngrok.com/).
## 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 available [here](https://github.com/kilmajster/demo).
## Dependency
- maven:
```xml
io.github.kilmajster
ngrok-spring-boot-starter
0.9.2
```
- or gradle:
```groovy
compile('io.github.kilmajster:ngrok-spring-boot-starter:0.9.2')
````
## Configuration
### 🚀 Minimal configuration
#### `ngrok.enabled`
To enable this starter, add following property:
```properties
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:
```properties
ngrok.authToken=
```
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:
> ```bash
> /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:
```properties
ngrok.config=/home/user/custom-ngrok-config.yml
```
or if you've got multiple configuration files, use semicolon (`;`) as separator, like below:
```properties
ngrok.config=/home/user/custom-ngrok-config.yml;/home/user/another-ngrok-config.yml
```
then generated ngrok command, should look like this:
```bash
/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:
```properties
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:
```properties
# 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
```properties
# 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