Cosmos Cloud LogoCosmos Cloud

Domains and HTTPS

Every URL you create in Cosmos has a hostname, such as photos.example.com, and every hostname needs two things to work from the outside: an HTTPS certificate, and a DNS record pointing at your server. The Domains page is where Cosmos manages both for you.

A domain is a name such as example.com with its own HTTPS and DynDNS setup. Every hostname uses the settings of its domain: photos.example.com, cloud.example.com and example.com itself all follow the entry for example.com. Give a domain a DNS provider, and Cosmos issues a wildcard certificate for it and keeps its DNS records pointed at the right servers, so a new URL works the moment you create it.

Where to find it

Go to Management > Configuration and open the Domains tab. The page has two parts:

  • Domains: the list of your domains, with a New domain button. Each row is saved on its own, from its dialog.
  • HTTPS on this server: the few things that belong to the server rather than to a domain. This card is part of the settings form, so remember to press Save at the bottom of the page after changing it.

The list has a row per domain, with:

  • Domain: the name. An auto chip marks an automatic domain (see below).
  • HTTPS: how its hostnames are served: Let's Encrypt (DNS: cloudflare), Let's Encrypt (HTTP challenge), Locally self-sign certificates, I have my own certificates or Use HTTP Only.
  • Certificate: the certificate its hostnames are served with, and when it expires. See the certificate column.
  • DynDNS: whether Cosmos manages its DNS records: off, on, on + wildcard, or error. Hover the chip to see the records and when they were last checked.
  • Hostnames: how many hostnames currently use this domain. Hover to list them. In a cluster, this counts the hostnames of every server.

Click a row to open its settings, or use the pencil. The bin deletes the domain.

Automatic domains

You do not have to create anything for HTTPS to work. Any hostname in use (your Cosmos hostname, the hostname of each URL) that no domain of yours covers is listed as an automatic domain, marked with the auto chip. An automatic domain is the hostname itself, and it has no DynDNS: you create its DNS record at your registrar. Its HTTPS needs no setting either. A public name such as photos.example.com gets a Let's Encrypt certificate, which each server obtains for its own hostnames (HTTP challenge). A name Let's Encrypt cannot certify, such as nas.local or an IP address, is served with a self-signed certificate.

If a certificate cannot be obtained, Cosmos keeps serving the previous one, or its self-signed certificate when there is none, and sends you a notification. Nothing else changes: it asks again the next time it starts.

Opening an automatic domain shows its settings; saving it gives it settings of its own, under that exact hostname. Most of the time you want the whole domain instead: use New domain and enter example.com, and every automatic domain under it disappears from the list, absorbed by the new entry.

Automatic domains are never stored: they come and go with your URLs.

HTTPS on this server

How a hostname is served is always decided by its domain. The HTTPS on this server card holds the rest:

  • HTTPS: Enabled: each domain decides its certificate, or Use HTTP Only for a server that should not serve HTTPS at all, for example behind another reverse proxy that already does.
  • Address to advertise in DNS records: the address the DNS records managed by Cosmos point at for this server. See the address to advertise.
  • Email address for Let's Encrypt: the contact given to Let's Encrypt with every certificate request. It is optional, and shared by all the servers of a cluster.
  • Force HTTPS Certificate Renewal On Next Save: tick it and save to re-issue your certificates right away.

The mode you chose during the first setup is turned into domains for you: a self-signed setup or your own certificate becomes a domain with that mode, which you can edit like any other.

Adding a domain

Click New domain. The dialog asks for:

  • Domain: the name, such as example.com. All the hostnames under it follow this entry. It can also be a sub-domain, such as lab.example.com: the longest matching domain wins, so hostnames under lab.example.com follow that entry and the rest of example.com follows its own.
  • HTTPS Certificates: how the hostnames of the domain are served.
    • Automatically generate certificates using Let's Encrypt (Recommended).
    • Locally self-sign certificates, for a domain only reachable on your network.
    • I have my own certificates: paste the certificate and its private key, in PEM format. The key is never shown again; when you edit the domain later, leave it empty to keep the current one.
    • Use HTTP Only: the hostnames of the domain are served over plain HTTP, even on a server that serves HTTPS for its other domains.
  • DNS provider: the service hosting the DNS of your domain, if you want Cosmos to use it. See below.

Press Save. The domain is saved immediately, nothing else to click.

Picking a DNS provider

The DNS provider list has two groups. The providers listed first, marked certificates + DynDNS, can do both: get the certificates of the domain through the DNS challenge, and manage its DNS records. They are cloudflare, desec, digitalocean, duckdns, gandiv5, hetzner, namecheap, ovh, porkbun and route53. The providers under Certificates only (no DynDNS) are the other Let's Encrypt DNS providers: Cosmos uses them for the certificates of the domain, and you keep managing the records yourself.

Once you pick a provider, a <provider> setup section appears with its credentials. Fill only what your provider needs and leave the rest blank; the link at the top of the section goes to the provider's documentation. You do not need to set environment variables: the tokens go in the form.

A note for Cloudflare: use an API token (CF_DNS_API_TOKEN) with DNS edit permission on the zone of the domain (example.com for a domain such as lab.example.com), not the global API key. Certificates work with either, but DynDNS needs a token.

With a provider, a few options appear:

  • Use a wildcard certificate (*.example.com): one certificate for example.com and every *.example.com, issued through the DNS challenge. New hostnames are covered without a new certificate. Hostnames deeper than one level, such as a.lab.example.com, are added to the certificate as they appear. Without this option, the certificate lists exactly the hostnames in use, and is re-issued when a new one appears.
  • Manage the DNS records of this domain (DynDNS): let Cosmos write the DNS records of your hostnames. See managing DNS records.

An Advanced section holds the DNS challenge tuning: Custom DNS Resolvers, Disable Propagation Checks and Propagation Wait (seconds). Leave them alone unless your network redirects DNS requests, which can make the challenge fail to see its own record.

Without a DNS provider

Leave DNS provider on DISABLE and Cosmos works like a classic reverse proxy: each server gets the certificates of the domain by itself, through the HTTP challenge, and DNS records stay manual.

For this to work, each hostname must point at your server before you create its URL, and the server must be reachable from the internet on port 80 or 443. If you use Cloudflare, the record must not be proxied (grey cloud, not orange). A wildcard certificate is not possible without a DNS provider.

Managing DNS records

Tick Manage the DNS records of this domain (DynDNS) and Cosmos takes care of the records of every hostname it serves under the domain, so you never touch your registrar again. It is on by default for a new domain with a capable provider.

Concretely, for every hostname in use under the domain, Cosmos writes an A record with the address of the server serving it. When your public IP changes, the records follow within a minute or so. When you delete a URL, its record goes away. Records Cosmos did not create are left alone, except at the hostnames you declare: creating a URL on photos.example.com is your consent for Cosmos to take that name over, and an existing record or CNAME there is replaced.

The domain does not have to be a DNS zone of its own at your provider. For a domain such as lab.example.com, Cosmos finds the zone it lives in, here example.com, and writes its records there, as photos.lab and so on. Several domains can share one zone, and so can several Cosmos servers or clusters: each one only ever removes the records it wrote itself.

Tick *Point .example.com at this server or cluster to also write a wildcard record: a brand new hostname then resolves immediately, with no record to create and no propagation to wait for. It is on by default. Hostnames the wildcard already answers get no record of their own.

Records are written with a short TTL (60 seconds, or the minimum your provider accepts), and Cosmos re-reads the records of the domain every ten minutes to notice changes made elsewhere.

The DynDNS column of the list shows the result: on or on + wildcard when everything is in place, with the records and the time of the last check in the tooltip, or error with the provider's message when a write failed. Cosmos tries again by itself, a minute later, then five; after three failures in a row it sends you a notification and tries once a day. Saving the domain, for example with a corrected token, makes it try again right away.

The address to advertise

By default, the records point at the public IP of the server, as seen from the internet: Public IP, detected, with the address found next to it. This is what you want for a server at home behind a router, or on a VPS.

To publish a server on your local network instead, pick one of its network interfaces in Address to advertise in DNS records: the records then carry the address of that interface, such as 192.168.1.20. This gives you real hostnames, with real certificates, for a server that is never exposed to the internet.

The setting belongs to the HTTPS on this server card, and is per server: in a cluster, each server advertises its own address. A hostname is never published with a mix of public and private addresses: if both exist, only the public ones are written.

The certificate column

The Certificate column tells you what each domain's hostnames are served with:

  • Certificate of example.com · expires <date>: the domain's own certificate, issued through its DNS provider. Hover to see the names it covers. It is renewed automatically before it expires.
  • pending: the domain's certificate is being issued. Give it a minute; with a wildcard certificate, the DNS challenge waits for the record to propagate.
  • not covered: a hostname of the domain is not in the certificate served yet, usually because it was just added. The certificate is re-issued automatically.
  • This server's Let's Encrypt certificate: the hostnames are in the certificate this server gets by itself, through the HTTP challenge (automatic domains, and domains without a DNS provider).
  • Self-signed certificate, Provided certificate, HTTPS disabled: the corresponding HTTPS mode. A provided certificate shows its own expiry date, and not covered when it does not list a hostname of the domain.

The same information appears on each URL: open a URL and the Domain & certificate block of its overview shows the domain it belongs to, whether DynDNS is on, and the certificate serving it.

Deleting a domain

Use the bin at the end of the row, and confirm. Its hostnames become automatic domains again (or follow a wider domain of yours, if one covers them), and Cosmos stops managing their DNS records. The records already written stay as they are at your provider, so nothing breaks right away.

Automatic domains cannot be deleted: they exist as long as a URL uses their hostname.

In a Constellation cluster

With several servers connected through Constellation, your domains are shared by the whole cluster: create or edit one on any server, and every server knows about it.

  • One certificate per domain. The certificate of a domain is issued once, by the cluster leader, and shared with every server. A certificate you provide for a domain is shared the same way. Each server presents it for the hostnames it serves, so a URL moved or load-balanced to another server keeps a valid certificate without any new issuance.
  • Records are written by the cluster leader. The leader sees every hostname of the cluster and which servers answer for it. A URL served by one server points at that server. A URL behind the load balancers (a deployment or a tunneled URL) points at the load balancers, and so does the wildcard record (or at the first manager, when no load balancer is enabled). When a server goes down, its address is withdrawn from the shared records after a short grace period, never leaving a hostname without an address. On the other servers, the DynDNS tooltip simply says Records are written by the cluster leader.
  • New servers get a hostname. A server that joins the cluster by uploading its constellation file during the first setup is given the hostname <device name>.<cluster domain> automatically, for example nas-2.example.com for a device named nas-2. The cluster domain is the domain of the server that generated the file. You can change the hostname in the setup screen before joining. With the wildcard record and wildcard certificate on, the new server is reachable over HTTPS as soon as it has joined.