{"id":15616410,"url":"https://github.com/texpert/ngrok-wrapper","last_synced_at":"2026-03-06T08:34:16.462Z","repository":{"id":43415063,"uuid":"445829833","full_name":"texpert/ngrok-wrapper","owner":"texpert","description":"Ruby wrapper for ngrok v2.x or v3.x","archived":false,"fork":false,"pushed_at":"2024-08-25T14:38:22.000Z","size":82,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T07:51:11.690Z","etag":null,"topics":["ngrok","ruby","webhooks"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/texpert.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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":"2022-01-08T13:40:14.000Z","updated_at":"2024-10-17T22:04:56.000Z","dependencies_parsed_at":"2024-10-22T00:40:01.905Z","dependency_job_id":null,"html_url":"https://github.com/texpert/ngrok-wrapper","commit_stats":{"total_commits":39,"total_committers":1,"mean_commits":39.0,"dds":0.0,"last_synced_commit":"deff05d2e272cd3f2bd031b8121b4c367a5a0728"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/texpert%2Fngrok-wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/texpert%2Fngrok-wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/texpert%2Fngrok-wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/texpert%2Fngrok-wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/texpert","download_url":"https://codeload.github.com/texpert/ngrok-wrapper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248945848,"owners_count":21187394,"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":["ngrok","ruby","webhooks"],"created_at":"2024-10-03T07:08:06.180Z","updated_at":"2026-03-06T08:34:16.381Z","avatar_url":"https://github.com/texpert.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ngrok::Wrapper\n\nNgrok-wrapper gem is a ruby wrapper for ngrok v2.x or v3.x.\n\n[![Maintainability](https://api.codeclimate.com/v1/badges/d978e217a8219326e325/maintainability)](https://codeclimate.com/github/texpert/ngrok-wrapper/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/d978e217a8219326e325/test_coverage)](https://codeclimate.com/github/texpert/ngrok-wrapper/test_coverage)\n\n## History\n\nNgrok-wrapper is renamed from my fork of the initial awesome [Ngrok-tunnel](https://github.com/bogdanovich/ngrok-tunnel) gem by [Anton Bogdanovich](https://github.com/bogdanovich)\n\nI was dealing with debugging work on some webhooks at my current project. Using Ngrok on a free plan, I quickly got tired of Ngrok generating a new endpoint URL every time on restarting the process. \n\nThere was a pull request [Add support for leaving an ngrok process open and reusing an existing ngrok process \ninstead of starting a new one on every process](https://github.com/bogdanovich/ngrok-tunnel/pull/11), but it wasn't \nquite working. \n\nSo, I have created [a working one](https://github.com/bogdanovich/ngrok-tunnel/pull/20), but neither \nof these PRs got any reaction from the author.\n\nSo, excuse me, [Anton Bogdanovich](https://github.com/bogdanovich), but I've decided to craft another gem, based on your awesome work, thank you!\n\n## Installation\n\n**Pre-requisites:** You must have `ngrok` v2+ or v3+ installed available in your `PATH`.\n\n**Upgrade Note:** Do not forget to run `ngrok config upgrade` after upgrading `ngrok` from v2.x to v3.x \n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'ngrok-wrapper'\n```\n\nAnd then execute:\n\n    $ bundle install\n\nOr install it yourself as:\n\n    $ gem install ngrok-wrapper\n\n## Usage\n\n```ruby\nrequire 'ngrok/wrapper'\n\n# spawn ngrok (default port 3001)\nNgrok::Wrapper.start\n\n# ngrok local_port\nNgrok::Wrapper.port\n# =\u003e 3001\n\n# ngrok external url\nNgrok::Wrapper.ngrok_url\n# =\u003e \"http://aaa0e65.ngrok.io\"\n\nNgrok::Wrapper.ngrok_url_https\n# =\u003e \"https://aaa0e65.ngrok.io\"\n\nNgrok::Wrapper.running?\n# =\u003e true\n\nNgrok::Wrapper.stopped?\n# =\u003e false\n\n# ngrok process id\nNgrok::Wrapper.pid\n# =\u003e 27384\n\n# ngrok log file descriptor\nNgrok::Wrapper.log\n# =\u003e #\u003cFile:/tmp/ngrok20141022-27376-cmmiq4\u003e\n\n# kill ngrok\nNgrok::Wrapper.stop\n# =\u003e :stopped\n\n```\n\n```ruby\n# ngrok custom parameters\nNgrok::Wrapper.start(addr: 'foo.dev:80',\n                    subdomain: 'MY_SUBDOMAIN',\n                    hostname: 'MY_HOSTNAME',\n                    authtoken: 'MY_TOKEN',\n                    inspect: false,\n                    log: 'ngrok.log',\n                    config: '~/.ngrok2/ngrok.yml',\n                    persistence: true,\n                    persistence_file: '/Users/user/.ngrok2/ngrok-process.json') # optional parameter\n```\n\n- If `persistence: true` is specified, on the 1st server start, an Ngrok process will get invoked, and the attributes of this Ngrok process, like `pid`, URLs and `port` will be stored in the `persistence_file`. \n- On server stop, the Ngrok process will not be killed. \n- On the subsequent server start, Ngrok::Wrapper will read the process attributes from the `persistence_file` and will try to re-use the running Ngrok process, if it hadn't been killed.\n  - The `persistence_file` parameter is optional when invoking `Ngrok::Wrapper.start`, by default the '/Users/user/.ngrok2/ngrok-process.json' will be created and used\n  - The `authtoken` parameter is also optional, as long as the `config` parameter is specified (usually Ngrok config \n    is the `~/.ngrok2/ngrok.yml` file)\n\n### With Rails\n\n- Use ~/.ngrok2/ngrok.yml as a config file\n- Set NGROK_INSPECT=false if you want to disable the inspector web-server\n- Add this code at the end of `config/application.rb` in a Rails project\n\n```ruby\nNGROK_ENABLED = Rails.env.development? \u0026\u0026\n                  (Rails.const_defined?(:Server) || ($PROGRAM_NAME.include?('puma') \u0026\u0026 Puma.const_defined?(:Server))) \u0026\u0026\n                  ENV['NGROK_TUNNEL'] == 'true'\n```\n\n- Add the following code at the start of `config/environments/development.rb`\n\n```ruby\nif NGROK_ENABLED\n  require 'ngrok/wrapper'\n\n  options = { addr: 'https://localhost:3000', persistence: true }\n  options[:config] = ENV.fetch('NGROK_CONFIG', \"#{ENV['HOME']}/.ngrok2/ngrok.yml\")\n  options[:inspect] = ENV['NGROK_INSPECT'] if ENV['NGROK_INSPECT']\n\n  puts \"[NGROK] tunneling at #{Ngrok::Wrapper.start(options)}\"\n  puts '[NGROK] inspector web interface listening at http://127.0.0.1:4040' if ENV['NGROK_INSPECT'] == 'true'\n\n  NGROK_URL = Ngrok::Wrapper.ngrok_url_https\nend\n```\n\n- If you need SSL (`https`) webhooks, you can use the `localhost` gem and then, in `config/puma.rb`:\n\n```ruby\nif self.class.const_defined?(:NGROK_ENABLED)\n  bind 'ssl://localhost:3000'\nelse\n  port ENV.fetch('PORT', 3000)\nend\n```\n\n- And in `config/environments/development.rb`:\n\n```ruby\nif NGROK_ENABLED\n  config.force_ssl = true\n  config.hosts \u003c\u003c URI.parse(NGROK_URL).host # for Rails \u003e= 6.0.0\nend  \n\nconfig.action_mailer.default_url_options = {\n  host: NGROK_ENABLED ? NGROK_URL.delete_prefix('https://') : 'myapp.local',\n  port: 3000\n}\n```\n\n- To make the sessions bound to the Ngrok domain, in `config/initializers/session_store.rb`:\n\n```ruby\nRails.application.config.session_store :cookie_store,\n  key: \"_#{Rails.env}_my_app_secure_session_3\",\n  domain: NGROK_ENABLED ? NGROK_URL.delete_prefix('https://') : :all,\n  tld_length: 2\n```\n\n- To use the webhooks when sending to, for example, Slack API, you can define the redirect URL in controller as follows:\n\n```ruby\nredirect_uri = NGROK_ENABLED ? \"#{NGROK_URL}/slack/oauth/#{organization.id}\" : slack_oauth_url(organization.id)\n```\n\n### With Rack server\n\n- Use ~/.ngrok2/ngrok.yml as a config file.\n- Set NGROK_INSPECT=false if you want to disable the inspector web-server.\n- Add the following code to the end of a configuration file of your preferred web-server, e.g. config/puma.rb, \nconfig/unicorn.rb, or config/thin.rb\n\n```ruby\nrequire 'ngrok/wrapper'\n\noptions = { addr: 'https://localhost:3000', persistence: true }\noptions[:config] = ENV.fetch('NGROK_CONFIG', \"#{ENV['HOME']}/.ngrok2/ngrok.yml\")\noptions[:inspect] = ENV['NGROK_INSPECT'] if ENV['NGROK_INSPECT']\n\nputs \"[NGROK] tunneling at #{Ngrok::Wrapper.start(options)}\"\nputs '[NGROK] inspector web interface listening at http://127.0.0.1:4040' if ENV['NGROK_INSPECT'] == 'true'\n\nNGROK_URL = Ngrok::Wrapper.ngrok_url_https\n```\n\n## Gem Maintenance\n\n### Preparing a release\n\nMerge all the pull requests that should make it into the new release into the `main` branch, then checkout and pull the\nbranch and run the `github_changelog_generator`, specifying the new version as a `--future-release` cli parameter:\n\n```\ngit checkout main\ngit pull\n\ngithub_changelog_generator -u texpert -p ngrok-wrapper --future-release v0.1.0\n```\nAdjust the new gem version number in the `lib/ngrok/wrapper/version.rb` file.\n\nThen add the changes to `git`, commit and push the `Preparing the new release` commit directly into the `main` branch:\n\n```\ngit add .\ngit commit -m 'Preparing the new v0.1.0 release'\ngit push\n```\n\n### RubyGems credentials\n\nEnsure you have the RubyGems credentials located in the `~/.gem/credentials` file.\n\n### Adding a gem owner\n\n```\ngem owner ngrok-wrapper -a branzeanu.aurel@gmail.com\n```\n\n### Building a new gem version\n\nCheck if the new gem version number in the `lib/ngrok/wrapper/version.rb` file has been specified. \nIt is used when building the gem by the following command:\n\n```\ngem build ngrok-wrapper.gemspec\n```\n\nAssuming the version was set to `0.1.0`,\na `ngrok-wrapper-0.1.0.gem` binary file will be generated at the root of the app (repo).\n\n- The binary file shouldn't be added into the `git` tree, it will be pushed into the RubyGems and to the GitHub releases\n\n### Pushing a new gem release to RubyGems\n\n```\ngem push ngrok-wrapper-0.1.0.gem # don't forget to specify the correct version number\n```\n\n### Crafting the new release on GitHub\n\nOn the [Releases page](https://github.com/texpert/ngrok-wrapper/releases) push the `Draft a new release` button.\n\nThe new release editing page opens, on which the following actions could be taken:\n\n- Choose the repo branch (default is `main`)\n- Insert a tag version (usually, the tag should correspond to the gem's new version, v0.1.0, for example)\n  - the tag will be created by GitHub on the last commit into the chosen branch\n- Fill the release Title and Description\n- Attach the binary file with the generated gem version\n- If the release is not yet ready for production, mark the `This is a pre-release` checkbox\n- Press either the `Publish release`, or the `Save draft button` if you want to publish it later\n  - After publishing the release, the the binary gem file will be available on GitHub and could be removed locally\n\n\n## Contributing\n\n1. Fork it ( https://github.com/texpert/ngrok-wrapper/fork )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftexpert%2Fngrok-wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftexpert%2Fngrok-wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftexpert%2Fngrok-wrapper/lists"}