This is an instruction for Mac OS X with homebrew

primary source:

Tomáš Vestenický on Medium - “How to set up SSL with Let’s Encrypt on Heroku for free”

Please, read this guide as a whole first, as this can’t be done step by step!

Please! donate to letsencrypt for their incredible service, if you use it.


heroku offers automated certificate management (acm) for free with paid dynos

  • install certbot brew install certbot

  • set up your app in heroku
    • running on a hobby dyno at least
    • Custom domains set up and running
  • modify your controller (in this example pages_controller.rb - make sure your setting correspond with the following route settings)
      def letsencrypt
        # second-part-of-string-random-characters
        # will be a key that certbot / letsencrypt create for you
        # you need to replace "second-part-of-string-random-characters" later
        render text: "#{params[:id]}.second-part-of-string-random-characters"
  • add a route for your rails app in routes.rb
    # Let’s encrypt
    get '/.well-known/acme-challenge/:id' => 'pages#letsencrypt'
  • run certbot:

    sudo certbot certonly --manual

    the program will guide you through the setup, it needs your primary and valid contact email and urls (with and without “www”).

    Certbot will ultimately present you a key. It will probably look like this.


    Look for the “.” in the middle. Copy the part of the key after the dot and replace second-part-of-string-random-characters in your controller method for letsencrypt (see above).


  • your app is now set up properly, please push your app to heroku

  • after your updated app is online, continue with certbot and finish the process, the certificate and all keys will be generated for you under: /etc/letsencrypt/live/<your.domain>/

  • Now all what’s left to do, is pushing the keys to heroku for your app. Fire up a new terminal, replace <your.domain> and <your-app> in the following line according to your setup:
    $ sudo heroku _certs:add /etc/letsencrypt/live/<your.domain>/fullchain.pem /etc/letsencrypt/live/<your.domain>/privkey.pem — app <your-app>


I do not need automation for this process, refreshing the certificate every 3 months is fine for me. One more time: Please do not forget to donate to letsencrypt for their incredible service.

More on this:

Tomáš Vestenický on Medium - “How to set up SSL with Let’s Encrypt on Heroku for free”

linode: Install Let’s Encrypt to Create SSL Certificates


In case you want your staging app not to enforce SSL:

  • setup a environment variable on heroku for your production app e.g. FORCE_SSL = true and edit your app’s production.rb to:
    config.force_ssl = true if ENV['FORCE_SSL'] == true