Let's Encrypt (certbot) plugin for Heroku apps
OTHER License
THIS PLUGIN IS DEPRECATED
A plugin for the certbot (Let's Encrypt) client that allows you to automate the installation, and most importantly the renewal, of SSL certificates for you Heroku apps.
If you are paying anything to Heroku for your app, you can use Heroku's ACM feature to automatically generate and renew Let's Encrypt certificates for your app. Ref: https://devcenter.heroku.com/articles/automated-certificate-management
If you are using Heroku free plan, sadly, Heroku discontinued support for SSL for you.
And thus, this plugin is now deprecated, unless you somehow can't or don't want to use ACM. If so, continue below.
Requirements: Heroku CLI and certbot (or certbot-auto) installed. You should run heroku
at least once to make sure it's set-up correctly.
Note that the authorization plugin is not compatible with Heroku's Preboot feature. If enabled for the specified app, it will be temporarily disabled to allow the plugin to do it's job.
1. Install the certbot-heroku plugin:
Is your client called certbot-auto
? See note 1 below.
Did you install certbot
on Mac using Homebrew? See note 2 below.
$ curl -LO https://github.com/gboudreau/certbot-heroku/archive/master.zip
$ unzip master.zip && rm master.zip
$ cd certbot-heroku-master
$ pip install . # or `python setup.py install`
Note 1: Your LE client might be called certbot-auto
instead of certbot
.
If that is the case, use ~/.local/share/letsencrypt/bin/pip
or ~/.local/share/letsencrypt/bin/python
to install, instead of just pip
or python
.
Also, you will need to re-install the plugin each time certbot-auto
upgrades to a newer version, which it will do automatically unless you specify the --no-self-upgrade
parameter when running certbot-auto
.
Note 2: If you installed certbot
using Homebrew on Mac, find the full path to the python
binary using this command:
cat $(which certbot) | head -1
Then use the full path to the pip
binary found in the same folder to install.
Also, you will need to re-install the plugin each time Homebrew will update certbot
.
Did it work?
$ certbot plugins
[...]
* certbot-heroku:heroku
Description: Heroku SSL
[...]
2. Server-side script:
In order for ACME authentication to succeed, you need to configure your Heroku app to answer the ACME challenge with the appropriate value (stored in the LETS_ENCRYPT_CHALLENGE
environment variable).
How you do that depends on the buildpack you use. See examples in the server/ folder.
3. Usage:
$ certbot run --configurator certbot-heroku:heroku -H YourHerokuAppName -d www.example.com
or
$ certbot certonly --authenticator certbot-heroku:heroku -H YourHerokuAppName -d www.example.com
or
$ certbot install --installer certbot-heroku:heroku -H YourHerokuAppName -d www.example.com
Before issuing a SSL certificate, the Certificate Authority (CA) needs to insure that you are the owner of the domain for which want the certificate. Let's Encrypt allows different protocols for doing so, but the one that is the easiest for most people is ACME. ACME is a protocol where the CA generates a random string, gives it to you, and asks you to put that string on your web server. On most servers, that would require simply dropping a text file at the right place on your web server, but with Heroku, that would require committing this file into git, and pushing to Heroku, before the CA could verify your ownership of the domain you are interested in.
This plugin simplify this by using an Heroku config var (LETS_ENCRYPT_CHALLENGE
) to store and answer the challenge.
Some initial set-up is required, but once it's working, renewals can be automated very easily.
Once the domain is authenticated, a new certificate is generated (by the Let's Encrypt CA), and is stored on your computer.
The plugin will take that certificate, and the associated key, and install those on your Heroku app.
It does that using the heroku certs
command (ref).