How to use Let’s Encrypt on Hypernode. [BETA]
Table of contents
- 1 Introduction
- 2 Configuration
- 3 Manually renew your certificates
- 4 Stop using dehydrated / Cleanup
- 5 Troubleshooting
Let’s Encrypt is a fairly new CA Authority that provides free SSL certificates through domain validation and automated retrieval.
It is started as a joint effort by big companies in the IT world to provide free and transparent SSL certification and validation through automation.
The key principles behind Let’s Encrypt are, (taken from their website):
- Free: Anyone who owns a domain name can use Let’s Encrypt to obtain a trusted certificate at zero cost.
- Automatic: Software running on a web server can interact with Let’s Encrypt to painlessly obtain a certificate, securely configure it for use, and automatically take care of renewal.
- Secure: Let’s Encrypt will serve as a platform for advancing TLS security best practices, both on the CA side and by helping site operators properly secure their servers.
- Transparent: All certificates issued or revoked will be publicly recorded and available for anyone to inspect.
- Open: The automatic issuance and renewal protocol will be published as an open standard that others can adopt.
- Cooperative: Much like the underlying Internet protocols themselves, Let’s Encrypt is a joint effort to benefit the community, beyond the control of any one organization.
See their website for more information about how to use Let’s Encrypt
To make use of Let’s Encrypt on Hypernodes, we installed the
dehydrated Let’s Encrypt client.
This command-line utility orders and renews a certificate through the LE API and stores the retrieved certificates on disk so we can use them in the Nginx configuration.
dehydrated to manage SSL certificates for a domain, add the domain to the list of domains:
echo 'your_hypernode_app_name.hypernode.io' > /data/web/.dehydrated/domains.txt
dehydrated to request a certificate:
dehydrated -c --create-dirs
This will create a directory tree in
/data/web/certs with the configured certificates
Make sure you add an entry for each domain record you need ssl for. This means that you should add both the
example.com on it’s own line to the
Add existing Let’s Encrypt certificates to be renewed by dehydrated
If you want to use a different Let’s Encrypt client you can do so as well, just place your cert.pem, chain.pem and fullchain.pem files in the /data/web/certs directory in a subdirectory with as name the domain name the certificate is for.
The directory tree will look like this if you have example.com and example.net:
find /data/web/certs example.com/ example.com/fullchain.pem example.com/cert.pem example.com/privkey.pem example.net/ example.net/fullchain.pem example.net/cert.pem example.net/privkey.pem
When a certificate is renewed, the old certificate will be renamed to cert-
unique id for recovery usage.
Manually renew your certificates
To force renewal on your certificates, even when the certificate is longer valid than 30 days, use the
dehydrated -c --force
Be careful not to exceed the ratelimits at Let’s Encrypt!
Multiple domains for one shop
Dehydrated does support multi domain certificates but our config generator does not. This implicates that if you want to serve both your
apex domain over SSL, you should add both records on it’s own line to
.dehydrated/domains.txt to ensure a valid nginx configuration is created for both domains.
cat ~/.dehydrated/domains.txt example.hypernode.io example.com www.example.com example.nl www.example.nl
Configure the Hypernode and Magento to support Let’s Encrypt
After creating certificates you need to update the Nginx configuration. This is done using the script
When you run this script, an SSL enabled Nginx configuration for your shop is generated in
After creating an Nginx configuration, you should adjust your Magento base URL’s to support SSL:
- For Magento 1:
magerun sys:store:config:base-url:set # set your baseurl to secure (https) magerun cache:clean
- For Magento 2:
cd ~/magento2 magerun2 sys:store:config:base-url:list magerun2 cache:clean
Setup a cron to automatically renew certificates
To periodically check and renew certificates, create a cronjob running dehydrated:
PATH="/data/web/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" MAILTO="email@example.com" 0 1 * * * flock -n /data/web/.dehydrated.lock chronic dehydrated --cron --create-dirs
This will check nightly at 1:00 if there are configured certificates that should be renewed.
Stop using dehydrated / Cleanup
If you want to switch to an SSL certificate managed by Byte (for example you switch to an SSL EV certificate), you can easily remove the configuration and certificated for Let’s Encrypt:
- Remove the
- Remove the
/data/web(you might want to make a backup first)
- Remove all domains from the
- Remove the cronjob from your crontab
- Renew the Nginx configuration by running
- By default,
dehydratedrenews Let’s Encrypt certificates 30 days before expiring.
Make sure your cron is running, else
dehydratedwill not automagically renew certificates before expiration.
You can request a maximum of 20 domains per week per IP and a maximum of 5 certificates per domain per week. See: Let’s Encrypt about ratelimits
“Error creating new cert :: Too many certificates already issued for: […]”
This is not an issue with dehydrated but an API limit with boulder (the Let’s Encrypt CA request server).
At the time of writing this you can only create 5 certificates per domain in a sliding window of 7 days.
“Certificate request has 123 names, maximum is 100.”
This also is an API limit from boulder, you are requesting to sign a multi domain certificate with way too many domains.
“My certificates are not in the Nginx config”
This can be caused by a change in your Nginx config not picked up by the
nginx-config-reloader. To manually force a reload, touch some files in /data/web/nginx`:
“Error code: MOZILLA_PKIX_ERROR_REQUIRED_TLS_FEATURE_MISSING”
This error appears in Firefox and is caused by a inconsistency in our configuration. We changed this configuration by disabling
OCSP stapling. If you keep getting this error, please recreate your Let’s Encrypt certificate:
rm -rf /data/web/certs dehydrated -c