{"id":13337976,"url":"https://github.com/zbo14/tls-refresh","last_synced_at":"2026-04-13T22:03:58.016Z","repository":{"id":94588831,"uuid":"368681769","full_name":"zbo14/tls-refresh","owner":"zbo14","description":"🤖 Auto-generate and renew your TLS certificates for HAProxy using certbot","archived":false,"fork":false,"pushed_at":"2021-05-31T22:14:10.000Z","size":41,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2025-01-31T14:27:37.344Z","etag":null,"topics":["bash","certbot","docker","docker-compose","haproxy","letsencrypt","tls"],"latest_commit_sha":null,"homepage":"https://zachh.me/blog/automatic-certificate-renewal-without-downtime/","language":"Shell","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/zbo14.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-18T22:29:37.000Z","updated_at":"2021-06-18T16:53:34.000Z","dependencies_parsed_at":"2023-03-02T22:15:39.081Z","dependency_job_id":null,"html_url":"https://github.com/zbo14/tls-refresh","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbo14%2Ftls-refresh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbo14%2Ftls-refresh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbo14%2Ftls-refresh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbo14%2Ftls-refresh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zbo14","download_url":"https://codeload.github.com/zbo14/tls-refresh/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245659051,"owners_count":20651525,"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":["bash","certbot","docker","docker-compose","haproxy","letsencrypt","tls"],"created_at":"2024-07-29T19:15:16.644Z","updated_at":"2026-04-13T22:03:57.969Z","avatar_url":"https://github.com/zbo14.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tls-refresh\n\nAuto-generate and renew your TLS certificates for [HAProxy](https://www.haproxy.org/) using [certbot](https://certbot.eff.org/)!\n\n## Overview\n\nHAProxy is very handy as a reverse proxy and well-suited for load balancing across several backend servers. It can also perform TLS termination so there's no need to update TLS certificates on each backend server. I thought it might be cool to have a Dockerized HAProxy + certbot configuration that would auto-renew certificates and leverage HAProxy's [runtime API](https://www.haproxy.com/blog/dynamic-configuration-haproxy-runtime-api/) to update TLS credentials without restarting the service and introducing downtime.\n\n## Dependencies\n\n`tls-refresh` should work across UN\\*X systems 🤞\n\n* [Docker](https://docs.docker.com/get-docker/)\n* [Compose](https://docs.docker.com/compose/install/)\n\n## Usage\n\n### Setup\n\n`$ ./tls-refresh setup`\n\nThis command does the following:\n\n* Prompts you for domain and email address\n* Customizes environment file and HAProxy TLS settings\n* Builds Docker images for certbot and demo server\n* Generates self-signed (placeholder) certificate for HAProxy\n* Specifies weekly cron job to check certificate renewal\n\nYour domain and email address are stored in `./etc/tls-refresh/.env` (gitignored).\n\n### Configuration\n\n`tls-refresh` ships with a NodeJS HTTP server that responds to requests with a short note about this project. This is meant for testing and demo purposes to ensure that certificate generation and renewal works.\n\nTo substitute your own web service, run `./tls-server configure`. This command prompts for the following service information:\n\n* Docker image (Default: tls-refresh-server)\n* Name (Default: \"server\")\n* Listening port (Default: 9000)\n* Scale / # of instances (Default: 2)\n\nIt then stores this information in `./etc/tls-refresh/.env` and modifies the `docker-compose.yml` and `./etc/haproxy/haproxy.cfg` files accordingly.\n\nFurther configuration of `docker-compose.yml` or `haproxy.cfg` must be done manually. Please refer to the appropriate [documentation](#Resources).\n\n### Start\n\nStart the HAProxy gateway, certbot, and web server!\n\n`$ ./tls-refresh start`\n\n### Stop\n\nStop and remove the running containers.\n\n`$ ./tls-refresh stop`\n\n## Design\n\nEach service (i.e. HAProxy, certbot, web server) runs in a Docker container on the Docker network, `tls-refresh`. The entire configuration is defined in the aforementioned `docker-compose.yml` file.\n\nThis configuration has a few advantages:\n\n* We don't need to install any dependencies locally besides Docker + Compose\n* The services can communicate with each other via DNS names\n* HAProxy is the only service with exposed ports; everything else sits behind it\n\nA weekly cron job runs cerbot in a Docker container on the `tls-refresh` network to renew the TLS certificate, if need be. On successful renewal, a [deploy hook](./etc/letsencrypt/renewal-hooks/deploy/update-haproxy) executes and updates HAProxy's TLS settings to use the new certificate. You can view the renewal logs at `./logs/tls-refresh-certbot.out` and `./logs/tls-refresh-certbot.err`.\n\n**Note:** the certbot containers *aren't* persistent like the HAProxy gateway or web server; they should create or renew the certificate and then exit.\n\nHAProxy automatically redirects HTTP traffic (port 80) to the HTTPS endpoint (port 443) *unless* the requested path begins with `/.well-known/acme-challenge/`. This route allows [Let's Encrypt](https://letsencrypt.org/) to validate control of your domain and provision a certificate.\n\n## Contributing\n\nWant to make `tls-refresh` better?\n\n[Open an issue](https://github.com/zbo14/tls-refresh/issues/new) or [create a pull request](https://github.com/zbo14/tls-refresh/compare/develop...) and let's take it from there!\n\n## Resources\n\n* https://certbot.eff.org/docs/using.html\n* https://cbonte.github.io/haproxy-dconv/2.4/configuration.html\n* https://docs.docker.com/compose/\n* https://www.haproxy.com/blog/dynamic-ssl-certificate-storage-in-haproxy/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzbo14%2Ftls-refresh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzbo14%2Ftls-refresh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzbo14%2Ftls-refresh/lists"}