Certificates and TLS

TLS encrypts connections and checks the server’s identity. A certificate authority (CA) signs server certificates. Clients must trust that authority before accepting its certificates.

Choose the trust model

	TLS at the leader	TLS at a proxy
Certificate served by	Smeltr	Reverse proxy or ingress
Setting	`leader.tls.enabled = true`	`leader.tls.enabled = false`; keep upstream private
Worker trust	Enrollment codes establish trust in the leader CA	System trust; configure private CA trust separately
Browser trust	Verify the CA fingerprint, then install its public certificate	Trust the proxy certificate; install a private CA if needed
Certificate changes	Admin → System → Certificates	At the proxy or ingress

Obtain and verify the public CA

For direct TLS the generated CA is at tls/ca.pem beneath leader.storage.data_dir. Obtain that public file through a trusted host-management channel for initial browser setup. Once signed in, Admin → System → Certificates also provides Download ca.pem and the authority fingerprint. Never distribute the CA private key.

openssl x509 -in /var/lib/smeltr/tls/ca.pem -noout -subject -dates -fingerprint -sha256

Verify the certificate names against the public URL and any worker-only DNS names. Add worker-only names with leader.tls.extra_san, restart for startup-setting changes, and check the certificate shown in the UI. Do not use a certificate warning bypass as the production setup procedure.

Choose where the certificate comes from

Admin → System → Certificates shows the authority and the certificate this leader serves, and a Source chooser with the one in force marked.

Source	Where the certificate comes from
Leader issued	The leader's own authority signs it. Issue a new one replaces it under the same authority.
Uploaded	An administrator pastes Certificate, Private key and Authority, all PEM, and selects Serve this certificate. The certificate must cover every name the page lists.
ACME	The leader orders it from a certificate authority and renews it. Order a certificate over ACME.

A new certificate from the same authority is served at once.

A new authority has to reach the workers first. The page shows the switch in progress while the leader hands the authority to them. The leader then serves the new certificate.

Cut over now serves it without waiting.
Abandon switch cancels the switch.

Browsers must be told to trust a new authority separately. If the page says the socket refused the reload, restart the leader. Replace proxy certificates at the proxy.

Order a certificate over ACME

Let's Encrypt and other certificate authorities issue certificates automatically over ACME. The authority checks that each name on the certificate reaches this leader, then issues it. The leader renews it on its own.

Before you start

Every name on the certificate points at this leader in DNS. A public authority such as Let's Encrypt won't issue for localhost or a private address.
With the TLS-ALPN-01 challenge, the default, port 443 on each name must reach this leader.
With the HTTP-01 challenge, port 80 on each name must reach this leader. The leader listens on leader.tls.acme_http_port only while it orders. That setting is 80 unless something forwards 80 to another port.
If this leader runs its own worker, set worker.leader.url to one of the certificate's names. That worker otherwise reaches the leader at localhost, and the leader refuses a certificate that doesn't cover it.

Order it

Under Source, choose ACME.
Pick the Directory: Let's Encrypt, or Other to type another authority's URL.
Check Names. They start as this leader's own names, without localhost.
Enter a Contact email. The authority sends notices about the account there.
Agree to the terms of service.
Select Get certificate. The first certificate from an authority is a switch, as described above.

Renewal

With ACME in force, the page shows when the certificate renews.

The leader renews when one-third of the certificate's life remains, e.g. 30 days of a 90-day certificate.
If an order fails, the page shows why, and the leader tries again every hour.
Save keeps your changes for the next renewal. Renew now orders a certificate right away.
A renewal under a new root is a switch, like the first order.

The leader stops renewing once you choose another source.

Advanced settings

Under Advanced:

Challenge picks TLS-ALPN-01 or HTTP-01.
Authority takes the root a private authority issues under, as PEM. It is needed only when the platform does not already trust that root.
EAB key ID and EAB HMAC key are for an authority that requires an account with it. It gives you both. The leader stores the HMAC key encrypted and never shows it again.

Rotate the authority

Back up the leader state and key; inventory offline workers and workers using explicit worker.leader.ca files.
Under Rotate authority, set Wait for the fleet and select Start rotation.
The leader publishes the incoming authority on heartbeats while it still signs under the old one. Ensure workers have received it. Explicit CA-file overrides require manual maintenance; update browser trust separately.
Only after verifying client readiness choose Cut over now, or allow the deadline to do so automatically. The leader retires the old authority and withdraws enrollment codes naming it.
Verify heartbeats and browser access after cutover. Before cutover, Abandon rotation cancels the pending rotation.