Using ngrok with Docker

For detailed instructions on using ngrok with Kubernetes, check out the k8s quickstart.

ngrok provides pre-built docker images for the ngrok Agent with instructions for getting started. An example command for starting a tunnel to port 80 on the host machine looks like this.

Debian Linux
Windows or Mac

docker run --net=host -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http 80

docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http host.docker.internal:80

For MacOS and Windows, you must use the special URL host.docker.internal as described in the Docker networking documentation.This also applies to the upstream.url endpoint property in your ngrok config file. For example:

endpoints:
  - name: example
    url: https://example.ngrok.app
    upstream:
      url: http://host.docker.internal:80

Note: the Docker version of ngrok follows the same convention as the agent, for example:

docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http 80                            # secure public URL for port 80 web server
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http --url baz.ngrok.dev 8080   # port 8080 available at baz.ngrok.dev
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http foo.dev:80                    # tunnel to host:port instead of localhost
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http https://localhost:5001        # expose a local https server running on port 5001
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest tcp 22                             # tunnel arbitrary TCP traffic to port 22
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest tls --url foo.com 443           # TLS traffic for foo.com to port 443
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest start foo bar baz                  # start tunnels from the configuration file

Basic usage

The ngrok docker image wraps the ngrok agent executable. Read the documentation for the ngrok agent CLI docs for all commands.

Run an ngrok Agent pointed at localhost:80

docker run -it -e NGROK_AUTHTOKEN=your_token ngrok/ngrok http host.docker.internal:80

Choose a URL

If you don’t choose a URL, ngrok will assign one for you.

docker run -it -e NGROK_AUTHTOKEN=your_token ngrok/ngrok http host.docker.internal:80 --url https://your-url-here.ngrok.app

Add a Traffic Policy

Traffic Policy is a configuration language that offers you the flexibility to filter, match, manage, and orchestrate traffic to your endpoints.

docker run -it -v $(pwd)/traffic-policy.yml:/etc/traffic-policy.yml ngrok/ngrok:alpine http host.docker.internal:80 --traffic-policy-file /etc/traffic-policy.yml

`traffic-policy.yml`

on_http_request:
  - actions:
      - type: basic-auth
        config:
          credentials:
            - user:password123

Run in the background

docker run -d --restart unless-stopped -e NGROK_AUTHTOKEN=your_token --name ngrok-agent ngrok/ngrok http host.docker.internal:80

Use a configuration file

Run the ngrok agent with the config file ./ngrok.yml from the host machine:

docker run -it -v $(pwd)/ngrok.yml:/etc/ngrok.yml -e NGROK_CONFIG=/etc/ngrok.yml ngrok/ngrok:alpine http host.docker.internal:80

Pull the ngrok container image

docker pull ngrok/ngrok

Traffic Inspection

Traffic Inspector

Use Traffic Inspector on your ngrok dashboard

Local web inspection on localhost:4040 (Legacy)

The agent serves this web interface on port 4040 so you’ll need to publish it as well with -p 4040:4040

docker run -it -p 4040:4040 ngrok/ngrok http host.docker.internal:80

If you are unable to view the web inspection interface typically available at http://localhost:4040, you may need to map your host port 4040 to port 4040 on the container, for example:

docker run -p 4040:4040 -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http host.docker.internal:80

Observing Agent Traffic

CLI

CLI Configuration File

Reference

Guides

Agent TLS Termination

Basic usage

Run an ngrok Agent pointed at localhost:80

Choose a URL

Add a Traffic Policy

`traffic-policy.yml`

Run in the background

Use a configuration file

Pull the ngrok container image

Traffic Inspection

Traffic Inspector

Local web inspection on localhost:4040 (Legacy)

​Basic usage

​Run an ngrok Agent pointed at localhost:80

​Choose a URL

​Add a Traffic Policy

traffic-policy.yml

​Run in the background

​Use a configuration file

​Pull the ngrok container image

​Traffic Inspection

​Traffic Inspector

​Local web inspection on localhost:4040 (Legacy)

Basic usage

Run an ngrok Agent pointed at localhost:80

Choose a URL

Add a Traffic Policy

`traffic-policy.yml`

Run in the background

Use a configuration file

Pull the ngrok container image

Traffic Inspection

Traffic Inspector

Local web inspection on localhost:4040 (Legacy)