# Add a custom domain

> Attach your own hostname to an app or site target, verify DNS, and get a certificate

URL: https://pier.run/docs/guides/add-a-custom-domain

**Goal.** `api.acme.example` serves `api` over HTTPS with a certificate Pier issues and
renews.

### Declare the domain

```bash
pier add domain api.acme.example --app api
```

```text title="output"

  Changes:
    ~ update app "api" in prod
      domain: api.acme.example   (policy — applied immediately)

→  Updated pier.yaml
→  Waiting for infrastructure provisioning...
OK  Infrastructure ready
OK  Added domain api.acme.example to app "api"

```

The domain attaches to a target (`--app api/canary` for another target; `--site www` for
a site).

### Create the DNS records

Two records at your DNS provider, as the output shows:

| Record  | Name                     | Value                                       | Proves    |
| ------- | ------------------------ | ------------------------------------------- | --------- |
| `CNAME` | `api.acme.example`       | the target's hostname (`<id>.app.pier.run`) | routing   |
| `TXT`   | `_pier.api.acme.example` | `pier-verify=<token>`                       | ownership |

Pier re-checks until both resolve, then issues the certificate.

```bash
pier ls domains
```

```text title="output"
→  No custom domains.

```

`pending` becomes `verified`, and TLS `active`, once DNS has propagated. This usually
takes minutes and at most the record's TTL.

## What changed

```yaml title="pier.yaml"
    apps:
      - name: api
        targets:
          - name: primary
            plan: app-s
            domains:
              - host: api.acme.example
```

## Variations

* **An apex domain** (`acme.example`): providers that cannot CNAME an apex offer
  ALIAS/ANAME records; use one with the same target.
* **A site**: `pier add domain www.acme.example --site www`; sites use a shared CNAME
  target, shown in the output.
* **Remove**: `pier rm domain api.acme.example`.

## See also

[Domains](/docs/resources/domains) · [`pier add`](/docs/cli/reference/add)