# Custom domain lifecycle

## Understand the custom-domain lifecycle

A custom domain is your own web address for serving published documentation, such as
`docs.yourcompany.com`. The setup stages are **Waiting for DNS**, **Verifying**, **Issuing
certificate**, and **Live**. The other outcomes are **Verification failed**, **Certificate failed**,
**Offline**, and **Removed**.

The lifecycle starts when the domain is connected and DNS records are checked.

```mermaid
stateDiagram-v2
    state "Waiting for DNS" as s1
    state "Verifying" as s2
    state "Issuing certificate" as s3
    state "Live" as s4
    state "Verification failed" as s5
    state "Certificate failed" as s6
    state "Offline" as s7
    state "Removed" as s8
    s1 --> s2: Check now
    s2 --> s3: Check now
    s3 --> s4: Check now
    s5 --> s2: Retry
    s6 --> s2: Retry
    s7 --> s2: Recover
    s4 --> s7: Check now
    s4 --> s8: Remove domain
    s8 --> s1: Connect domain
```

| If you need to… | Go to |
|---|---|
| Connect a domain or change a subdomain | [Manage custom domains](doc:manage-custom-domains) |
| Open the settings area that contains the Domain tab | [Configure Branding](doc:configure-branding) |
| Understand the full status path | Continue with [Check DNS and respond to the status](#check-dns-and-respond-to-the-status) |
| Find the next action for a displayed status | [Handle each domain-status branch](#handle-each-domain-status-branch) |

## Before you start

**Prerequisites**

- Select the project whose published documentation uses the domain.
- Have access to the DNS provider for the domain. DNS records are the type, name, and value that
  the Domain surface displays for the domain.
- Know whether you are checking an existing domain or connecting one for the first time.
- Keep the domain's current status and last check time in view when deciding what to do next.
- Use the exact message shown on screen when a check, retry, or removal does not complete.

The domain surface does not mark its visible controls as required. The page displays the current
domain value, DNS values, registrar, last-check value, and current status when available.

## Open the domain status

The Domain tab is the project-level surface for reading and responding to a custom-domain status.
Use [Manage custom domains](doc:manage-custom-domains) when you need to connect or change an address.

**Prerequisites**

- You have selected a project.

**Steps**

1. Open Branding settings for the selected project.
2. Select **Domain**.

![Select **Domain** to view the project's subdomain and custom-domain status controls.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/6d993ee2703ffe0cdc3c37e33864eb4a.png)

**Result:** The Domain tab opens with the **Subdomain** and **Custom domain** surfaces.

## Read the status surface

The Domain tab puts the project's published-address settings and custom-domain status together.
The **Subdomain** card contains **Current address** and **Rename subdomain**. The **Custom domain**
card contains the domain value and, when a domain is being managed, its DNS records and status
actions.

The visible status information is organised as follows:

| What you need to read | Where to read it |
|---|---|
| The configured address | The value beside **Custom domain** |
| The records to add or inspect | **DNS records** |
| The record kind | **Type** |
| The DNS name | **Name** |
| The required DNS value | **Value** |
| Whether a record check succeeded | **Status** |
| The last check time | **Last checked** |
| A server-side reason for a failed or **Offline** state | **Last error:** |

The surface can show **Check now**, **Retry**, or **Recover** according to the current status.
When the domain is live, it shows **Open** beside the live address. **Remove domain** is in the
danger area. Copy controls are available beside the domain and DNS-record values.

## Check DNS and respond to the status

DNS checking compares the domain's configured records with the records listed in **DNS records**.
The check can move the domain through its lifecycle, and the available action changes when the
status changes.

**Prerequisites**

- The Domain tab is open.
- A custom domain is present in the management panel.

**Steps**

1. Read the expected entries in **DNS records**.
2. Select **Check now**.
3. Choose the action that matches the status shown:

   | If the status is… | Select… |
   |---|---|
   | **Verification failed** or **Certificate failed** | **Retry** |
   | **Offline** | **Recover** |
   | **Live** | **Open** to open the live documentation address |

4. Read **Type**, **Name**, **Value**, and **Status** again after the check.

**Result:** The panel shows the latest DNS check and the action that applies to the current
domain status.

## Handle each domain-status branch

Each status tells you what is happening to the custom domain and which next action belongs to it.
Use the status chip and the DNS records table together; the DNS table shows the values that need
attention when a check does not succeed.

**Prerequisites**

- The Domain tab is open.
- The custom-domain status is visible.

**Steps**

1. Read the status chip and follow the matching branch:

   | Status shown | What it means for your next move |
   |---|---|
   | **Waiting for DNS** | Add or correct the listed DNS records, then use **Check now**. |
   | **Verifying** | Wait for the DNS check to finish and review the displayed records. |
   | **Issuing certificate** | Wait for certificate issuance, then review the status again. |
   | **Live** | Select **Open** when you need to view the published documentation. |
   | **Verification failed** | Correct the DNS records and select **Retry**. |
   | **Certificate failed** | Select **Retry** after the certificate problem is ready to be retried. |
   | **Offline** | Restore the DNS records and select **Recover**. |
   | **Removed** | Reconnect the domain from the setup surface with **Connect domain**. |

**Result:** You have taken the action associated with the displayed status, or the status remains
visible with the DNS information needed for the next check.

## When a check or removal goes wrong

Use the exact message on screen to identify the correction.

**Prerequisites**

- The Domain tab is open.
- The message is visible in the domain surface.

**Steps**

1. Read the exact message shown in the domain surface.
2. Apply the action in the matching row below.

| What you see | What to do |
|---|---|
| `Enter a valid domain, like docs.yourcompany.com` | Enter a domain in the requested format. |
| `Apex domains need ALIAS-capable DNS — we recommend a subdomain like docs.yourcompany.com` | Review the apex-domain warning before continuing. |
| `Could not load your domain settings.` | Select **Try again**. |
| `Try again` | Select **Try again** to retry loading the domain settings. |
| `Observed:` | Compare this value with the expected value in the same DNS-record row. |
| `nothing yet` | Add the listed DNS record, then select **Check now**. |
| `Open DNS settings` | Select **Open DNS settings** when the link is available. |
| `Your docs are live at` | Select **Open** to open the live documentation address. |
| `Readers using this domain will lose access. Remember to also delete the DNS records at your provider.` | Review the consequence and remove the provider's DNS records when you disconnect the domain. |
| `Domain removed` | The domain has been removed; reconnect it from the connect surface with **Connect domain** if needed. |
| `Retry failed` | Review the displayed status and DNS records before trying **Retry** again. |
| `Remove failed` | Review the displayed domain state before trying **Remove domain** again. |

**Result:** You have a message-specific correction to make before repeating the affected action.

## Know what happens next

After a successful DNS check, the domain can continue from **Waiting for DNS** through **Verifying**
and **Issuing certificate** to **Live**. A live domain shows **Your docs are live at** and an
**Open** link. If DNS changes after the domain is live, the status can become **Offline**; restore
the records and select **Recover**.

When you no longer want to serve documentation from the custom domain, select **Remove domain**.
Review the confirmation text before choosing **Yes, remove it** or **Keep domain**. Removing the
domain leaves the project's subdomain working. To configure or reconnect an address, continue
with [Manage custom domains](doc:manage-custom-domains). To return to the wider settings area, use
[System Settings overview](doc:system-settings-overview).

**Result:** The domain is either progressing toward **Live**, available at its published address,
recoverable through **Recover**, or ready to be reconnected after **Removed**.