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, then choose the Domains tab.
  2. Under Domains and certificates, for Add a domain you own, enter the hostname, for example shop.example.com.
  3. Choose Add domain. The domain is listed with its DNS and certificate badges and, unless the platform answers for it, the record to create.

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 panel then shows Answered by your hosted zone, and a Zone delegated badge, or Zone not delegated / Delegation not confirmed while your registrar does not yet name the platform nameservers. 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, create the record the panel names under Create this record at your DNS provider:

  • 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.

Beside the record the panel shows what DNS answers right now and what is known about the certificate, each with its explanation, and checks again every 15 seconds while the app has a machine. Re-check checks one domain on demand and records when it last resolved to the app.

Field API value Console badge Meaning
DNS ok Resolves here Resolves to the machine, or is a CNAME onto the default host
DNS mismatch Points somewhere else Resolves to another address
DNS missing No record Nothing answered, or the hosted zone answering for it is not delegated
DNS unknown Nothing to compare yet No machine serves the app yet, or the platform answers for the name and the check could not see it
Certificate pending Certificate pending Not issued yet: no machine, DNS not right yet, or the machine has not reported on the name
Certificate active Certificate active A valid certificate is served for the name
Certificate failed Certificate failed The served certificate does not verify, or issuance failed; the cause is shown
Certificate unavailable No certificate (plain HTTP) The platform runs on a local domain and serves plain HTTP
Certificate on-demand Certificate per name, on first request A wildcard: each name is issued on its first request; the names served so far are listed

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 and lists the names the machine has served certificates for.

Remove a domain

Choose the delete icon beside the domain, then Remove, 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?