Let's Encrypt plugin for Heroku apps
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.
How to use
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
If that is the case, use
~/.local/share/letsencrypt/bin/python to install, instead of just
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
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
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.
$ 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
How it works
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).