portray or describe (something) precisely.
This repo contains some repeatable examples using ngrok to create secure tunnels to expose local endpoints on the internet
Explore the docs »
Report Bug
·
Request Feature
- About The Project
- Built With
- Getting Started
- Usage Examples
- Roadmap
- Contributing
- License
- Acknowledgements
This repo was created to experiment with ngrok to better understand it's functionality and use cases. It is not meant to be a replica of the official documentation 😆.
This repo follows the principle of minimal manual setup of the local development environment. A task target has been provided for simplicity task init, the taskfile.yaml file can be inspected for more details.
To use ngrok you must have a valid authentication token. If you need to create an account get an auth token you should follow the simple sign up steps at ngrok.com/signup.
Once you have a token it must be added to .env using NGROK_AUTH_TOKEN=[YOUR TOKEN].
To use the following examples you must first start the simple non-production web server using task example:web command, this will start serving a "hello, world!" website on http://localhost:8000.
For the domain & oauth examples you will need to register custom domain on the ngrok edge platform follow the instructions at ngrok domains, as part of this it will be necessary to to setup DNS entries in your domain registrar.
Once this is running you can use the following commands to start an ngrok tunnel.
| Example | Task | Description |
|---|---|---|
| basic | task example:basic |
This example exposes the website running at localhost:8000 on a non-stable grok generated sub-domain. |
| domain | task example:domain |
This example exposes the website using a custom pre-owned domain. See below for more details . |
| oauth | task example:oauth |
This example exposes the website on a custom domain and secures authentication using an OAuth provider (e.g. Google) |
Once you have finished with each example you can stop the web server using task example:kill to stop the web server.
This example shows ngrok being used to run a file server.
| Example | Task | Description |
|---|---|---|
| File | task example:files |
This example serves the files that are located in examples/files. |
ngrok can also be run as a background service, this example uses a configuration file ngrok.yaml and enables the configured ngrok tunnels. For simplicity this example mirrors the tunnel created using task example:oauth. This is a great way to run multiple tunnels easily.
The ngrok auth token must be written to the config file. To reduce the risk committing secret with git the ngrok.yaml file is copied to ngrok.processed.yaml and the token added to ngrok.processed.yaml, while ngrok.processed.yaml is excluded via .gitignore.
# starts the configured tunnels
task example:service:start
# stops the configured tunnels
task example:service:stopAlso note that the above commands will require admin privileges and therefore it's highly likely that you will need to enter your password to complete these tasks.
See the open issues for a list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
If you would like to contribute to any delineate.io OSS projects please read:
Distributed under the MIT License. See LICENSE for more information.