Issue an HTTPS certificate

A new hosting starts with a self-signed certificate, which is enough for nginx to start but not for browsers. Once its domain resolves to the server you issue a Let’s Encrypt certificate from the site’s Domains & SSL tab. It covers the primary domain and every alias, is validated over HTTP-01 and renews by itself.

Before you start

• Your account has the Manage TLS certificates permission.
• DNS for the domain and every alias points at the node that hosts the site, and port 80 reaches nginx. A Cloudflare proxy in front is fine.
• A real contact address is set. Open Settings, then HTTPS & previews, and check Let’s Encrypt contact. A placeholder such as an @example.com address makes issuance refuse to start. Enter the address in Contact email and click Save. A site can override it under ACME contact email on its own Domains & SSL tab.
• For a wildcard, use Issue a wildcard certificate instead.

Steps

1. Open Hostings, click the site and open the Domains & SSL tab.
2. Under Let’s Encrypt certificate, in step 1 · DNS check, click Check DNS. A green DNS OK line lists the A and AAAA records. A yellow DNS mismatch line shows what the domain resolves to and this node’s addresses.
3. In step 2 · Issue, click Issue HTTPS certificate and confirm Issue certificate.
4. Watch the job that opens under Background jobs. It finishes when the certificate is installed and nginx has reloaded.

Before it asks Let’s Encrypt, Hyperion re-renders the site’s vhost, runs the DNS check again and refuses to continue if the domain does not resolve here. The ticked box Skip the DNS pre-check overrides that; the attempt is then likely to fail, and each failed attempt counts against Let’s Encrypt’s rate limits. Skipping is recorded in the audit log.

An existing certificate is replaced in place, and the site keeps serving a trusted one throughout. Issue again whenever you add an alias.

Renewal

A daily check renews Let’s Encrypt certificates that are within 30 days of expiry, without a DNS check. Failures raise a notification each day until the certificate is renewed. Suspended sites are renewed too, without coming back online. To force a pass, open Certificates in the sidebar and click Renew all eligible. Only certificates inside the window are touched.

The Certificates page lists every certificate in the cluster, soonest expiry first, with counts for Expired, Critical < 7 d, Warning < 30 d and Healthy. When master-hosted sites still have self-signed certificates, Issue N certificate(s) issues them one after another as a background job.

Upload your own certificate

1. On the Domains & SSL tab, open Upload a custom certificate.
2. Paste Certificate (PEM) and Private key (PEM), and optionally CA bundle / intermediates.
3. Click Upload & install certificate.

Hyperion checks that the key matches the certificate and that the certificate covers the domain and every alias. It then installs it and turns off automatic renewal for this site, so renewal stays your job. The page shows “Custom certificate uploaded — auto-renewal disabled for it.”

Fall back to a self-signed certificate

Before you delete a certificate

Delete certificate removes the certificate files and the certificate record for this site. Visitors then see a browser security warning until you issue a new one, because the site is switched to a self-signed certificate. You do not need to delete a certificate to replace it. Issue a new one instead.

Nothing in the site’s files or database changes. Deleting removes the certificate and key files from the server, and Hyperion keeps no other copy of an uploaded certificate or key, so keep your own. To undo, issue a new certificate or upload one again.

1. Under Certificate, open Delete this certificate… (shown only for a trusted certificate).
2. Click Delete certificate and confirm.

Check that it worked

The Certificate card shows the pill trusted, the Issuer, the names under Covers, and Expires. The site’s page shows “Production HTTPS certificate issued.” In Hostings, the certificate column of the site is no longer self-signed.

openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -issuer -dates

Expected: an issuer naming Let’s Encrypt and a notAfter about 90 days away.

If it fails

• Certificate issuance failed: DNS pre-check failed for example.com: … The domain does not resolve to this node. Correct DNS, wait for it to propagate, and run Check DNS again.
• acme contact email “…” is invalid or a placeholder. Edit /etc/hyperion/agent.toml [acme] contact_email and restart hyperion-agent. Set a real address under Settings, HTTPS & previews, Let’s Encrypt contact.
• A proxied domain fails validation: if the SSL/TLS mode at Cloudflare is Full (strict) while the site still has the self-signed certificate, validation cannot succeed. Set the mode to Full, issue the certificate, then switch back to Full (strict). The site page shows a red Behind Cloudflare with a self-signed origin certificate. banner in this case.
• The certificate does not cover … banner: an alias was added after the last issuance. Issue again.
• An upload is refused: the key does not match the certificate, or the certificate does not cover the domain and all aliases. The red banner on the page shows the reason.