{"id":13540102,"url":"https://github.com/dokku/dokku-letsencrypt","last_synced_at":"2025-04-02T06:32:03.075Z","repository":{"id":39006811,"uuid":"47838113","full_name":"dokku/dokku-letsencrypt","owner":"dokku","description":"Automatic Let's Encrypt TLS Certificate installation for dokku","archived":false,"fork":false,"pushed_at":"2024-04-18T11:50:46.000Z","size":236,"stargazers_count":1090,"open_issues_count":12,"forks_count":93,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-10-30T00:56:03.720Z","etag":null,"topics":["dokku","dokku-letsencrypt","letsencrypt","nginx"],"latest_commit_sha":null,"homepage":"https://blog.semicolonsoftware.de/securing-dokku-with-lets-encrypt-tls-certificates/","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/dokku.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},"funding":{"github":"dokku","open_collective":"dokku","patreon":"dokku"}},"created_at":"2015-12-11T16:37:07.000Z","updated_at":"2024-10-22T18:52:22.000Z","dependencies_parsed_at":"2023-02-16T01:16:08.242Z","dependency_job_id":"6d30d354-cd42-4135-b4df-d0a2f33e9e06","html_url":"https://github.com/dokku/dokku-letsencrypt","commit_stats":{"total_commits":275,"total_committers":40,"mean_commits":6.875,"dds":0.6654545454545455,"last_synced_commit":"1ddac1c83dc57a19d448bdf59e97086029da28ab"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokku%2Fdokku-letsencrypt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokku%2Fdokku-letsencrypt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokku%2Fdokku-letsencrypt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokku%2Fdokku-letsencrypt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dokku","download_url":"https://codeload.github.com/dokku/dokku-letsencrypt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246515275,"owners_count":20790025,"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":["dokku","dokku-letsencrypt","letsencrypt","nginx"],"created_at":"2024-08-01T09:01:40.429Z","updated_at":"2025-04-02T06:32:03.068Z","avatar_url":"https://github.com/dokku.png","language":"Shell","funding_links":["https://github.com/sponsors/dokku","https://opencollective.com/dokku","https://patreon.com/dokku"],"categories":["Shell","others","\u003ca id=\"86d5daccb4ed597e85a0ec9c87f3c66f\"\u003e\u003c/a\u003eTLS\u0026\u0026SSL\u0026\u0026HTTPS"],"sub_categories":["\u003ca id=\"776c034543a65be69c061d1aafce3127\"\u003e\u003c/a\u003e新添加的"],"readme":"# dokku-letsencrypt\n\ndokku-letsencrypt is the official plugin for [dokku][dokku] that gives the ability to automatically retrieve and install TLS certificates from [letsencrypt.org](https://letsencrypt.org). During ACME validation, your app will stay available at any time.\n\n\u003e By running this plugin, you agree to the Let's Encrypt Subscriber Agreement automatically (because prompting you whether you agree might break running the plugin as part of a cronjob).\n\u003e\n\u003e If you like Let's Encrypt, please consider [donating to Let's Encrypt](https://letsencrypt.org/donate).\n\n## Installation\n\n```shell\nsudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git\nsudo dokku letsencrypt:cron-job --add # \u003c- To enable auto-renew\n```\n\n### Upgrading from previous versions\n\n```shell\nsudo dokku plugin:update letsencrypt\n```\n\n## Commands\n\n```\n$ dokku letsencrypt:help\n    letsencrypt:active \u003capp\u003e                Verify if letsencrypt is active for an app\n    letsencrypt:auto-renew                  Auto-renew all apps secured by letsencrypt if renewal is necessary\n    letsencrypt:auto-renew \u003capp\u003e            Auto-renew app if renewal is necessary\n    letsencrypt:cleanup \u003capp\u003e               Cleanup stale certificates and configurations\n    letsencrypt:cron-job \u003c--add|--remove\u003e   Add or remove an auto-renewal cronjob\n    letsencrypt:disable \u003capp\u003e               Disable letsencrypt for an app\n    letsencrypt:enable \u003capp\u003e                Enable or renew letsencrypt for an app\n    letsencrypt:list                        List letsencrypt-secured apps with certificate expiry\n    letsencrypt:revoke \u003capp\u003e                Revoke letsencrypt certificate for app\n```\n\n## Usage\n\n\u003e If using this plugin with Cloudflare:\n\u003e\n\u003e - The domain dns should be setup in \"Proxied\" mode\n\u003e - SSL/TLS mode must be in \"Full\" mode\n\u003e   - Using letsencrypt in \"Flexible\" mode will cause Cloudflare to detect your server as down\n\u003e   - Using \"Full\" mode will require disabling SSL/TLS in cloudflare in order to renew the certificate.\n\u003e\n\u003e If using \"Flexible\" SSL/TLS mode, avoid using this plugin.\n\u003e\n\u003e See these two links for more details:\n\u003e\n\u003e  - https://community.cloudflare.com/t/lets-encrypt-ssl-cannot-renew-with-cloudflare/257666\n\u003e  - https://support.cloudflare.com/hc/en-us/articles/214820528-Validating-a-Let-s-Encrypt-Certificate-on-a-Site-Already-Active-on-Cloudflare\n\nThe app which is obtaining a letsencrypt certificate must already be deployed and accessible over the internet (i.e. in the browser) in order to add letsencrypt to your app. This plugin will fail to apply for an app that has otherwise only been created.\n\nObtain a Let's encrypt TLS certificate for app `myapp` (you can also run this command to renew the certificate):\n\n```\n$ dokku letsencrypt:set myapp email your@email.tld\n-----\u003e Setting email to your@email.tld\n$ dokku letsencrypt:enable myapp\n=====\u003e Let's Encrypt myapp...\n-----\u003e Updating letsencrypt docker image...\nlatest: Pulling from dokku/letsencrypt\n\nDigest: sha256:20f2a619795c1a3252db6508f77d6d3648ad5b336e67caaf801126367dbdfa22\nStatus: Image is up to date for dokku/letsencrypt:latest\n       done\n-----\u003e Enabling letsencrypt proxy for myapp...\n-----\u003e Getting letsencrypt certificate for myapp...\n        - Domain 'myapp.mydomain.com'\n\n[ removed various log messages for brevity ]\n\n-----\u003e Certificate retrieved successfully.\n-----\u003e Symlinking let's encrypt certificates\n-----\u003e Configuring SSL for myapp.mydomain.com...(using /var/lib/dokku/plugins/available/nginx-vhosts/templates/nginx.ssl.conf.template)\n-----\u003e Creating https nginx.conf\n-----\u003e Running nginx-pre-reload\n       Reloading nginx\n-----\u003e Disabling letsencrypt proxy for myapp...\n       done\n```\n\nOnce the certificate is installed, you can use the `certs:*` built-in commands to edit and query your certificate.\n\nYou could also use the following command to set an email address for global. So you don't need to type the email address for different application.\n\n```shell\ndokku letsencrypt:set --global email your@email.tld\n```\n\n## Automatic certificate renewal\n\nTo enable the automatic renewal of certificates, a cronjob needs to be defined for\nthe `dokku` user which will run daily and renew any certificates that are due to\nbe renewed.\n\nThis can be done using the following command:\n\n```shell\ndokku letsencrypt:cron-job --add\n```\n\n## Configuration\n\n`dokku-letsencrypt` uses the [Dokku environment variable manager](https://dokku.com/docs/configuration/environment-variables/) for all configuration. The important environment variables are:\n\nVariable             | Default           | Description\n---------------------|-------------------|-------------------------------------------------------------------------\n`dns-provider`       | (none)            | The name of a [valid lego dns-provider](https://go-acme.github.io/lego/dns/)\n`email`              | (none)            | **REQUIRED:** E-mail address to use for registering with Let's Encrypt.\n`graceperiod`        | 2592000 (30 days) | Time in seconds left on a certificate before it should get renewed\n`lego-docker-args`   | (none)            | Extra arguments to pass via `docker run`. See the [lego CLI documentation](https://go-acme.github.io/lego/usage/cli/) for available options.\n`server`             | default           | Which ACME server to use. Can be 'default', 'staging' or a URL\n\nYou can set a setting using `dokku letsencrypt:set $APP $SETTING_NAME $SETTING_VALUE`. When looking for a setting, the plugin will first look if it was defined for the current app and fall back to settings defined by `--global`.\n\n\u003e Note: See \"DNS-01 Challenge\" for more information on configuration a dns-provider for DNS-01 based challenges and wildcard support.\n\n## Redirecting from HTTP to HTTPS\n\nDokku's default nginx template will automatically redirect HTTP requests to HTTPS when a certificate is present.\n\nYou can [customize the nginx template](https://dokku.com/docs/networking/proxies/nginx/) if you want different behaviour.\n\n## Design\n\n`dokku-letsencrypt` gets around having to disable your web server using the following workflow:\n\n  1. Temporarily add a reverse proxy for the `/.well-known/` path of your app to `https://127.0.0.1:$ACMEPORT`\n  2. Run [the acme/lego Let's Encrypt client](https://github.com/go-acme/lego) in a [Docker container](https://hub.docker.com/r/goacme/lego/) binding to `$ACMEPORT` to complete the ACME challenge and retrieve the TLS certificates\n  3. Install the TLS certificates\n  4. Remove the reverse proxy and reload nginx\n\nFor a more in-depth explanation, see [this blog post](https://blog.semicolonsoftware.de/securing-dokku-with-lets-encrypt-tls-certificates/)\n\n## Dockerfile and Image-based Deploys\n\nWhen securing Dockerfile and Image-based deploys with dokku-letsencrypt, be aware of the [proxy mechanism for dokku 0.6+](https://dokku.com/docs/networking/port-management/#dockerfile).\n\nFor Dockerfile deploys - as well as those via `git:from-image` - Dokku will determine which ports a container exposes (using `EXPOSE`) and will proxy them on the same port numbers on the host. If the Dockerfile exposes another port than 443, then HTTPS port 443 **needs to be manually configured** using the `dokku ports:*` commands in order for certificate validation and browsing to the app via HTTPS to work.\n\nA full workflow for creating a new Dockerfile/Image-based deployment (assuming the app is listening/exposed on port 5555) with `dokku-letsencrypt` would be:\n\n1. Create a new app `myapp` in dokku and push to the `dokku@myhost.com` remote.\n2. On the dokku host, use `dokku letsencrypt:enable myapp` to retrieve HTTPS certificates.\n3. On the dokku host, use `dokku ports:add myapp https:443:5555` to proxy HTTPS port 443 to port 5555 on the Docker image\n\nAfter these steps, the output of `dokku ports:report myapp` should look like this:\n\n```\n=====\u003e myapp ports information\n       Ports map:                     https:443:5555\n       Ports map detected:            https:5555:5555\n```\n\nReplace the container port (`5555` in the above example) with the port your app is listening on.\n\n## Dealing with rate limit\n\nBe aware that Let's Encrypt is subject to [rate limiting](https://letsencrypt.org/docs/rate-limits/). The limit about the number of certificates you can add on a domain per week is a concern for dokku because of the default domain added to your new applications, named like `\u003capp\u003e.\u003cdokku-domain\u003e`: using `dokku-letsencrypt` on all your applications would create a certificate for each application subdomain on `\u003cdokku-domain\u003e`.\n\nAs a workaround, if you want to encrypt many applications, make sure to add a proper domain for each one and remove their default domain before running `dokku-letsencrypt`. For example, if your dokku domain is `dokku.example.com` and you want to encrypt your `foo` app:\n\n```sh\ndokku domains:add foo foo.com\ndokku domains:remove foo foo.dokku.example.com\ndokku letsencrypt:enable foo\n```\n\nWhile playing around with this plugin, you might want to switch to the let's encrypt staging server by running `dokku letsencrypt:set myapp server  staging` to enjoy much higher rate limits and switching back to the real server by running `dokku letsencrypt:set myapp server` once you are ready.\n\n## Generating a Cert for multiple domains\n\nYour [default dokku app](https://dokku.com/docs/networking/proxies/nginx/?h=default+site#default-site) is accessible under the root domain too. So if you have an application `00-default` that is running under `00-default.mydomain.com` it is accessible under `mydomain.com` too. Now if you enable letsencrypt for your `00-default` application, it is not accessible anymore on `mydomain.com`. You can add the root domain to your dokku domains by typing:\n\n```shell\ndokku domains:add 00-default mydomain.com\ndokku letsencrypt:enable 00-default\n```\n\n## DNS-01 Challenge\n\n\u003e Functionality sponsored by [Orca Scan Ltd](https://orcascan.com/).\n\nIn order to provide a Letsencrypt certificate for a wildcard domain, a DNS-01 challenge must be used. To configure, the `dns-provider` property must be set to a [supported Lego provider](https://go-acme.github.io/lego/dns/). Additionally, the environment variables used by the DNS provider must be set as letsencrypt properties with the prefix `dns-provider-`. Both global and app-specific properties are supported.\n\n\u003e Warning: Before using a DNS-based challenge, ensure all DNS records - including wildcard records - are pointing at your server.\n\n```shell\n# set the provider to namecheap\ndokku letsencrypt:set --global dns-provider namecheap\n\n# set the properties necessary for namecheap usage\ndokku letsencrypt:set --global dns-provider-NAMECHEAP_API_USER user\ndokku letsencrypt:set --global dns-provider-NAMECHEAP_API_KEY key\n```\n\nDue to limitations in how certain DNS providers work, environment variables _must not_ use the `_FILE` based method for referring to values in files.\n\nPlease see the Lego documentation for your DNS provider for more information on what configuration is necessary to utilize DNS-01 challenges.\n\n## Conditional enabling\n\n`dokku letsencrypt:enable \u003capp\u003e` enables letsencrypt for an application or renews the certificate. This may lead to hitting rate limits with letsencrypt.\n\nTo avoid renewals, for example in a continuous deployment scenario, you could first check if letsencrypt has already been enabled for the app:\n\n```shell\ndokku letsencrypt:active \u003capp\u003e || dokku letsencrypt:enable \u003capp\u003e\n```\n\n## License\n\nThis plugin is released under the MIT license. See the file [LICENSE](LICENSE).\n\n[dokku]: https://github.com/dokku/dokku\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdokku%2Fdokku-letsencrypt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdokku%2Fdokku-letsencrypt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdokku%2Fdokku-letsencrypt/lists"}