90 lines
5 KiB
Markdown
90 lines
5 KiB
Markdown
# Docker Ngrok
|
|
|
|
A Docker image for [ngrok](https://ngrok.com) service to expose a local docker environment or any other local server to the public internet over secure tunnels. The image is built using official [busybox:glibc](https://hub.docker.com/_/busybox) docker image, so no third party libraries are used, only official busybox and ngrok binary.
|
|
|
|
## Usage
|
|
|
|
### Command-line
|
|
|
|
**Example**
|
|
The example below assumes that you have running web server docker container named `dev_web_1` with exposed port `80`.
|
|
|
|
```bash
|
|
docker run --rm -it --link dev_web_1 hhftechnologies/ngrok http dev_web_1:80
|
|
```
|
|
|
|
With command line usage, ngrok session is active until it won't be terminated by `Ctrl+C` combination.
|
|
|
|
#### Command details
|
|
|
|
**Using ngrok parameters**
|
|
|
|
```bash
|
|
docker run --rm -it --link <web-container-name> [--net <default-netowrk-name>] hhftechnologies/ngrok <ngrok-parameters> <web-container-name>:<port>
|
|
```
|
|
|
|
For information about ngrok parameters, please refer to [ngrok documentation](https://ngrok.com/docs).
|
|
|
|
**Passing parameters to ngrok via env variables**
|
|
|
|
```bash
|
|
docker run --rm -it --link <web-container-name> [--net <default-netowrk-name>] --env DOMAIN=<web-container-name> --env PORT=<port> hhftechnologies/ngrok
|
|
```
|
|
|
|
Available env variables can be found below, at [environment variables](#environment-variables) section.
|
|
|
|
#### Troubleshooting
|
|
|
|
_If you are getting an error like_
|
|
|
|
```bash
|
|
docker: Error response from daemon: Cannot link to /dev_web_1, as it does not belong to the default network.
|
|
```
|
|
|
|
_You need to specify default docker network, for example_
|
|
|
|
```bash
|
|
docker run --rm -it --link dev_web_1 --net dev_default hhftechnologies/ngrok http dev_web_1:80
|
|
```
|
|
|
|
### As part of docker-compose.yml file
|
|
|
|
```yaml
|
|
ngrok:
|
|
image: hhftechnologies/ngrok:latest
|
|
ports:
|
|
- 4551:4551
|
|
links:
|
|
- web
|
|
environment:
|
|
- DOMAIN=web
|
|
- PORT=80
|
|
```
|
|
|
|
Where `web` in example above is a web server service name of this docker-compose.yml file.
|
|
|
|
If ngrok container is created as part of docker-compose.yml file, ngrok session is active while container is running. To restart or stop session, you will need to restart or stop container respectively.
|
|
Ngrok web interface available at `http://localhost:4551`.
|
|
|
|
## Environment variables
|
|
|
|
List of available environment variables to configure ngrok in command line usage or as part of docker-compose.yml file.
|
|
|
|
| Name | Values | Default | Information |
|
|
| :---------- | :------------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| PROTOCOL | http, tls, tcp | http | Ngrok tunneling protocol. |
|
|
| DOMAIN | \* | localhost | Hostname or docker container, service name which is referred to by ngrok. |
|
|
| PORT | \* | 80 | Port which is referred to by ngrok. |
|
|
| REGION | us, eu, ap, au, sa, jp, in | us | Region where the ngrok client will connect to host its tunnels. |
|
|
| HOST_HEADER | \* | | Optional, rewrite incoming HTTP requests with a modified Host header. e.g. `HOST_HEADER=localdev.test` |
|
|
| BIND_TLS | true, false | | Optional, forward only HTTP or HTTPS traffic, but not both. By default, when ngrok runs an HTTP tunnel, it opens endpoints for both HTTP and HTTPS traffic. |
|
|
| SUBDOMAIN | \* | | Optional, specifies the subdomain to use with ngrok, if unspecified ngrok with generate a unique subdomain on each start. |
|
|
| AUTH_TOKEN | \* | | Optional, token used to authorise your subdomain with ngrok. |
|
|
| DEBUG | true | | Optional, write logs to stdout. |
|
|
| PARAMS | \* | | Pass all ngrok parameters by one string. When specified, any other env variables are skipped (Except AUTH_TOKEN).|
|
|
|
|
For more information about ngrok parameters, please refer to [ngrok documentation](https://ngrok.com/docs).
|
|
|
|
## License
|
|
|
|
[MIT](../../blob/master/LICENSE)
|