{"id":24160328,"url":"https://github.com/JonasAlfredsson/docker-nginx-certbot","last_synced_at":"2025-09-20T04:31:48.882Z","repository":{"id":38354715,"uuid":"152468227","full_name":"JonasAlfredsson/docker-nginx-certbot","owner":"JonasAlfredsson","description":"Automatically create and renew website certificates for free using the Let's Encrypt certificate authority.","archived":false,"fork":false,"pushed_at":"2025-08-24T12:33:06.000Z","size":443,"stargazers_count":1123,"open_issues_count":3,"forks_count":189,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-08-24T18:07:38.568Z","etag":null,"topics":["acme","armv7","certbot","certificate-authority","dhparam","dns-01-challange","docker","ecdsa","hacktoberfest","https","ipv6","letsencrypt","live-reload","localhost","nginx","offline-capable","ssl","ssl-certificates","wildcard-certificates"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/jonasal/nginx-certbot","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/JonasAlfredsson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null},"funding":{"github":"JonasAlfredsson","patreon":"jonasal","ko_fi":"jonasal","custom":["buymeacoffee.com/jonasal","paypal.me/JonasAlfredsson"]}},"created_at":"2018-10-10T18:08:50.000Z","updated_at":"2025-08-24T12:33:02.000Z","dependencies_parsed_at":"2023-10-05T02:09:09.636Z","dependency_job_id":"c7a913fa-bc4d-41e2-993b-2e25f924b210","html_url":"https://github.com/JonasAlfredsson/docker-nginx-certbot","commit_stats":null,"previous_names":[],"tags_count":122,"template":false,"template_full_name":null,"purl":"pkg:github/JonasAlfredsson/docker-nginx-certbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasAlfredsson%2Fdocker-nginx-certbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasAlfredsson%2Fdocker-nginx-certbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasAlfredsson%2Fdocker-nginx-certbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasAlfredsson%2Fdocker-nginx-certbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JonasAlfredsson","download_url":"https://codeload.github.com/JonasAlfredsson/docker-nginx-certbot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasAlfredsson%2Fdocker-nginx-certbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276046871,"owners_count":25575876,"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","status":"online","status_checked_at":"2025-09-20T02:00:10.207Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["acme","armv7","certbot","certificate-authority","dhparam","dns-01-challange","docker","ecdsa","hacktoberfest","https","ipv6","letsencrypt","live-reload","localhost","nginx","offline-capable","ssl","ssl-certificates","wildcard-certificates"],"created_at":"2025-01-12T16:02:03.701Z","updated_at":"2025-09-20T04:31:48.868Z","avatar_url":"https://github.com/JonasAlfredsson.png","language":"Shell","funding_links":["https://github.com/sponsors/JonasAlfredsson","https://patreon.com/jonasal","https://ko-fi.com/jonasal","buymeacoffee.com/jonasal","paypal.me/JonasAlfredsson"],"categories":["Shell"],"sub_categories":[],"readme":"# docker-nginx-certbot\n\nAutomatically create and renew website SSL certificates using the\n[Let's Encrypt][1] free certificate authority and its client [*certbot*][2].\nBuilt on top of the [official Nginx Docker images][9] (both Debian and Alpine),\nand uses OpenSSL/LibreSSL to automatically create the Diffie-Hellman parameters\nused during the initial handshake of some ciphers.\n\n\u003e :information_source: The very first time this container is started it might\n  take a long time before it is ready to respond to requests. Read more\n  about this in the\n  [Diffie-Hellman parameters](./docs/good_to_know.md#diffie-hellman-parameters)\n  section.\n\n\u003e :information_source: Please use a [specific tag](./docs/dockerhub_tags.md)\n  when doing a Docker pull, since `:latest` might not always be 100% stable.\n\n### Noteworthy Features\n- Handles multiple server names when [requesting certificates](./docs/good_to_know.md#how-the-script-add-domain-names-to-certificate-requests) (i.e. both `example.com` and `www.example.com`).\n- Handles wildcard domain request in case you use [DNS authentication](./docs/certbot_authenticators.md).\n- Can request both [RSA and ECDSA](./docs/good_to_know.md#ecdsa-and-rsa-certificates) certificates ([at the same time](./docs/advanced_usage.md#multi-certificate-setup)).\n- Will create [Diffie-Hellman parameters](./docs/good_to_know.md#diffie-hellman-parameters) if they are defined.\n- Uses the [parent container][9]'s [`/docker-entrypoint.d/`][7] folder.\n- Will report correct [exit code][6] when stopped/killed/failed.\n- You can do a live reload of configs by [sending in a `SIGHUP`](./docs/advanced_usage.md#manualforce-renewal) signal (no container restart needed).\n- Possibility to use this image **offline** with the help of a [local CA](./docs/advanced_usage.md#local-ca).\n- Both [Debian and Alpine](./docs/dockerhub_tags.md) images built for [multiple architectures][14].\n\n\n\n# Acknowledgments and Thanks\n\nThis container requests SSL certificates from [Let's Encrypt][1], with the help\nof their [*certbot*][2] script, which they provide for the absolutely bargain\nprice of free! If you like what they do, please [donate][3].\n\nThis repository was originally forked from [`@henridwyer`][4] by\n[`@staticfloat`][5], before it was forked again by me. However, the changes to\nthe code has since become so significant that this has now been detached as its\nown independent repository (while still retaining all the history). Migration\ninstructions, from `@staticfloat`'s image, can be found\n[here](./docs/good_to_know.md#help-migrating-from-staticfloats-image).\n\n\n\n# Usage\n\n## Before You Start\n1. This guide expects you to already own a domain which points at the correct\n   IP address, and that you have both port `80` and `443` correctly forwarded\n   if you are behind NAT. Otherwise I recommend [DuckDNS][12] as a Dynamic DNS\n   provider, and then either search on how to port forward on your router or\n   maybe find it [here][13].\n\n2. I suggest you read at least the first two sections in the\n   [Good to Know](./docs/good_to_know.md) documentation, since this will give\n   you some important tips on how to create a basic server config, and how to\n   use the Let's Encrypt staging servers in order to not get rate limited.\n\n3. I don't think it is necessary to mention if you managed to find this\n   repository, but you will need to have [Docker][11] installed for this to\n   function.\n\n\n## Available Environment Variables\n\n### Required\n- `CERTBOT_EMAIL`: Your e-mail address. Used by Let's Encrypt to contact you in case of security issues.\n\n### Optional\n- `DHPARAM_SIZE`: The size of the [Diffie-Hellman parameters](./docs/good_to_know.md#diffie-hellman-parameters) (default: `2048`)\n- `ELLIPTIC_CURVE`: The size/[curve][15] of the ECDSA keys (default: `secp256r1`)\n- `RENEWAL_INTERVAL`: Time interval between certbot's [renewal checks](./docs/good_to_know.md#renewal-check-interval) (default: `8d`)\n- `RSA_KEY_SIZE`: The size of the RSA encryption keys (default: `2048`)\n- `STAGING`: Set to `1` to use Let's Encrypt's [staging servers](./docs/good_to_know.md#initial-testing) (default: `0`)\n- `USE_ECDSA`: Set to `0` to have certbot use [RSA instead of ECDSA](./docs/good_to_know.md#ecdsa-and-rsa-certificates) (default: `1`)\n\n### Advanced\n- `CERTBOT_AUTHENTICATOR`: The [authenticator plugin](./docs/certbot_authenticators.md) to use when responding to challenges (default: `webroot`)\n- `CERTBOT_DNS_PROPAGATION_SECONDS`: The number of seconds to wait for the DNS challenge to [propagate](./docs/certbot_authenticators.md#troubleshooting-tips) (default: certbot's default)\n- `CERTBOT_DNS_CREDENTIALS_DIR`: Directory where credentials for [DNS authenticators](./docs/certbot_authenticators.md#preparing-the-container-for-dns-01-challenges) should be located (default: `/etc/letsencrypt`).\n- `DEBUG`: Set to `1` to enable debug messages and use the [`nginx-debug`][10] binary (default: `0`)\n- `USE_LOCAL_CA`: Set to `1` to enable the use of a [local certificate authority](./docs/advanced_usage.md#local-ca) (default: `0`)\n\n\n## Volumes\n- `/etc/letsencrypt`: Stores the obtained certificates and the Diffie-Hellman parameters\n\n\n## Run with `docker run`\nCreate your own [`user_conf.d/`](./docs/good_to_know.md#the-user_confd-folder)\nfolder and place all of you custom server config files in there. When done you\ncan just start the container with the following command\n([available tags](./docs/dockerhub_tags.md)):\n\n```bash\ndocker run -it -p 80:80 -p 443:443 \\\n           --env CERTBOT_EMAIL=your@email.org \\\n           -v $(pwd)/nginx_secrets:/etc/letsencrypt \\\n           -v $(pwd)/user_conf.d:/etc/nginx/user_conf.d:ro \\\n           --name nginx-certbot jonasal/nginx-certbot:latest\n```\n\n\u003e You should be able to detach from the container by holding `Ctrl` and pressing\n  `p` + `q` after each other.\n\nAs was mentioned in the introduction; the very first time this container is\nstarted it might take a long time before before it is ready to\n[respond to requests](./docs/good_to_know.md#diffie-hellman-parameters), please\nbe a little bit patient. If you change any of the config files after the\ncontainer is ready, you can just\n[send in a `SIGHUP`](./docs/advanced_usage.md#manualforce-renewal) to tell\nthe scripts and Nginx to reload everything.\n\n```bash\ndocker kill --signal=HUP \u003ccontainer_name\u003e\n```\n\n\n## Run with `docker-compose`\nAn example of a [`docker-compose.yaml`](./examples/docker-compose.yml) file can\nbe found in the [`examples/`](./examples) folder. The default parameters that\nare found inside the [`nginx-certbot.env`](./examples/nginx-certbot.env) file\nwill be overwritten by any environment variables you set inside the `.yaml`\nfile.\n\n\u003e NOTE: You can use both `environment:` and `env_file:` together or only one\n        of them, the only requirement is that `CERTBOT_EMAIL` is defined\n        somewhere.\n\nLike in the example above, you just need to place your custom server configs\ninside your [`user_conf.d/`](./docs/good_to_know.md#the-user_confd-folder)\nfolder beforehand. Then you start it all with the following command.\n\n```bash\ndocker-compose up\n```\n\n\n## Build It Yourself\nThis option is for if you make your own `Dockerfile`. Check out which tags that\nare available in [this document](./docs/dockerhub_tags.md), or on\n[Docker Hub][8], and then choose how specific you want to be.\n\nIn this case it is possible to completely skip the\n[`user_conf.d/`](./docs/good_to_know.md#the-user_confd-folder) folder and just\nwrite your files directly into Nginx's `conf.d/` folder. This way you can\nreplace the files I have built [into the image](./src/nginx_conf.d) with your\nown. However, if you do that please take a moment to understand what they do,\nand what you need to include in order for certbot to continue working.\n\n```Dockerfile\nFROM jonasal/nginx-certbot:latest\nCOPY conf.d/* /etc/nginx/conf.d/\n```\n\n\n\n# Tests\nWe make use of [BATS][16] to test parts of this codebase. The easiest way to\nrun all the tests is to execute the following command in the root of this\nrepository:\n\n```bash\ndocker run -it --rm -v \"$(pwd):/workdir\" ffurrer/bats:latest ./tests\n```\n\n\n\n# More Resources\nHere is a collection of links to other resources that provide useful\ninformation.\n\n- [Good to Know](./docs/good_to_know.md)\n  - A lot of good to know stuff about this image and the features it provides.\n- [Changelog](./docs/changelog.md)\n  - List of all the tagged versions of this repository, as well as bullet points to what has changed between the releases.\n- [DockerHub Tags](./docs/dockerhub_tags.md)\n  - All the tags available from Docker Hub.\n- [Advanced Usage](./docs/advanced_usage.md)\n  - Information about the more advanced features this image provides.\n- [Certbot Authenticators](./docs/certbot_authenticators.md)\n  - Information on the different authenticators that are available in this image.\n- [Nginx Tips](./docs/nginx_tips.md)\n  - Some interesting tips on how Nginx can be configured.\n\n\n\n# External Guides\nHere is a list of projects that use this image in various creative ways. Take\na look and see if one of these helps or inspires you to do something similar:\n\n- [A `Node.js` application served over HTTPS in AWS Elastic Beanstalk](https://efraim-rodrigues.medium.com/using-docker-to-containerize-your-node-js-aefcd1ecd37d)\n- [Host your own `Nakama` server](https://www.snopekgames.com/tutorial/2021/how-host-nakama-server-10mo)\n\n\n\n\n\n[1]: https://letsencrypt.org/\n[2]: https://github.com/certbot/certbot\n[3]: https://letsencrypt.org/donate/\n[4]: https://github.com/henridwyer/docker-letsencrypt-cron\n[5]: https://github.com/staticfloat/docker-nginx-certbot\n[6]: https://github.com/JonasAlfredsson/docker-nginx-certbot/commit/43dde6ec24f399fe49729b28ba4892665e3d7078\n[7]: https://github.com/nginxinc/docker-nginx/tree/master/entrypoint\n[8]: https://hub.docker.com/r/jonasal/nginx-certbot\n[9]: https://github.com/nginxinc/docker-nginx\n[10]: https://github.com/docker-library/docs/tree/master/nginx#running-nginx-in-debug-mode\n[11]: https://docs.docker.com/engine/install/\n[12]: https://www.duckdns.org/\n[13]: https://portforward.com/router.htm\n[14]: https://github.com/JonasAlfredsson/docker-nginx-certbot/issues/28\n[15]: https://security.stackexchange.com/a/104991\n[16]: https://github.com/bats-core/bats-core\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJonasAlfredsson%2Fdocker-nginx-certbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJonasAlfredsson%2Fdocker-nginx-certbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJonasAlfredsson%2Fdocker-nginx-certbot/lists"}