Skip to content

Let's Encrypt certificates

Wondering how free SSL certificates get from Let's Encrypt onto your domains?

For a project, the short answer is the 'SSL' panel on the project page: click 'View', then 'Request Let's Encrypt' next to a domain that doesn't have a certificate yet. Renewal is automatic from then on.

This article explains what happens underneath that button: the three objects involved, being the certificate manager, the certificate and the domain router, and how they fit together. If a certificate hasn't appeared, skip to What goes wrong.

For paid (commercial) SSL certificates, see Paid SSL certificates.

The three pieces behind that button

  1. Certificate manager — issues certificates from a provider, here Let's Encrypt. You give it a list of domains to cover.
  2. Certificate — the actual PEM certificate, chain and key, produced by the manager.
  3. Domain router — the per-domain object that decides what is served. It has a slot for one certificate and presents it to visitors over TLS.

The manager owns issuance and renewal, the certificate is what gets attached, the router is where it is presented.

Certificate manager

Two fields:

  • 'Provider' — 'Let's Encrypt' for free certificates.
  • 'Common Names' — the domains the certificate should cover, picked from existing domain-router domains on the cluster.

One manager can cover several domains, all on a single SAN certificate. Re-using one manager for a project's primary domain plus its www. and other aliases gives you one certificate, one renewal, and one attachment per router.

A domain can be part of only one certificate manager at a time. Domains already covered by an existing manager do not appear in the dropdown when you create a new one.

Certificate

You do not create it directly for a Let's Encrypt manager. The manager produces it the first time it runs against the provider, and again on every renewal.

The manager's detail page has a 'Request certificate' action that triggers issuance on demand — useful when you have just added a domain to the manager and do not want to wait for the next scheduled run.

The same 'Certificates' object model also covers paid certificates, where you paste in your own PEMs. Ignore that path for Let's Encrypt.

Attaching to the domain router

Each domain router has a 'Certificate' tile. Once the manager has produced a certificate, it is attached to the domain routers whose domains are in the manager's 'Common Names'.

You normally never touch that tile. It matters only when:

  • You are attaching a paid certificate, with no manager involved.
  • You are switching between two certificates that cover the same domain, for example migrating from a paid certificate to Let's Encrypt.

Renewal

Let's Encrypt certificates are valid for 90 days. Cyberfusion renews them automatically: the manager re-runs against the provider well before expiry, and the new certificate replaces the old one with no downtime.

As long as the manager exists and its 'Common Names' still resolve to domain routers on the cluster, renewal happens on its own.

What goes wrong, and how to spot it

The most common cause of a failed issuance: the domain does not point at Cyberfusion yet.

Let's Encrypt validates ownership via HTTP-01, which means fetching a file at /.well-known/acme-challenge/.... If the domain's A or AAAA records do not point at the cluster's nodes, the validation cannot reach the file and the request fails.

When a manager shows 'No Certificate' for a domain you just pointed at the cluster:

  1. Confirm DNS points at Cyberfusion, and that the domain is assigned to a server that can answer for it.
  2. Click 'Request certificate' on the manager to trigger a fresh attempt.
  3. Still failing → the 'View Request Detail' link on the manager's last run shows the task collection with the underlying error.

How to group domains across managers

  • One manager per client project — the primary domain plus every www., m. and country-TLD alias on a single SAN certificate. One renewal, one place to look when something breaks.
  • One manager per customer domain for white-labelled portals and custom hostnames. Onboarding a new customer's domain is then a DNS change plus a manager.
  • Keep admin and staging domains on a separate manager from the public storefront. If the storefront certificate's private key ever leaks, for example through a server compromise, the admin and staging domains are not on that same certificate.
  • Group hostnames by lifecycle — the ones added and removed together — rather than packing dozens of unrelated domains into one manager. If a renewal then fails, because of a Let's Encrypt rate limit or a stale DNS record, only the domains in that manager lose their valid certificate. Every other domain on the cluster keeps working.