ngrok/README.md

111 lines
5.7 KiB
Markdown
Raw Normal View History

2018-08-25 07:37:40 +00:00
[![Docker repository](https://img.shields.io/docker/automated/wernight/ngrok.svg)](https://hub.docker.com/r/wernight/ngrok/) [![Build passing](https://img.shields.io/docker/build/wernight/ngrok.svg)](https://hub.docker.com/r/wernight/ngrok/) [![Codenvy badge](http://beta.codenvy.com/factory/resources/codenvy-contribute.svg)](http://beta.codenvy.com/f?url=https://github.com/wernight/docker-ngrok 'Start development on Codenvy')
# Supported tags and respective `Dockerfile` links
* [`latest`](https://github.com/wernight/docker-ngrok/blob/master/Dockerfile) [![](https://images.microbadger.com/badges/image/wernight/ngrok.svg)](http://microbadger.com/images/wernight/ngrok "Get your own image badge on microbadger.com")
* [`armhf`](https://github.com/wernight/docker-ngrok/blob/master/Dockerfile.armhf)
2015-06-22 12:03:40 +00:00
A [Docker][docker] image for [ngrok][ngrok] v2, introspected tunnels to localhost.
It's based on the excellent work of [wizardapps/ngrok][wizardapps/ngrok] and [fnichol/ngrok][fnichol/ngrok].
2016-06-29 05:55:26 +00:00
## Features
2015-06-22 12:03:40 +00:00
2015-06-22 12:06:20 +00:00
* **Small**: Built using [busybox][busybox].
* **Simple**: Just link as `http` or `https` in most cases, see below; exposes ngrok server `4040` port.
2015-06-30 13:02:23 +00:00
* **Secure**: Runs as non-root user with a random UID `6737` (to avoid mapping to an existing UID).
2015-06-22 12:03:40 +00:00
2016-06-29 05:55:26 +00:00
## Configuration
2015-06-22 12:03:40 +00:00
2017-05-06 13:56:35 +00:00
To see command-line options, run `docker run --rm wernight/ngrok ngrok --help`.
2015-06-22 12:03:40 +00:00
2016-06-29 05:55:26 +00:00
## Usage
2015-06-30 13:02:23 +00:00
2015-07-07 13:08:44 +00:00
Supposing you've an Apache or Nginx Docker container named `web_service_container` listening on port 80:
2016-10-16 15:22:40 +00:00
$ docker run --rm -it --link web_service_container wernight/ngrok ngrok http web_service_container:80
2015-06-30 13:02:23 +00:00
2016-06-29 05:55:26 +00:00
2016-07-08 07:33:56 +00:00
### Environment variables
*Please consider using directly the command-line arguments of Ngrok.*
2016-07-08 09:35:19 +00:00
If you use the default `CMD` (i.e. don't specify the ngrok command-line but only `wernight/ngrok`),
then you can use instead envrionment variables magic below.
2016-07-08 07:33:56 +00:00
You simply have to link the Ngrok container to the application under the `app` or `http` or `https` aliases, and all of the configuration will be done for you by default.
Additionally, you can specify one of several environment variable (via `-e`) to configure your Ngrok tunnel:
* `NGROK_AUTH` - Authentication key for your Ngrok account. This is needed for custom subdomains, custom domains, and HTTP authentication.
* `NGROK_SUBDOMAIN` - Name of the custom subdomain to use for your tunnel. You must also provide the authentication token.
2017-03-16 23:52:33 +00:00
* `NGROK_HOSTNAME` - Paying Ngrok customers can specify a custom domain. Only one subdomain or domain can be specified, with the domain taking priority.
* `NGROK_REMOTE_ADDR` - Name of the reserved TCP address to use for a TCP tunnel. You must also provide the authentication token.
2016-07-08 07:33:56 +00:00
* `NGROK_USERNAME` - Username to use for HTTP authentication on the tunnel. You must also specify an authentication token.
* `NGROK_PASSWORD` - Password to use for HTTP authentication on the tunnel. You must also specify an authentication token.
* `NGROK_PROTOCOL` - Can either be `HTTP` or `TCP`, and it defaults to `HTTP` if not specified. If set to `TCP`, Ngrok will allocate a port instead of a subdomain and proxy TCP requests directly to your application.
* `NGROK_PORT` - Port to expose (defaults to `80` for `HTTP` protocol). If the server is non-local, the hostname can also be specified, e.g. `192.168.0.102:80`.
* `NGROK_REGION` - Location of the ngrok tunnel server; can be `us` (United States, default), `eu` (Europe), `ap` (Asia/Pacific) or `au` (Australia)
2019-04-02 11:19:37 +00:00
* `NGROK_LOOK_DOMAIN` - This is the domain name referred to by ngrok. (default: localhost).
* `NGROK_BINDTLS` - Toggle tunneling only HTTP or HTTPS traffic. When `true`, Ngrok only opens the HTTPS endpoint. When `false`, Ngrok only opens the HTTP endpoint
2016-07-08 07:33:56 +00:00
#### Full example
2015-06-22 12:03:40 +00:00
1. We'll set up a simple example HTTP server in a docker container named `www`:
$ docker run -v /usr/share/nginx/html --name www_data busybox true
$ docker run --rm --volumes-from www_data busybox /bin/sh -c 'echo "<h1>Yo</h1>" > /usr/share/nginx/html/index.html'
$ docker run -d -p 80 --volumes-from www_data --name www nginx
$ curl $(docker port www 80)
<h1>Yo</h1>
2. Now we'll link that HTTP server into an ngrok container to expose it on the internet:
$ docker run -d -p 4040 --link www:http --name www_ngrok wernight/ngrok
3. You can now access the [API][ngrok-api] to find the assigned domain:
$ curl $(docker port www_ngrok 4040)/api/tunnels
or access the web UI to see requests and responses:
$ xdg-open http://$(docker port www_ngrok 4040)
2016-06-29 05:55:26 +00:00
### Helper
For common cases you may want to create an alias in your `~/.profile` (or `~/.bashrc`, `~/.zshrc`, or equivalent):
function docker-ngrok() {
docker run --rm -it --link "$1":http wernight/ngrok ngrok http http:80
}
# For ZSH with Oh-My-Zsh! and 'docker' plugin enabled, you can also enable auto-completion:
#compdef __docker_containers docker-ngrok
Then to run the simple example just do `docker-ngrok web_service_container`.
For non dockerized http targets consider this helper function:
function expose-ngrok() {
docker run --rm --net=host -e NGROK_PORT="$1" wernight/ngrok
}
and then visit [localhost:4040](http://localhost:4040) for receiving the links.
2015-06-22 12:03:40 +00:00
2016-06-29 05:55:26 +00:00
## Feedbacks
2015-06-22 12:03:40 +00:00
2015-06-22 12:06:20 +00:00
Report issues/questions/feature requests on [GitHub Issues][issues].
2015-06-22 12:03:40 +00:00
Pull requests are very welcome!
[issues]: https://github.com/wernight/docker-ngrok/issues
[docker]: https://www.docker.io/
[ngrok]: https://ngrok.com/
[ngrok-api]: https://ngrok.com/docs#client-api
[busybox]: https://registry.hub.docker.com/_/busybox
[wizardapps/ngrok]: https://registry.hub.docker.com/u/wizardapps/ngrok/
[fnichol/ngrok]: https://registry.hub.docker.com/u/fnichol/ngrok/