{"id":15067815,"url":"https://github.com/kilmajster/ngrok-spring-boot-starter","last_synced_at":"2026-02-17T21:04:25.071Z","repository":{"id":42514236,"uuid":"141406934","full_name":"kilmajster/ngrok-spring-boot-starter","owner":"kilmajster","description":"🚀 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 🧙‍♂️","archived":false,"fork":false,"pushed_at":"2025-03-10T13:35:04.000Z","size":10100,"stargazers_count":134,"open_issues_count":5,"forks_count":17,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T13:04:45.604Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kilmajster.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-18T08:44:46.000Z","updated_at":"2025-03-15T10:25:07.000Z","dependencies_parsed_at":"2024-02-01T17:07:18.287Z","dependency_job_id":"9549d815-51e4-4713-aa51-f550d2c7c2a4","html_url":"https://github.com/kilmajster/ngrok-spring-boot-starter","commit_stats":{"total_commits":362,"total_committers":8,"mean_commits":45.25,"dds":0.5718232044198894,"last_synced_commit":"667f93288af8de68fe0e9783dba42421fbde3045"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilmajster%2Fngrok-spring-boot-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilmajster%2Fngrok-spring-boot-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilmajster%2Fngrok-spring-boot-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilmajster%2Fngrok-spring-boot-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kilmajster","download_url":"https://codeload.github.com/kilmajster/ngrok-spring-boot-starter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247184941,"owners_count":20897860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["development-tools","docker","http-tunnel","java","linux","macos","ngrok","ngrok-tunnel","port-forwarding","spring","spring-boot","springboot","springboot-starter","testing-tools","tool","tunneling","windows"],"created_at":"2024-09-25T01:27:32.322Z","updated_at":"2026-02-17T21:04:25.064Z","avatar_url":"https://github.com/kilmajster.png","language":"Java","funding_links":[],"categories":["网络编程"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n    Ngrok Spring Boot Starter\n    \u003cbr\u003e\n    \u003ca href=\"https://github.com/kilmajster/ngrok-spring-boot-starter/actions\"\u003e\n        \u003cimg align=\"center\" src=\"https://github.com/kilmajster/ngrok-spring-boot-starter/workflows/main/badge.svg\" alt=\"CI status badge\"\u003e\n    \u003c/a\u003e\n    \u003cimg align=\"center\" src=\"https://img.shields.io/github/last-commit/kilmajster/ngrok-spring-boot-starter.svg\" alt=\"Github last commit badge\"\u003e\n    \u003ca href=\"https://mvnrepository.com/artifact/io.github.kilmajster/ngrok-spring-boot-starter\"\u003e\n        \u003cimg align=\"center\" src=\"https://img.shields.io/maven-central/v/io.github.kilmajster/ngrok-spring-boot-starter?color=blue\" alt=\"Maven Central\" \u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/kilmajster/ngrok-spring-boot-starter/blob/main/LICENSE\"\u003e\n        \u003cimg align=\"center\" src=\"https://img.shields.io/github/license/kilmajster/ngrok-spring-boot-starter?color=blue\" alt=\"MIT license badge\"\u003e\n    \u003c/a\u003e\n    \u003cbr\u003e\n    \u003ca href=\"https://github.com/kilmajster/ngrok-spring-boot-starter/actions/workflows/automation-test-windows.yml\"\u003e\n        \u003cimg align=\"center\" src=\"https://github.com/kilmajster/ngrok-spring-boot-starter/actions/workflows/automation-test-windows.yml/badge.svg\" alt=\"CI on Windows\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/kilmajster/ngrok-spring-boot-starter/actions/workflows/automation-test-ubuntu.yml\"\u003e\n        \u003cimg align=\"center\" src=\"https://github.com/kilmajster/ngrok-spring-boot-starter/actions/workflows/automation-test-ubuntu.yml/badge.svg\" alt=\"CI on Ubuntu\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/kilmajster/ngrok-spring-boot-starter/actions/workflows/automation-test-macos.yml\"\u003e\n        \u003cimg align=\"center\" src=\"https://github.com/kilmajster/ngrok-spring-boot-starter/actions/workflows/automation-test-macos.yml/badge.svg\" alt=\"CI on MacOS\"\u003e\n    \u003c/a\u003e\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/kilmajster/ngrok-spring-boot-starter/blob/main/.github/overview.png\" alt=\"ngrok overview\"\u003e\n\u003c/p\u003e\n\n\u003e What is Ngrok?\n\u003e\n\u003e *tldr;* Ngrok can create a http tunnel and give you a public URL with redirection to\n\u003e specified port on your local machine, which in our case will be a standard springs `http://localhost:8080`\n\u003e or whatever you set as `server.port` springs property. Tunnels created with free version will be available for 2 hours, \n\u003e so it is a great tool for development and testing purposes!\n\u003e For more details you can check out their [site](https://ngrok.com/).\n\n## What this starter gives to you?\nThis starter will automatically download Ngrok binary corresponding to your \noperating system (Windows, Linux, OSX or even Docker) and then cache it into `home_directory/.ngrok3`. \nIf Ngrok binary is already present in the PATH, download will be skipped.\nThen every time you will run your Spring Boot application, Ngrok will \nautomatically build http tunnel pointing to your springs web server, and you will get pretty logs \nwith the remote links, just like it's done below 👇\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/kilmajster/ngrok-spring-boot-starter/blob/main/.github/demo.gif\" alt=\"demo gif\"\u003e\n\u003c/p\u003e\n\nCode of demo application is available \n[here](https://github.com/kilmajster/ngrok-spring-boot-starter/tree/main/.github/test-app-sb-2x) for spring-boot v2 and \n[here](https://github.com/kilmajster/ngrok-spring-boot-starter/tree/main/.github/test-app-sb-3x) for v3.\n\n## Dependency\n- maven:\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.github.kilmajster\u003c/groupId\u003e\n  \u003cartifactId\u003engrok-spring-boot-starter\u003c/artifactId\u003e\n  \u003cversion\u003e0.9.2\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n- or gradle:\n```groovy\ncompile('io.github.kilmajster:ngrok-spring-boot-starter:0.9.2')\n````\n\n##  Configuration\n### 🚀 Minimal configuration\n#### `ngrok.enabled`\nTo enable this starter, add following property:\n```properties\nngrok.enabled=true\n```\n#### `ngrok.authToken`\nNgrok requires `authToken` to be defined, to obtain one visit https://dashboard.ngrok.com/get-started/your-authtoken and then add it like below:\n```properties\nngrok.authToken=\u003cYOUR PERSONAL AUTH TOKEN\u003e\n```\nIf you got already configured auth token in your ngrok config file there is no need to define this property.\n\n✅ **All done, configuration is ready!** \n\n\u003e What will happen now?\n\u003e\n\u003e If you are using default spring configuration of server port, which is `8080`, then ngrok will \n\u003e be downloaded, extracted and cached into user default directory(eg. `/home/user/.ngrok3`) and then executed\n\u003e on application startup, so final command executed in background as child process, should look like:\n\u003e ```bash\n\u003e /home/user/.ngrok3/ngrok http 8080\n\u003e ```\n\u003e if you are using different server port, it will be picked up automatically from `server.port` property.\n\u003e If ngrok binary is already present in path, download will be skipped \n\n### ⚙️ Advanced configuration\n#### `ngrok.config` - ngrok configuration file(s)\nIf you want to start ngrok with configuration file or files, you can use `ngrok.config` property:\n```properties\nngrok.config=/home/user/custom-ngrok-config.yml\n```\nor if you've got multiple configuration files, use semicolon (`;`) as separator, like below:\n```properties\nngrok.config=/home/user/custom-ngrok-config.yml;/home/user/another-ngrok-config.yml\n```\nthen generated ngrok command, should look like this:\n```bash\n/home/user/.ngrok3/ngrok http -config /home/user/custom-ngrok-config.yml 8080\n# or for multiple configs, could be something like this:\n/home/user/.ngrok3/ngrok http -config /home/user/custom-ngrok-config.yml -config /home/user/another-ngrok-config.yml 8080\n```\n###### configuration from Classpath\nIf you prefer to keep ngrok configuration file inside your app, just add it as resource file and prefix `ngrok.config` property\nwith `classpath:`, so for config in standard springs resources root dir `src/main/resources/ngrok.yml`, it should look like following:\n```properties\nngrok.config=classpath:ngrok.yml\n```\n\n#### `ngrok.command` - ngrok custom command attributes\nIf you want to achieve something more complex, you can use `ngrok.command` property to provide ngrok execution attributes, \nexample:\n```properties\n# to run default behavior\nngrok.command=http 8080\n# should result with command = /home/user/.ngrok3/ngrok http 8000\n\n# or some more specific\nngrok.command=http -region=us -hostname=dev.example.com 8000\n# should be = /home/user/.ngrok3/ngrok http -region=us -hostname=dev.example.com 8000\n```\n\n##### Optional properties \u0026 descriptions\n```properties\n# if you want to use ngrok v2\nngrok.legacy=true\n\n# if you want to force download ngrok binary instead of using local one even if it's present in the PATH\nngrok.useFromPath=false\n\n# if you've got already running Ngrok instance somewhere else, you can specify its host \u0026 port, whoch defaults are:\nngrok.host=http://127.0.0.1\nngrok.port=4040\n\n# if you want to use Ngrok directory location different than default, which are:\n#  - for Windows C:\\Users\\user\\.ngrok3\n#  - for unix systems ~/.ngrok3\n# use ngrok.directory property, like below:\nngrok.directory=C:\\\\Users\\\\user\\\\Desktop\\\\ngrok\n\n# if for some reason Ngrok starting takes longer than really quick, you can override time \n# of waiting for ngrok startup:\nngrok.waitForStartup.millis=3000\n\n# or just specify custom location as fallback:\nngrok.binary.custom=http://not-exist.com/custom-ngrok-platform-bsd-arm-sth.zip\n```\n\n#### Issues \u0026 contributing\nIf you've got any troubles or ideas, feel free to report an issue or create pull request with improvements 🙂.\n\n#### References\n - https://ngrok.com/\n - https://spring.io/projects/spring-boot\n - https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#using-boot-starter\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkilmajster%2Fngrok-spring-boot-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkilmajster%2Fngrok-spring-boot-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkilmajster%2Fngrok-spring-boot-starter/lists"}