Argo Tunnels to easily and securely expose your local services to the outside world.Hera automates the creation of
Hera lets you instantly access services outside of your local network with a custom domain using tunnels and is a more secure alternative than using port forwarding or dynamic DNS.
Hera monitors the state of your configured services to instantly start a tunnel when the container starts. Tunnel processes are also monitored to ensure persistent connections and to restart them in the event of sudden disconnects or shutdowns. Tunnels are automatically restarted when their containers are restarted, or gracefully shutdown if their containers are stopped.
- How Hera Works
- Getting Started
- Running Hera
- Continuously monitors the state of your services for automated tunnel creation.
- Revives tunnels on running containers when Hera is restarted.
- Uses the s6 process supervisor to ensure active tunnel processes are kept alive.
- Low memory footprint and high performance – services can be accessed through a tunnel within seconds.
- Requires a minimal amount of configuration so you can get up and running quickly.
- Supports multiple Cloudflare domains.
How Hera Works
Hera attaches to the Docker daemon to watch for changes in state of your configured containers. When a new container is started, Hera checks that it has the proper configuration as well as making sure the container can receive connections. If it passes the configuration checks, Hera spawns a new process to create a persistent tunnel connection.
In the event that a container with an active tunnel has been stopped, Hera gracefully shuts down the tunnel process.
- Installation of Docker with a client API version of 1.22 or later
- An active domain in Cloudflare with the Argo Tunnel service enabled
- A valid Cloudflare certificate (see Obtain a Certificate)
Obtain a Certificate
Hera needs a Cloudflare certificate so it can manage tunnels on your behalf.
- Download a new certificate by visiting https://www.cloudflare.com/a/warp
- Rename the certificate to match your domain, ending in
.pem. For example, a certificate for
mysite.comshould be named
- Move the certificate to a directory that can be mounted as a volume (see Required Volumes).
Hera will look for certificates with names matching your tunnels' hostnames and allows the use of multiple certificates. For more info, see Using Multiple Domains.
Create a Network
Hera must be able to connect to your containers and resolve their hostnames before it can create a tunnel. This allows Hera to supply a valid address to Cloudflare during the tunnel creation process.
It is recommended to create a dedicated network for Hera and attach your desired containers to the new network.
For example, to create a network named
docker network create hera
Hera can be started with the following command:
docker run \ --name=hera \ --network=hera \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /path/to/certs:/certs \ aschzero/hera:latest
/var/run/docker.sock– Attaching the Docker daemon as a volume allows Hera to monitor container events.
/path/to/certs– The directory of your Cloudflare certificates.
You can optionally mount a volume to
/var/log/hera to persist the logs on your host machine:
docker run \ --name=hera \ --network=hera \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /path/to/certs:/certs \ -v /path/to/logs:/var/log/hera \ aschzero/hera:latest
Hera utilizes labels for configuration as a way to let you be explicit about which containers you want enabled. There are only two labels that need to be defined:
hera.hostname- The hostname is the address you'll use to request the service outside of your home network. It must be the same as the domain you used to configure your certificate and can either be a root domain or subdomain (e.g.:
hera.port- The port your service is running on inside the container.
hera.port label value needs to be the internal port within the container.
Here's an example of a container configured for Hera with the
docker run command:
docker run \ --network=hera \ --label hera.hostname=mysite.com \ --label hera.port=80 \ nginx
That's it! After the tunnel propagates, you would be able to see the default nginx welcome page when requesting
Viewing the logs would output something similar to below:
$ docker logs -f hera [INFO] Hera container found, connecting to 5aa5a300dd0e... [INFO] Registering tunnel mysite.com time="2018-08-11T08:38:40Z" level=info msg="Applied configuration from /var/run/s6/services/mysite.com/config.yml" time="2018-08-11T08:38:40Z" level=info msg="Proxying tunnel requests to http://172.18.0.3:80" time="2018-08-11T08:38:40Z" level=info msg="Starting metrics server" addr="127.0.0.1:40521" time="2018-08-11T08:38:41Z" level=info msg="Connected to SEA" time="2018-08-11T08:38:41Z" level=info msg="Route propagating, it may take up to 1 minute for your new route to become functional" ...
Stopping a container with an active tunnel will trigger it to shut down:
$ docker stop nginx $ docker logs -f hera [INFO] Stopping tunnel mysite.com time="2018-08-11T09:00:53Z" level=info msg="Initiating graceful shutdown..." time="2018-08-11T09:00:53Z" level=info msg="Quitting..." time="2018-08-11T09:00:53Z" level=info msg="Metrics server stopped"
Using Multiple Domains
You can use multiple domains as long as there are certificates for each domain with names matching the base hostname of the tunnel. Names are matched according to the pattern
*.domain.tld and must be placed in the same directory.
For example, tunnels for
blog.mysite.com will use the certificate named
If a certificate with a matching domain cannot be found, it will look for
cert.pem in the same directory as a fallback.
An example of a tunnel for Kibana pointing to
docker run \ --name=kibana \ --network=hera \ --label hera.hostname=kibana.mysite.com \ --label hera.port=5601 \ -p 5000:5601 \ docker.elastic.co/kibana/kibana:6.2.4
version: '3' services: hera: image: aschzero/hera:latest volumes: - /var/run/docker.sock:/var/run/docker.sock - /path/to/certs:/certs networks: - hera nginx: image: nginx:latest networks: - hera labels: hera.hostname: mysite.com hera.port: 80 networks: hera: