letsencrypt_http_challenge
A Rails::Engine answering Let's Encrypt ACME - Simple HTTP - Identifier Validation Challenges on a twelve-factor app along with the rake task to automate the certificate generation.
Installation
In you application, add this line to your Gemfile:
gem 'letsencrypt_http_challenge'
Install the gem with bundler:
$ bundle install
Or manually with the gem command:
$ gem install letsencrypt_http_challenge
Mount the engine in your application's routes.rb file
Rails.application.routes.draw do
mount LetsencryptHttpChallenge::Engine => "/" unless ENV['LE_HTTP_CHALLENGE_RESPONSE'].blank?
# Other routes...
end
Usage
Run the interactive generate_letsencrypt_cert
rake task from your local machine, setting the necessary environment variables:
$ LE_HTTP_CHALLENGE_CONTACT_EMAIL=admin@example.com LE_HTTP_CHALLENGE_CERTIFICATE_DOMAINS="www.example.com example.com" bundle exec rake generate_letsencrypt_cert
This will interact with the staging server. To obtain certificates from the production server, also add LE_HTTP_CHALLENGE_ENDPOINT='https://acme-v01.api.letsencrypt.org/'
to your environment
When prompted by the script, update the LE_HTTP_CHALLENGE_RESPONSE variable on the web server and restart it. This could be further automated depending on the features of the web server hosting environment. The initial release require manual updates for each domain that needs to be verified.
Run the test suite with:
bundle exec rake
A sample interaction could be as follow:
LE_HTTP_CHALLENGE_CONTACT_EMAIL=admin@example.com LE_HTTP_CHALLENGE_CERTIFICATE_DOMAINS="www.example.com example.com" bundle exec rake generate_letsencrypt_cert
Registering with Let's Encrypt service...
Success
Sending authorization request(s)...
Set
LE_HTTP_CHALLENGE_RESPONSE=6DOqR_BmMD02pYh-Rwpo3-1Dy-EauqbN_bFMbCypnsI.Iv478AtdWnuUCE6e-UfAJFN6y-F3YUTYG-skUvfYPJc
on your Rails web server and restart it.
You can test by pointing your browser to
www.example.com/.well-known/acme-challenge/6DOqR_BmMD02pYh-Rwpo3-1Dy-EauqbN_bFMbCypnsI
Looking good?
Press any key to continue.
Requesting verification...
Set
LE_HTTP_CHALLENGE_RESPONSE=JvWeOoR-NgyQINyR92QhtFPOL7txd8EHSx94Lh466p4.Iv478AtdWnuUCE6e-UfAJFN6y-F3YUTYG-skUvfYPJc
on your Rails web server and restart it.
You can test by pointing your browser to
example.com/.well-known/acme-challenge/JvWeOoR-NgyQINyR92QhtFPOL7txd8EHSx94Lh466p4
Looking good?
Press any key to continue.
Requesting verification...
Requesting the certificate...
Certificate saved
For a server hosted on Heroku:
# Set the variable manually from the command line or from their web based console
heroku config:set LE_HTTP_CHALLENGE_RESPONSE=JPizvzEPdRV4c4jRuNeFiLt0CCzL4aX-m4Ota1WYxh4.E_dQtIfQA9oIW2T7stzq9SgogpUQS2Ha2A4mxlCeAPk --app your_app_name
# Deleted it after the verification is done
heroku config:unset LE_HTTP_CHALLENGE_RESPONSE --app your_app_name
# Update an existing certificate
heroku certs:update fullchain.pem privkey.pem --app your_app_name
For more information about SSL on Heroku, please refer to their Dev Center article: https://devcenter.heroku.com/articles/ssl-endpoint
Finally, store the certificate files created by the script privkey.pem cert.pem chain.pem fullchain.pem
in a safe location.
TODO
- Automate the deployment on Heroku and other hosting services
Acknowledgements
LetsencryptHttpChallenge was inspired by:
- lgromanowski/letsencrypt-plugin https://github.com/lgromanowski/letsencrypt-plugin
- unixcharles/acme-client https://github.com/unixcharles/acme-client