{"id":13548694,"url":"https://github.com/aschzero/hera","last_synced_at":"2025-07-13T20:33:27.709Z","repository":{"id":46001730,"uuid":"133128002","full_name":"aschzero/hera","owner":"aschzero","description":"Automated secure tunnels for containers using Cloudflare Argo","archived":false,"fork":false,"pushed_at":"2021-11-25T15:08:21.000Z","size":91,"stargazers_count":127,"open_issues_count":16,"forks_count":19,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-07T18:13:14.020Z","etag":null,"topics":["argo","docker","golang","tunnel"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aschzero.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-12T08:29:32.000Z","updated_at":"2025-04-04T12:38:22.000Z","dependencies_parsed_at":"2022-08-14T09:30:23.941Z","dependency_job_id":null,"html_url":"https://github.com/aschzero/hera","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/aschzero/hera","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aschzero%2Fhera","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aschzero%2Fhera/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aschzero%2Fhera/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aschzero%2Fhera/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aschzero","download_url":"https://codeload.github.com/aschzero/hera/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aschzero%2Fhera/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265200067,"owners_count":23726768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["argo","docker","golang","tunnel"],"created_at":"2024-08-01T12:01:13.308Z","updated_at":"2025-07-13T20:33:27.405Z","avatar_url":"https://github.com/aschzero.png","language":"Go","funding_links":[],"categories":["Go","\u003ca id=\"01e6651181d405ecdcd92a452989e7e0\"\u003e\u003c/a\u003e工具"],"sub_categories":["\u003ca id=\"9d6789f22a280f5bb6491d1353b02384\"\u003e\u003c/a\u003e隧道\u0026\u0026穿透"],"readme":"\u003cimg alt=\"Hera\" src=\"https://s3-us-west-2.amazonaws.com/aschzero-hera/hera.png\" width=\"500px\"\u003e\n\n### Hera automates the creation of [Argo Tunnels](https://www.cloudflare.com/products/argo-tunnel/) to easily and securely expose your local services to the outside world.\n\nHera 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.\n\nHera 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.\n\n[![Build Status](https://semaphoreci.com/api/v1/aschzero/hera/branches/master/badge.svg)](https://semaphoreci.com/aschzero/hera)\n[![](https://images.microbadger.com/badges/version/aschzero/hera.svg)](https://hub.docker.com/r/aschzero/hera)\n\n----\n\n* [Features](#features)\n* [How Hera Works](#how-hera-works)\n* [Getting Started](#getting-started)\n  * [Prerequisites](#prerequisites)\n  * [Obtain a Certificate](#obtain-a-certificate)\n  * [Create a Network](#create-a-network)\n* [Running Hera](#running-hera)\n    * [Required Volumes](#required-volumes)\n    * [Persisting Logs](#persisting-logs)\n  * [Tunnel Configuration](#tunnel-configuration)\n  * [Using Multiple Domains](#using-multiple-domains)\n* [Examples](#examples)\n  * [Subdomains](#subdomains)\n  * [Docker Compose](#docker-compose)\n* [Contributing](#contributing)\n\n----\n\n# Features\n* Continuously monitors the state of your services for automated tunnel creation.\n* Revives tunnels on running containers when Hera is restarted.\n* Uses the s6 process supervisor to ensure active tunnel processes are kept alive.\n* Low memory footprint and high performance – services can be accessed through a tunnel within seconds.\n* Requires a minimal amount of configuration so you can get up and running quickly.\n* Supports multiple Cloudflare domains.\n\n# How Hera Works\nHera 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.\n\nIn the event that a container with an active tunnel has been stopped, Hera gracefully shuts down the tunnel process.\n\nℹ️ Hera only monitors the state of containers that have been explicitly configured for Hera. Otherwise, containers and their events are completely ignored.\n\n# Getting Started\n## Prerequisites\n\n* Installation of Docker with a client API version of 1.22 or later\n* An active domain in Cloudflare with the Argo Tunnel service enabled\n* A valid Cloudflare certificate (see [Obtain a Certificate](#obtain-a-certificate))\n\n## Obtain a Certificate\n\nHera needs a Cloudflare certificate so it can manage tunnels on your behalf.\n\n1. Download a new certificate by visiting https://www.cloudflare.com/a/warp\n2. Rename the certificate to match your domain, ending in `.pem`. For example, a certificate for `mysite.com` should be named `mysite.com.pem`.\n3. Move the certificate to a directory that can be mounted as a volume (see [Required Volumes](#required-volumes)).\n\nHera will look for certificates with names matching your tunnels' hostnames and allows the use of multiple certificates. For more info, see [Using Multiple Domains](#using-multiple-domains).\n\n## Create a Network\n\nHera 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.\n\nIt is recommended to create a dedicated network for Hera and attach your desired containers to the new network.\n\nFor example, to create a network named `hera`:\n\n`docker network create hera`\n\n---\n\n# Running Hera\n\nHera can be started with the following command:\n\n```\ndocker run \\\n  --name=hera \\\n  --network=hera \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  -v /path/to/certs:/certs \\\n  aschzero/hera:latest\n```\n\n## Required Volumes\n\n* `/var/run/docker.sock` – Attaching the Docker daemon as a volume allows Hera to monitor container events.\n* `/path/to/certs` – The directory of your Cloudflare certificates.\n\n## Persisting Logs\n\nYou can optionally mount a volume to `/var/log/hera` to persist the logs on your host machine:\n\n```\ndocker run \\\n  --name=hera \\\n  --network=hera \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  -v /path/to/certs:/certs \\\n  -v /path/to/logs:/var/log/hera \\\n  aschzero/hera:latest\n```\n\nℹ️ Tunnel log files are named according to their hostname and can be found at `/var/log/hera/\u003chostname\u003e.log`\n\n## Tunnel Configuration\n\nHera 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:\n\n* `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.: `mysite.com` or `blog.mysite.com`).\n\n* `hera.port` - The port your service is running on inside the container.\n\n⚠️ _Note: you can still expose a different port to your host network if desired, but the `hera.port` label value needs to be the internal port within the container._\n\nHere's an example of a container configured for Hera with the `docker run` command:\n\n```\ndocker run \\\n  --network=hera \\\n  --label hera.hostname=mysite.com \\\n  --label hera.port=80 \\\n  nginx\n```\n\nThat's it! After the tunnel propagates, you would be able to see the default nginx welcome page when requesting `mysite.com`.\n\nViewing the logs would output something similar to below:\n\n```\n$ docker logs -f hera\n\n[INFO] Hera container found, connecting to 5aa5a300dd0e...\n[INFO] Registering tunnel mysite.com\ntime=\"2018-08-11T08:38:40Z\" level=info msg=\"Applied configuration from /var/run/s6/services/mysite.com/config.yml\"\ntime=\"2018-08-11T08:38:40Z\" level=info msg=\"Proxying tunnel requests to http://172.18.0.3:80\"\ntime=\"2018-08-11T08:38:40Z\" level=info msg=\"Starting metrics server\" addr=\"127.0.0.1:40521\"\ntime=\"2018-08-11T08:38:41Z\" level=info msg=\"Connected to SEA\"\ntime=\"2018-08-11T08:38:41Z\" level=info msg=\"Route propagating, it may take up to 1 minute for your new route to become functional\"\n...\n```\n\n### Stopping Tunnels\n\nStopping a container with an active tunnel will trigger it to shut down:\n\n```\n$ docker stop nginx\n$ docker logs -f hera\n\n[INFO] Stopping tunnel mysite.com\ntime=\"2018-08-11T09:00:53Z\" level=info msg=\"Initiating graceful shutdown...\"\ntime=\"2018-08-11T09:00:53Z\" level=info msg=\"Quitting...\"\ntime=\"2018-08-11T09:00:53Z\" level=info msg=\"Metrics server stopped\"\n```\n\n## Using Multiple Domains\n\nYou 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.\n\nFor example, tunnels for `mysite.com` or `blog.mysite.com` will use the certificate named `mysite.com.pem`.\n\nIf a certificate with a matching domain cannot be found, it will look for `cert.pem` in the same directory as a fallback.\n\n---\n\n# Examples\n\n## Subdomains\n\nAn example of a tunnel for Kibana pointing to `kibana.mysite.com`:\n\n```\ndocker run \\\n  --name=kibana \\\n  --network=hera \\\n  --label hera.hostname=kibana.mysite.com \\\n  --label hera.port=5601 \\\n  -p 5000:5601 \\\n  docker.elastic.co/kibana/kibana:6.2.4\n```\n\n## Docker Compose\n\n```yaml\nversion: '3'\n\nservices:\n  hera:\n    image: aschzero/hera:latest\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n      - /path/to/certs:/certs\n    networks:\n      - hera\n\n  nginx:\n    image: nginx:latest\n    networks:\n      - hera\n    labels:\n      hera.hostname: mysite.com\n      hera.port: 80\n\nnetworks:\n  hera:\n```\n\n# Contributing\n\n* If you'd like to contribute to the project, refer to the [contributing documentation](https://github.com/aschzero/hera/blob/master/CONTRIBUTING.md).\n* Read the [Development](https://github.com/aschzero/hera/wiki/Development) wiki for information on how to setup Hera for local development.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faschzero%2Fhera","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faschzero%2Fhera","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faschzero%2Fhera/lists"}