Skip to content
Flui Documentation

TLS and certificates

Every Flui cluster runs on HTTPS from the first minute. There is no separate step to set up certificate issuance: certificates come with the same operation that creates an endpoint, and they renew themselves.

This chapter covers which authority signs the certificates, which shape of certificate the cluster asks for, and what it does when it cannot get the shape it wanted.

The three issuance modes

There are two authorities underneath: Let’s Encrypt production and Let’s Encrypt staging. Three modes combine them:

  • Production. Certificates come from Let’s Encrypt production: real, browser-trusted, valid for every client out of the box. This is the mode for anything real users reach, and it is the default.
  • Staging. Certificates come from Let’s Encrypt staging. The issuance flow is the same, but the signing authority is one browsers do not trust, so they show a warning. In exchange its limits are loose enough that you can re-issue as often as you like while iterating.
  • Preflight. Start in staging, then move. A staging certificate is issued first, which quickly confirms that the whole challenge chain works end to end. Once it is valid, the endpoint offers you the switch to production. On a single endpoint you make the promotion yourself; the DNS setup wizard makes it for you once every staging certificate is valid. Use this path when you are testing a new domain setup and tripping a production limit would be costly.

The mode applies to the whole installation, not to one application. Set it with flui config set certificateMode production|staging|preflight; it is written into the dashboard’s configuration. A single zone can still be pinned to one authority when it is attached to a cluster, with flui dns zone assign <zone> --certificate-provider lets_encrypt_staging.

The rate-limit background is in Creating a cluster from zero. In short: production is the default for real environments, staging suits a tight loop of creating and destroying clusters, and preflight sits between them. A cluster that starts in staging can be promoted to production later. The other direction is rarely useful and no surface offers it.

The three certificate shapes

Within either authority, the cluster does not always ask for the same kind of certificate. The shape depends on what the cluster knows about DNS.

One wildcard for the cluster the ordinary case DNS challenge, on a zone at aprovider whose DNS Flui drives One per endpoint the fallback HTTP challenge, works anywhere,one issuance per endpoint One listing several names asked for on purpose up to twenty names,fixed when it is created *.production.example.com shop.production.example.com api.production.example.com next-app.production.example.com shop.example.com blog.example.com docs.example.com one certificate, three names api.example.com dashboard.example.com auth.example.com new.example.com not on the list: refused Which one an endpoint gets 1 On a multi-name certificate? Use it 2 Wildcard ready? Use it 3 Otherwise: one of its own
The three shapes a certificate can take. The wildcard is the usual one: an application deployed tomorrow is already covered.

One wildcard for the cluster

This is the usual case. Attach a DNS zone to a cluster with flui dns zone assign <zone> and you get it without asking; --no-wildcard-certificate declines it.

One certificate covers every name one level under the cluster’s subdomain. Applications that do not exist yet are already covered, so deploying one needs no new issuance. The certificate is issued once, held in one place on the cluster, and copied to wherever an application needs it.

The cluster proves it controls the zone by briefly writing a record on it (a DNS-01 challenge). That needs a zone on a provider whose DNS Flui can drive; see which providers. On any other DNS provider the wildcard is not available, and the cluster falls back to the shape below.

A wildcard is exactly one label deep. A certificate for *.apps.example.com answers for shop.apps.example.com, but not for eu.shop.apps.example.com and not for the bare apps.example.com. Names a level deeper get a wildcard of their own over their own parent, and a bare domain gets its own certificate. So one cluster can hold more than one wildcard, and that is normal.

One certificate per endpoint

A cluster falls back to this shape when it has no DNS zone and addresses applications by IP, when the zone lives on a provider Flui cannot write to, when the wildcard was declined, or when a single endpoint asks for the HTTP challenge by name.

Here the cluster proves it controls each name by serving a small challenge file from that application’s own address (an HTTP-01 challenge). It needs no DNS integration, so it works everywhere.

The cost is that every new endpoint is a fresh issuance. On a cluster where applications come and go, the count adds up against the authority’s limits. That is why the wildcard is the default rather than an option you turn on.

One certificate listing several names

A single certificate can instead list up to twenty hostnames. Proof of control is per name, with the same HTTP-01 challenge as above, or DNS-01 when every name on it sits under one zone Flui can drive.

You only get this shape by asking for it: the certificate is created first, and endpoints are attached to it as they are created. Flui uses it itself. When the dashboard’s DNS setup configures the platform without a wildcard, its three addresses (the API, the dashboard and the identity provider) go into one certificate, so the setup pays for one challenge instead of three. It suits a small, fixed set of names known up front and nothing else, because the list is fixed when the certificate is created. An endpoint whose hostname is not on the list is refused, and a different set of names means a different certificate.

Which shape an endpoint gets

The cluster decides per endpoint, in this order:

  1. If the endpoint was attached to a multi-name certificate, that one is used.
  2. Otherwise the wildcard, if the wildcard is not switched off, the endpoint asked for a certificate at all, its hostname falls under a zone attached to the cluster, and the cluster’s wildcard issuance is ready.
  3. Otherwise a certificate of its own.

A wildcard that cannot be used is never an error. Each failing condition means the endpoint gets its own certificate, and the deploy carries on. When both the production and the staging wildcard issuance are ready on a cluster, production wins.

The wildcard record and the wildcard certificate

A cluster serves all of its applications from one wildcard DNS record and covers them with one wildcard certificate. These are separate, and you can have one without the other.

flui dns wildcard status prints both, per zone: a dns line for the record and a certificate line saying whether the certificate covers everything or applications get one each. If the record is missing, flui dns wildcard publish creates it. The difference you notice is propagation. With the record in place, a newly deployed application answers straight away. Without it, each new name publishes on its own and waits about a minute for resolvers to see it.

If a wildcard record already exists on the zone and points somewhere other than this cluster, Flui leaves it alone and applications keep publishing their own names, rather than overwriting someone else’s record.

Renewal

In every mode and every shape, certificates renew themselves ahead of expiry, with no action from anyone.

Renewal follows the issuance path: a wildcard renews through the DNS challenge against its zone, per-endpoint certificates through the HTTP challenge served from the cluster, and a multi-name certificate through whichever challenge it was issued with. A renewed wildcard reaches every application it covers on its own. Nothing is redeployed or reconciled by hand.

An application’s URL is published only once the endpoint is settled and its certificate is no longer on its way. An address is reachable minutes before a certificate is signed, and the link Flui gives you is an https:// one. Showing it early would send a visitor to a browser warning.

The link is withheld only while a certificate is pending or being issued, and that window closes on its own; a refresh resolves it. A certificate that failed or expired does not hide the application. The link appears and the browser says what is wrong, which tells you more.

Where this chapter goes from here