Buttons generates its own self-signed certificate automatically so HTTPS works out of the box, without waiting on anything external. Replacing it with a certificate from a trusted authority can help you remove the browser warning users see on a self-signed certificate, and match whatever certificate practice your organization already uses.
Before you begin#
- Access to Settings → Certificates.
- A server certificate and matching private key, both RSA: no other key type is currently supported.
- If your certificate has a chain, the intermediate certificates to include.
- Awareness that saving a new certificate restarts the web service, briefly interrupting HTTPS access.
Understand what's installed today#
Settings → Certificates shows the currently installed certificate's Common Name and the date it was uploaded, not its full subject, SAN list, or expiry. If the CN doesn't match the hostname you expect, or you're not sure when it was issued, that's the extent of what's shown here; check the certificate file itself for full details if you need them.
Buttons doesn't currently warn you as a certificate approaches expiry: track renewal dates yourself, the same way you would for any other certificate you manage outside Buttons.
Plan the certificate's hostname coverage#
Buttons' own automatically generated certificate covers the single hostname it detects at generation time. When you bring your own certificate, make sure its Common Name, and any Subject Alternative Names it needs, actually covers every hostname or address people will use to reach this Buttons instance. Buttons doesn't check this for you: it accepts a certificate whose CN doesn't match how you're actually reaching the server, so a working upload doesn't by itself confirm your hostname planning was correct.
Upload a certificate#
- Open Settings → Certificates.
- Select Upload certificate files.
- Provide the Server certificate file, then the Private key file. The private key field stays disabled until a certificate is selected.
- If your certificate has a chain, include the intermediate certificates in the same upload as instructed in the dialog.
- Select Save and restart.
Buttons checks that the private key you provided actually matches the certificate's public key before saving, and rejects a non-RSA key outright. It does not check the certificate's chain of trust, its expiry, or whether its CN or SAN entries match this server's actual hostname: confirm those yourself before uploading.
Saving restarts the web service to apply the new certificate. Plan the change for a moment when a brief HTTPS interruption is acceptable.
Handle the private key securely#
An uploaded private key is stored directly, not through Buttons' separate Secrets encryption feature used for connection credentials. Treat the certificate files themselves with the same care you'd give any private key outside Buttons: transfer them securely, and don't leave copies lying around after the upload.
Roll back to a self-signed certificate#
There's no undo for a certificate change: replacing one certificate with another removes the previous one entirely. To return to an automatically generated certificate:
- Open Settings → Certificates.
- Select Generate self-signed certificate → Generate.
- Confirm: this also restarts the web service.
If you need to restore the exact certificate you replaced, you'll need your own saved copy of it; Buttons doesn't retain a history of previous certificates.
Certificates in a Kubernetes deployment#
When Buttons runs under Kubernetes, certificate management can be handed to the cluster instead, for example, through cert-manager. In that case, the page shows Certificate managed by Kubernetes, and manual upload, generation, and deletion are all unavailable from here; manage the certificate through your cluster's own tooling instead.
If you get stuck#
What you see | What to try |
|---|
The upload is rejected with a key/certificate mismatch. | Confirm you're uploading the private key that was actually generated alongside this certificate, not a key from a different certificate. |
The upload is rejected outright. | Confirm the private key is RSA: no other key type is currently accepted. |
Users still see a certificate warning after uploading. | Confirm the certificate's CN and SAN entries actually cover the hostname or address being used to reach Buttons, and that any required intermediate certificates were included. |
You need to know when the current certificate expires. | Buttons doesn't display this: check the certificate file itself, or your certificate authority's own records. |
The page shows Certificate managed by Kubernetes and won't let you make changes. | Manage the certificate through your cluster's own certificate tooling instead of this page. |
Where to go next#
