SSL

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 site example.com with wildcard certificate and you want to create abc.example.com which will inherit (reuse) the certificate of example.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

KeyValue
_acme-challenge.example.comxxxxxxxxx
_acme-challenge.example.comyyyyyyyyy

 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 [email protected]
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

Subpages