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

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](/docs/dns/guide/point-a-name-at-a-resource).

## Add the domain

**Console**
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.

**CLI**
```sh
dcloud deploy domains add app-id --domain shop.example.com
```

**API**
```http
POST /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/domains
{ "domain": "shop.example.com" }
```

**Terraform**
```hcl
resource "dcloud_app_domain" "shop" {
  app_id = dcloud_app.web.id
  domain = "shop.example.com"
}
```

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](scale-an-app.md).

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

## Related

- [Scale an app](scale-an-app.md), for domains behind a load balancer
- `deploy.domains.add` · `dcloud deploy domains add` · `dcloud_app_domain`
