Every [Static Hosting](Article: static-hosting) site is served on its own `deployhq-sites.com` address. You can also serve it on a domain you own, such as `www.example.com`, and DeployHQ sets up HTTPS for you automatically.

## Before you start

* Custom domains are available on paid plans, including trials.
* Each site can have up to **two** custom domains: a domain and its `www` counterpart, for example `example.com` and `www.example.com`.
* The first domain you add becomes the **primary** domain. The second one permanently redirects (HTTP 301) to the primary.
* Your site keeps working on its `deployhq-sites.com` address as well.
* You need access to the DNS settings for your domain, at whichever provider hosts its DNS (your registrar, Cloudflare, Route 53, and so on).
* To use an apex (root) domain such as `example.com`, your DNS provider must support **CNAME flattening** or **ALIAS** / **ANAME** records.

## Adding a custom domain

1. Open your project and go to the Static Hosting server's settings. For a global server, go to **Settings > Global Servers** and open the server.
2. Scroll to the **Custom domains** section.
3. Enter the hostname only, without `https://` (for example `example.com`).
4. To serve both the apex and `www` versions, leave the **Also add** checkbox ticked. The domain you typed becomes the primary, and the other one redirects to it. The checkbox is offered when the site has no custom domains yet and you enter an apex domain or its `www` version.
5. Click **Add a domain**.

The domain appears straight away as **Setting up...**. Its DNS records appear within moments and the page updates by itself, so you do not need to reload it. Keep this page open; you will copy the values from it.

If you did not add both at once, you can add the second domain later by repeating the steps with the `www` or apex counterpart of your primary domain.

### Adding a domain when you create a server

On paid plans and trials, you can add a domain while creating a Static Hosting server. Enter it in the **Custom domain (optional)** field of the new server form, and use the same checkbox to add the `www` or apex version.

Once the server is created you are taken to its **Custom domains** section, where the DNS records appear. If the domain cannot be added, the server is still created and a message tells you why. You can then add the domain from the **Custom domains** section.

## Publishing the DNS records

At your DNS provider, create **both** of these records for each domain. The domain only goes live once both are in place.

### 1. The CNAME record

This record points your domain at DeployHQ. Use the address shown in DeployHQ.

| Type | Name | Value |
|------|------|-------|
| CNAME | your domain, for example `www.example.com` | `customers.deployhq-sites.com` |

**Apex (root) domains**: a domain without a subdomain, such as `example.com`, cannot use a plain CNAME record, because DNS does not allow CNAME records at the apex. Use your DNS provider's **ALIAS**, **ANAME**, or **CNAME flattening** record instead, pointing at `customers.deployhq-sites.com`. If your provider offers none of these, use a subdomain such as `www.example.com`, or move your DNS to a provider that does.

### 2. The TXT record

This record proves that you own the domain. Its name and value are unique to your domain and are shown in DeployHQ after you add it. Copy both exactly as shown.

If the TXT name or value says it is still being issued, wait a moment. It appears on this page shortly.

Keep the TXT record in place after the domain goes live.

## Verification and HTTPS

DeployHQ checks your DNS records automatically every few minutes; you do not need to do anything else. Once both records are found:

1. The domain is verified.
2. HTTPS is set up for you with an automatically issued certificate.
3. The domain's status changes to **Active**, and your site is served on it over HTTPS.

DNS changes can take time to propagate, so verification may not happen straight away. The **Custom domains** section updates by itself and shows the latest status and the result of the most recent check.

### Checking a domain now

If you have just published your records and do not want to wait for the next automatic check, click **Check now** next to a domain that is waiting for verification. The result appears in a moment. A domain can be checked once every 60 seconds; if you click again sooner, you are asked to try again shortly.

Domains that are not verified within **7 days** expire. An expired domain must be removed and added again.

## Domain statuses

| Status | What it means |
|--------|---------------|
| **Setting up...** | DeployHQ is preparing the domain. Its DNS records appear within moments. |
| **Waiting for DNS** | Publish the two DNS records shown. |
| **Waiting for TXT record** | Publish the TXT record shown. |
| **Issuing certificate** | Your DNS is set up, and the HTTPS certificate is being issued, usually within a few minutes. |
| **Active** | Your site is being served on this domain over HTTPS. |
| **Failed** | The domain could not be set up or verified. The reason is shown next to it. See [The domain has failed](#the-domain-has-failed). |
| **Expired** | The domain was not verified within 7 days. See [The domain has expired](#the-domain-has-expired). |

## Removing a custom domain

In the **Custom domains** section, click **Remove** next to the domain. The domain stops serving your site, and it may remain in the list for a short while as the removal completes.

Your site is not affected otherwise: it keeps serving on its `deployhq-sites.com` address. If you remove the primary domain and another domain remains, the remaining domain becomes the primary. You can add a removed domain again later.

After removing a domain, delete the CNAME and TXT records you created for it at your DNS provider.

## Moving to the Free plan

Custom domains are available on paid plans and during a trial. If your account moves to the Free plan, its custom domains are removed and each site keeps serving on its `deployhq-sites.com` address. If you upgrade later, add the domains again and publish the DNS records shown.

## Managing custom domains with the API or CLI

You can list, add, check, and remove custom domains with the [Static Hosting Custom Domains API](Article: static-hosting-custom-domains-api).

You can also manage custom domains from the DeployHQ CLI with the `dhq domains` commands. See [Managing Servers with the CLI](Article: cli-servers).

## Troubleshooting

### The domain is stuck on pending

* Check that **both** records exist. The domain will not go live with only the CNAME or only the TXT record.
* Compare the record names and values with the ones shown in DeployHQ, character for character. Some DNS providers automatically append your domain to the record name, so entering the full name can produce a duplicated name such as `www.example.com.example.com`.
* For an apex domain, make sure you used an ALIAS, ANAME, or CNAME flattening record rather than a plain CNAME.
* Allow time for DNS propagation. DeployHQ keeps checking automatically every few minutes, and you can click **Check now** to check sooner.

### My DNS is hosted on Cloudflare

Set the CNAME record to **DNS only** (grey cloud), not **Proxied** (orange cloud). The domain will not go live while the record is proxied.

### The domain is verified but the certificate is still pending

Check whether your domain has any **CAA** records. CAA records restrict which certificate authorities may issue certificates for your domain. If your domain has CAA records and they do not allow the certificate authority used for your site, the certificate cannot be issued. Update or remove the restrictive CAA records, then wait for the next automatic check. If you are unsure which CAA entries you need, contact our support team.

### The domain has failed

A domain shows **Failed** when it could not be set up, or could not be verified. The reason is shown next to the domain. Check the DNS records if they are mentioned, then click **Remove** and add the domain again. Copy the DNS record values shown in DeployHQ for the newly added domain.

If you leave a failed domain in place, it expires 7 days after it was added.

### The domain has expired

A domain that is not verified within 7 days expires. Remove it from the **Custom domains** section, make sure both DNS records are correct, and add the domain again. Copy the DNS record values shown in DeployHQ for the newly added domain.

### I cannot add a domain

* Custom domains require a paid plan or a trial. If your account is on a free plan, upgrade from the **Packages** page.
* A site can have at most two custom domains, and the second must be the `www` or apex counterpart of the first. Remove a domain before adding a different one. Expired domains don't count toward this limit.
* An account can make at most 10 changes to custom domains per hour, across all of its sites. If you reach this limit, try again later.
* An account can have at most 10 custom domains waiting for verification. Verify or remove one to add another.
