Add a custom domain

Serve an app on a hostname you own, or on every name below one with a wildcard, with a certificate obtained for it automatically.

Last updated 18 November 2026View as Markdown

Adding a domain does not require a redeploy: the machine's agent asks for the app's hostnames every few seconds and starts serving the new one. Replace app-id with the app's id and example.com with your domain.

Prerequisites

  • Permission for deploy:ManageDomain on the app (to add, re-check and remove a domain). deploy:DescribeApp shows the domains. Without dns:GetZone the panel does not show whether a hosted zone is delegated.
  • Access to the domain's DNS, unless the domain is inside one of your organization's hosted zones in DNS.

Add the domain

  1. Open the app (deploy:DescribeApp), then choose the Domains tab.
  2. Under Domains and certificates, choose Add a domain.
  3. For Hostname, enter the hostname, for example shop.example.com. For a compose app that publishes several services, choose the Service that answers on it (see Publish several services).
  4. Choose Add domain. The domain is listed as a row with its kind, DNS and certificate state; unless the platform answers for it, the row offers Create record beside its menu.

The domain is refused when:

  • it is not a bare hostname with at least two labels (400, Domain must be a bare host (no protocol or path) or Use a domain such as app.example.com, or *.example.com for every subdomain);
  • it is, encloses or sits under the platform's own domain (400, <domain> is the platform's own domain);
  • another organization holds it, or a name overlapping it, as a hosted zone or a custom domain (409, <domain> is already a custom domain on this platform, held by another organization, or … overlaps …);
  • it is already attached to an app (409);
  • the app is being deleted (409, The app is being deleted).

Point DNS at the app

When the domain sits inside one of your organization's hosted zones at the moment you add it, there is nothing to create: the platform writes an ALIAS record (TTL 60) into that zone, and the Deutsche Cloud nameservers answer with whichever machine currently serves the app. The DNS column then shows Zone delegated, or Zone not delegated while your registrar does not yet name the platform nameservers, and the row's side panel says what is missing. If the zone has no record answering for the app (the domain was added before the zone existed, or the record was replaced), the panel asks for an ALIAS onto the app's default host in that zone; removing and re-adding the domain writes it for you.

Elsewhere, choose Create record on the domain's row and create the record its side panel names:

  • Below the apex, a CNAME onto the app's default host, which keeps answering when the machine changes.
  • At the apex, which cannot be a CNAME, an A record to the machine's address (shown after the first deployment). It has to be updated if the app moves.
  • For a wildcard, a CNAME named *.example.com onto the default host.

The record, the explanation of each state and the hosted zone's delegation are in the row's side panel: Create record (or Fix record, Delegate zone, See why) opens it, as does selecting the row. The table checks DNS again every 15 seconds while the app has a machine. Re-check DNS in the row menu checks one domain on demand and records when it last resolved to the app.

Column API value Console Meaning
DNS ok Resolves here (Zone delegated) Resolves to the machine, or is a CNAME onto the default host
DNS mismatch Points elsewhere Resolves to another address
DNS missing Record missing Nothing answered
DNS delegation elsewhere / pending Zone not delegated The hosted zone answering for it is not delegated to the platform nameservers
DNS unknown Not checked yet No machine serves the app yet, or the platform answers for the name and the check could not see it
Certificate pending Pending Not issued yet: no machine, DNS not right yet, or the machine has not reported on the name
Certificate active (validUntil) Active until date A valid certificate is served for the name
Certificate failed Failed The served certificate does not verify, or issuance failed; the cause is in the side panel
Certificate unavailable None (plain HTTP) The platform runs on a local domain and serves plain HTTP
Certificate on-demand Per name, on first request A wildcard: each name is issued on its first request

For an app behind a load balancer the balancer, not the machine, holds the certificate. A name is added to it once the name resolves to the balancer, at the next deployment or the daily renewal; see Scale an app.

Wildcard domains

*.example.com serves every name exactly one label below example.com (a.example.com, not a.b.example.com, and not example.com itself: add the apex as its own domain). The machine obtains a certificate for each name the first time it is requested, which takes a few seconds for that first visitor. The machine only asks for names its app's domains cover, so pointing an unrelated name at it gets no certificate. Only one leading *. label is accepted. The panel checks DNS at a name under the wildcard.

Remove a domain

In the domain's row menu choose Remove, then Remove again to confirm, or run dcloud deploy domains remove app-id domain-id, with the domain's id from dcloud deploy domains list app-id. An ALIAS record the platform wrote into your hosted zone is removed with it; a record at another DNS provider is not touched.

Result

Once DNS points at the app, the machine requests the certificate, usually within a minute, and the app answers on the domain over HTTPS. dcloud deploy apps routing app-id shows the same DNS and certificate state as the panel.

Did this page help you?