Domains

A domain gives an application or a compose stack an HTTPS address. There are two kinds: a platform domain, a name under the platform's own domain, and your own domain, a hostname you control. A database takes no domain; the services in its project reach it by its internal address.

Each service with a domain lists it on its Domains section, and the Domains page in the sidebar lists every domain across the projects of the organization the console is in, with Add domain in its header.

Domains depend on how the platform is set up. When they are not available, the Domains page says so: "Domain connections are unavailable until the platform ingress is configured." or "Platform domains are not configured. You can connect your own domain when platform ingress is available."

When an application with no domain finishes a deployment as Done, Cloud gives it a platform domain: the service's name, cut to 32 characters, a hyphen, and six random letters and digits, under the platform's domain. The domain card on the Domains page shows the full address.

• An application that already has a domain, of either kind, is not given another.

• One whose domains were all removed is given a new address at its next Done deployment.

• A failed deployment, a database and a compose stack are given none.

The new address still goes through the checks below, so it answers over HTTPS a few checks after the deployment, not at the same moment.

To pick the name yourself, press Add domain, choose the Service, set Domain type to Platform domain, and type a Name. The platform's domain is shown after the field. Leave Name empty for a generated name. A name:

• is 3 to 63 lowercase letters, digits or hyphens, starting and ending with a letter or digit;

• has no hyphen pair in its third and fourth places, which is how internationalized names begin;

• is not one Cahaves keeps for itself, such as www, api, admin, login, billing, support, status or mail. Those are refused with "That name is kept for Cahaves. Choose another.";

• is not in use by anyone. A taken name is refused with "That name is already in use. Choose another." without saying whose it is.

The pencil button on a platform domain's card, labelled "Change name", gives it another name under the same rules. The old address stops answering at once, its certificate is dropped, and the domain is checked from the start under the new name. A name released by a rename or a removal is free for anyone straight away. Your own domains cannot be renamed: remove one and add the new hostname.

1. Add the hostname

   Press Add domain, choose the Service, keep Domain type on Your own domain, and enter the Hostname, such as www.example.com, without a scheme or path. "We will show a TXT record to verify ownership and the address records to add." A hostname under the platform's own domain is refused with "Use a generated platform domain for this hostname.", and one another domain has is refused with "This hostname is already in use."

2. Create the DNS records

   Press Show DNS records on the domain's card. The dialog lists each record to create at your DNS provider, with Type, Name and Value and a copy button on each name and value:

   • A TXT record named _cahaves. followed by your hostname, whose value starts with cahaves-verification=. It proves the hostname is yours.

   • One A record, or AAAA for an IPv6 address, for each address listed, all named with your hostname.

   Copy the values from the dialog rather than from anywhere else. If the dialog reads "The records appear here once the platform has worked out what to ask for.", close it and open it again after a minute.

3. Wait for HTTPS active

   Cloud checks DNS every five minutes. Once the records are right it routes the hostname to the service and waits for a certificate. The card reads HTTPS active once Cloud has seen a trusted certificate for the hostname being served, and the page refreshes itself while you wait.

The TXT value only proves control of the hostname. It is safe in public DNS and grants nothing else.

While a check is failing, the status chip carries the reason as a tooltip, and the DNS records dialog shows it above the records:

While a deployment of the service is in progress, Cloud postpones the domain's check by five minutes rather than counting it.

The round arrow button on a card that is not HTTPS active, labelled "Check again", restarts the checks.

Certificates are renewed for you. When a certificate is within seven days of expiry, Cloud checks the domain again once a day. While a renewal check fails and the old certificate is still valid, the domain stays HTTPS active and shows the reason. If the certificate expires without a verified renewal, the domain becomes HTTPS needs attention.

An application's domain sends traffic to the port in the service's Port setting at the moment the domain is added, or generated at the first Done deployment. Changing Port later does not move a domain that already exists. To route an existing domain to a new port:

• for your own domain, remove it and add it again, then create any record the new card asks for;

• for a generated platform domain, remove it and deploy: the next Done deployment generates a new address on the new port. To keep a name you chose, add it again as a platform domain with that Name.

Set Port before the first deploy and none of this is needed. Deploy a Docker image says why the port matters.

A compose stack's domain names a Compose service in the file and the Port that service listens on, and Cloud applies it through a deployment of the stack. Run a compose stack covers it.

Once a domain is HTTPS active, its card shows a preview of the page and Visit site opens it in a new tab. Before then the preview reads "Nothing to preview yet".

The Visit button in a service's header opens its first domain that is HTTPS active, your own before a platform one. Until there is one, it is greyed out and says why: "Deploy it again and its domain is generated", "Add a domain to visit this service", "Its domain is still being set up" or "Its domain needs attention".

The red bin button on a card, labelled "Remove domain", opens "Remove this domain?". Traffic to the hostname no longer reaches the service. For your own domain, remove its DNS records at your provider as well. For an application, a removed platform domain is replaced at its next Done deployment when it has no other domain.

• Domains cannot be added, renamed, checked or removed while the service has a deployment in progress ("A deployment of this service is already running.") or while it is suspended ("This service is suspended.").

• A service with domains cannot be deleted until they are removed: "Remove this service's domains first."

• Every domain answers over HTTPS on the path /. Cloud accepts no certificate of your own, and offers no wildcard domains, redirects or path routing.

• An application from the catalogue that builds settings from its address, such as n8n, restarts with the new address in its environment when a domain is added, renamed or removed.

• A notification channel can take the events Domain verified and Domain verification failed. Notifications sets one up.

A domain is stuck goes through the failures one by one.