EasyEngine uses AcmePHP library to manage SSL certificates. You pass --ssl
flag to create a site with SSL.
Currently there are three options you can pass to --ssl
flag
--ssl=le
. It should be used if you want to issue a new certificate from Let’s Encrypt.--ssl=inherit
. It should be used if there’s an existing siteexample.com
with wildcard certificate and you want to createabc.example.com
which will inherit (reuse) the certificate ofexample.com
instead of issuing a new one.--ssl=self
if you want to create a self signed certificate. Useful for https site on local machine.
Getting Certificate from Let’s Encrypt
In order to get certificate from Let’s Encrypt, you’ll have to use --ssl=le
flag during site create.
ee site create example.com --type=wp --ssl=le
Optionally, If you want a wildcard certificate, you also need to pass --wildcard
flag.
ee site create example.com --type=wp --ssl=le --wildcard
⚠️ Note: If you’ve used --wildcard
flag, you need to run following command after adding your DNS entries:
ee site ssl example.com
In order to get a SSL certificate from a certificate authority, you have to prove to the certificate authority that you own the domain. The certificate authority gives you a “challenge” to prove that you own the domain. You then need to “solve” the given challenge. The certificate authority gives you two primary methods which can be used to solve challenge –
- HTTP Challenge
- DNS Challenge
HTTP Challenge
When you use --ssl=le
, by default this method is selected unless you’ve used --wildcard
flag. EasyEngine automatically “solves” the challenge for you if this method is selected. Its only requirement is that the domain of site should point to the server where you’re creating site.
First of all, the certificate authority (Let’s Encrypt) tells us to put a specific string in a file at example.com/.well-known/acme-challenge/xxxxxxxxxxxxxxxx
. Once you do it, the certificate authority checks if you have added the given string there. If it finds that specific string there, it marks the given challenge as solved and gives you certificate for the domain. However, you don’t need to worry about doing any of this as EasyEngine already handles it for you.
DNS Challenge
When you use --ssl=le
with --wildcard
flag, DNS challenge is used by default as it is the only method which supports wildcard certificates. In this method, you have to manually add a TXT
record in your DNS.
In this method, the certificate authority gives you DNS entries that you need to add to verify ownership of the domain.
$ ee site create example.com --ssl=le --wildcard
Configuring project.
Creating site example.com.
Copying configuration files.
Starting site's services.
Success: Configuration files copied.
Checking and verifying site-up status. This may take some time.
Add the following TXT record to your DNS zone
Domain: _acme-challenge.example.com.
TXT value: xxxxxxxxx
Wait for the propagation before moving to the next step
Tips: Use the following command to check the propagation
host -t TXT _acme-challenge.example.com.
Add the following TXT record to your DNS zone
Domain: _acme-challenge.example.com.
TXT value: yyyyyyyyy
Wait for the propagation before moving to the next step
Tips: Use the following command to check the propagation
host -t TXT _acme-challenge.example.com.
IMPORTANT: Run `ee site ssl example.com` once the DNS changes have propagated to complete the certification generation and installation.
Starting site's services.
After running the above command, in this case, you need to add the following entries in your DNS
Key | Value |
_acme-challenge.example.com | xxxxxxxxx |
_acme-challenge.example.com | yyyyyyyyy |
After adding the entries, run the following command to verify that the changes have been propagated in the DNS –
$ host -t TXT _acme-challenge.easyengine.io
_acme-challenge.example.com descriptive text "jfKbXNIhMB5agYNfYQqwZdFJmaHv1j-c_-wBk3cI7qg"
_acme-challenge.example.com descriptive text "bIcFm-nUWaOGjtqDiTFMvDz2aFInLyro5bN9E2VvWpI"
Finally run following to verify the challenge and get the certificate from Let’s Encrypt –
ee site ssl example.com
DNS Challenge on Non-wildcard Site
If there’s a site which isn’t wildcard but you still need DNS challenge on it, then you can do so by setting preferred_dns_challenge
option in config file to dns
:
ee config set preferred_ssl_challenge dns
It will ensure all sites created will use DNS challenge instead of HTTP.
To restore the default behaviour, use:
ee config set preferred_ssl_challenge http
CloudFlare Integration 🌥️
If your site is on CloudFlare, you don’t have to manually add TXT records in DNS anymore, while creating the site with SSL. EasyEngine will add the TXT records for you and even clean them once they’re no longer needed.
To enable CloudFlare integration, you need to provide CloudFlare account email and its API key in the EasyEngine config using the commands below.
ee config set le-mail info@example.com
ee config set cloudflare-api-key <cf-api-key>
For the time being, EasyEngine requires the Let’s Encrypt email to be the same as the Cloudflare email. Therefore, you will need to pass the Cloudflare email value to the le-mail config key.
⚠️ Note: The site needs to be added into your CloudFlare account for this feature to work. The sites must be using CloudFlare DNS, other CloudFlare services are optional.
Inheriting Certs
Let’s say there’s an existing site example.com
with wildcard certificate and you want to create abc.example.com
which will reuse the certificate of example.com
instead of issuing a new one. Then you can do it with --ssl=inherit
flag:
ee site create abc.example.com --ssl=inherit
Self Signed Certificates
You can generate a self signed certificate while creating a site by using --ssl=self
flag. It is quite useful for creating https sites on local machine.
ee site create example.com --ssl=self
EasyEngine adds the self signed certificate’s Certificate Authority(CA) to your OS trust store so the sites created with self signed certificate do not display warnings in browser on that machine.
TLS Ciphers
We use ciphers from Mozilla’s Intermediate profile by default. You can use different set of ciphers by choosing a different ssl policy. You can use other ssl policies by updating ssl-policy
in EasyEngine’s config:
ee config set ssl-policy Mozilla-Intermediate
Policies that you can use are – Mozilla-Old, Mozilla-Intermediate, Mozilla-Modern, AWS-TLS-1-2-2017-01, AWS-TLS-1-1-2017-01, AWS-2016-08, AWS-2015-05, AWS-2015-03 and AWS-2015-02
. You can have a look at our code to see which ciphers and protocols will be used for which policy.
You can read more about how SSL is handled in nginx-proxy here.
SSL renewal CRON
A cronjob is required to setup SSL renewal, add a cron job similar to the one below. It will ensure the proper renewal of certificates when they are due. Please note that the certificate of sites that have wildcard certificate or use DNS challenge will be renewed via cron only if Cloudflare API key has been setup (which ensures automated txt record creation and cleanup).
As EasyEngine being executed from cron daemon, at times it does not get the PATH
to docker-compose
due to which the SSL renewal do not go through. To maintain proper SSL renewals, please add PATH
variable inside the crontab to get a cronjob like below:
# Add value of PATH from your system inside crontab. PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 0 0 * * * /usr/local/bin/ee site ssl-renew --all >> /opt/easyengine/logs/cron.log 2>&1