All chapters

Certificates and HTTPS

cpleks gets free certificates from Let's Encrypt, installs them, and renews them before they expire. You can also upload a certificate you bought, share one certificate between sites, and decide whether visitors are sent to HTTPS. All of it is on a site's Security tab.

Before you ask for a certificate

Let's Encrypt proves the name is yours by fetching a file from the site over plain HTTP. So the site's name must already point at this server, and port 80 must be reachable from the internet, including through any firewall in front of the machine. Ask too early and the attempt fails, and every failed attempt makes the next one wait longer.

A fresh install issues from Let's Encrypt STAGING. Staging certificates install and renew exactly like real ones, and no browser trusts them: visitors see a full-page warning. That default protects the weekly limits of the real service while your DNS is still being set up, and the panel says it on the certificate itself (STAGING · NOT TRUSTED). When your sites' names really resolve to this server, switch to production from SSH:

sudo touch /etc/cplex/acme/production-enabled
sudo chmod 0600 /etc/cplex/acme/production-enabled

Then press the certificate button on each site's Security tab once. The switch is per site: a site nobody reissues keeps renewing on staging. Only root can create that file, on purpose, so nothing reachable from the panel or the network can turn production on.

Get a certificate

  1. Open the site and its Security tab.
  2. In the Certificates card, which reads NOT STARTED before the first request, press Get a free certificate from Let's Encrypt. The card names every hostname the certificate will cover: the site's own name, its aliases and, when webmail is installed, webmail. under the site's name.
  3. The card shows IN PROGRESS while the request is with the certificate authority. It usually takes under a minute, and the page updates by itself.
  4. When it lands, the card shows who issued the certificate, which names it covers and when it expires, with the pill UP TO DATE.
The Certificates card on a site's Security tab, before any certificate: the site is reached over plain HTTP and a button offers a free certificate from Let's Encrypt.
The certificate card before the first request. The test machine is not reachable from the internet, so no certificate authority can reach it: the screenshots stop here.

If an attempt fails, the card says why in plain words, for example that the certificate authority could not fetch the proof file (the name does not resolve here, or port 80 is blocked), that the authority's weekly limit for these names is spent, or that this server could not reach the authority. Nothing is installed after a failure, and the site keeps serving what it had.

Renewal

Renewal is automatic. A background service checks every certificate regularly and renews the ones approaching expiry; nobody has to press anything. The card moves to RENEWAL DUE inside the renewal window and back to UP TO DATE afterwards.

On the Sites screen, the Certificates section lists what needs attention first: a certificate marked NOT RENEWING is still valid while every attempt to replace it fails, which looks fine until the day it expires. Show all lists every site under HTTPS, and Open takes you to that site's Security tab.

Upload your own certificate

  1. On the Security tab, press Upload.
  2. Choose the Certificate file (your certificate followed by any intermediates, in PEM format) and the Private key file. The certificate has to cover every name the site answers to, which the form lists; one that misses a name is refused rather than half-installed.
  3. Leave Stop cplex renewing this site's certificate ticked if this is the certificate you want served. Untick it and cpleks will replace it with a free Let's Encrypt certificate as it nears expiry.
  4. Press Install this certificate.

The private key is stored on this server, readable only by root. It is not written to the panel's database and never leaves the machine. With automatic certificates off, nothing replaces an uploaded certificate: upload the renewal before it expires, and the Certificates list reminds you.

The Upload a certificate form: a certificate file and a private key file in PEM format, the Stop cplex renewing this site's certificate box ticked, and an Install this certificate button.
Uploading a certificate you already have.

One certificate for several sites

Under Which certificate this site serves, a site can serve its own certificate or borrow another site's on the same plan. With Cover every subdomain a site asks for *.example.com as well, so every subdomain can borrow that one wildcard certificate instead of each getting its own. A wildcard is proved by a DNS record rather than a file, so it is offered only for a domain whose DNS this server answers (DNS).

How visitors arrive

  • How visitors reach this site has a switch that reads HTTP AND HTTPS while it is off. Switched on, it redirects: anyone typing the plain http:// address is sent to the secure one. Asked for before the site has a certificate, it waits (WAITING FOR A CERTIFICATE) and starts working by itself once the certificate arrives.
  • Tell browsers to remember (HSTS) makes browsers refuse plain HTTP for as long as you choose: an hour, a day or a year. The card says it cannot be undone for visitors who already received it, warns while the site has no certificate that switching it on would promise something the site cannot keep, and asks Tell browsers to remember? before anything is sent.
The How visitors reach this site card with its HTTP AND HTTPS switch, the Tell browsers to remember choices with their warning, and the Password protection section below.
Redirect to HTTPS, HSTS and password protection, per site. On the test machine the site has no certificate, and the card says so.

Password-protect a site or a folder

The same tab has Password protection. Press Ask for a password, choose The whole site (useful for a staging copy) or One directory, set the prompt, and add an account with a username and a password of at least 8 characters. The address Let's Encrypt uses to check a certificate is never protected, so renewal keeps working.

The panel's own certificate

The panel on port 8443 uses the self-signed certificate the installer made. Replacing it is done from SSH, with the commands the installer printed:

install -o cplex -g cplex -m 0644 fullchain.pem /etc/cplex/tls/cert.pem
install -o cplex -g cplex -m 0600 privkey.pem   /etc/cplex/tls/key.pem
systemctl restart cplex-api