# 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 (`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](publish-several-services.md)).
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.

**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 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](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.

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

## Related

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