# Replace the HTTPS certificate

> Understand the automatic self-signed certificate, generate your own or upload an RSA certificate and key, plan hostname coverage and renewal, remove a certificate, and handle HA-managed ones.

Buttons creates its own self-signed certificate automatically so HTTPS works out of the box, without waiting on anything external. Replacing it with a certificate your organization already trusts removes the browser warning users see on a self-signed certificate, and lets you follow whatever certificate practice you already use. Before you begin Access to Settings → Certificates . To upload a certificate: the server certificate and its matching private key, both RSA and both as PEM text files. No other key type or file format is currently supported (see Prepare the certificate files ). If your certificate has a chain, the intermediate certificates to include. Awareness that installing, generating, or removing a certificate restarts the web service, briefly interrupting access. Understand what's installed today Settings → Certificates shows the installed certificate's Common Name and the date it was uploaded, under Installed certificate . It doesn't show the full subject, the Subject Alternative Names, or the expiry date. Select Download to save a copy of the certificate and inspect those details with your usual tools. Buttons doesn't warn you as a certificate approaches expiry: track renewal dates yourself, the same way you would for any other certificate you manage. The automatic certificate When no certificate of your own is installed, Buttons generates one at startup for the hostname set in the app's Environment Settings (or with -publicHostname on a headless install). It covers that hostname and, when one is known, the machine's IP address, uses a 4096-bit RSA key, and is valid for 15 years. If the hostname changes, Buttons generates a new automatic certificate at the next startup. A certificate you upload or generate yourself is never replaced automatically. Plan the certificate's hostname coverage Make sure the certificate covers every hostname and IP address people will use to reach this Buttons instance, as Subject Alternative Names (SANs). Current browsers check only the SAN list and ignore the Common Name, so a certificate whose name appears only in the Common Name still shows a warning. Buttons doesn't check hostname coverage for you: it accepts a certificate that doesn't match how you're actually reaching the server, so a successful upload doesn't by itself confirm your hostname planning was right. Plan for renewal Certificates from public certificate authorities are valid for at most 398 days, and that limit is getting shorter, so renewing is a regular task rather than a one-off. Note the expiry date when you install a certificate and plan the next replacement ahead of it. Apple devices also refuse TLS certificates from a private certificate authority that are valid for more than 825 days. If macOS or iOS clients connect to Buttons with a certificate from your own internal authority, keep its validity within that limit. Generate a self-signed certificate A self-signed certificate is useful for local or internal HTTPS when you don't have a certificate authority to hand. Browsers still warn about it unless you install it as trusted on each client; for more than a few clients, an internal certificate authority is usually easier to manage. Open Settings → Certificates . Next to Generate self-signed certificate , select Generate . Fill in the form: Common name : the hostname people use to reach Buttons. The certificate covers only this name, so use a hostname rather than an IP address. Organization , Locality , State , and Two letter country code : required. Organizational unit : optional. Validity period (days) : from 1 to 36,500, default 365. RSA Key size : 2048, 4096, or 8192 bits, default 4096. Select Generate and restart . The new certificate replaces the installed one and isn't replaced automatically afterwards, even if the hostname changes. Prepare the certificate files Buttons reads the certificate and key as PEM text: the files that start with lines such as -----BEGIN CERTIFICATE----- and -----BEGIN PRIVATE KEY----- (or -----BEGIN RSA PRIVATE KEY----- ). Binary formats such as DER, .pfx , or .p12 aren't accepted. Convert them to PEM first. Password-protected private keys can't be read. Remove the password from a copy of the key before uploading, and delete that copy afterwards. Certificate chain : put the server certificate first in the certificate file, followed by any intermediate certificates, all in the same file. Buttons serves the whole file, so clients receive the chain. Upload a certificate Open Settings → Certificates . Next to Upload certificate files , select Upload . Under Certificate , choose the certificate file, then under Private key , choose the key file. The private key can't be chosen until a certificate is set. Select Save and restart . Buttons checks that the private key matches the certificate before saving, and rejects a key that isn't RSA. It doesn't check the certificate's chain of trust, its expiry, or whether its names match this server's hostname: confirm those yourself before uploading. Handle the private key securely An uploaded private key is stored as it is in Buttons' database, not through the separate Secrets encryption used for connection credentials. Treat the certificate files with the same care you'd give any private key: transfer them securely, and don't leave copies lying around after the upload. Replace or remove a certificate There's no undo for a certificate change: installing a certificate removes the previous one entirely, and Buttons doesn't keep a history. Before replacing a certificate, keep your own copy of the current certificate and key. To go back to a self-signed certificate, generate one . To remove the installed certificate, select Remove next to it and confirm. This turns HTTPS off: users have to connect over HTTP until a certificate is installed again. The next time Buttons starts, it creates a new automatic certificate , which turns HTTPS back on. When HTTPS is handled outside Buttons If HTTPS is terminated somewhere else, for example by a reverse proxy, the server can be started with the DISABLE_HTTPS_SUPPORT environment variable set to 1 or true . Settings → Certificates then shows "HTTPS is managed externally" and hides the generate and upload options. Certificates in a High Availability deployment A High Availability deployment uses the same certificate on all three machines. Generate, upload, replace or remove it from this page in the same way as on a single machine. If you get stuck What you see What to try The upload says the certificate and private key don't match. Confirm you're uploading the private key that was generated together with this certificate, not a key from another certificate. The upload says only RSA keys are supported. The certificate uses another key type, such as ECDSA. Request or generate an RSA certificate instead. The certificate or key file won't load. Confirm both are PEM text files and that the key isn't password-protected. Users still see a certificate warning after uploading. Confirm the certificate's Subject Alternative Names cover the hostname or address being used, and that the intermediate certificates follow the server certificate in the same file. Users see a warning with a self-signed certificate. That's expected unless the certificate is installed as trusted on each client. Use a certificate from a trusted authority to avoid it. You need to know when the current certificate expires. Select Download and check the certificate's details, or your certificate authority's records. HTTPS stopped working after you removed the certificate. Install a certificate, or restart Buttons so it creates a new automatic certificate. Where to go next Secure a Buttons deployment , for TLS as part of a broader security baseline. Startup configuration reference , for the hostname and HTTPS port settings. Deploy Buttons with High Availability , for what an HA deployment needs and how it's installed.