# Manage custom domains

## Manage a project's published domain

A subdomain gives your documentation an address on Atloria's documentation domain;
your docs are always reachable on an Atloria subdomain.
A custom domain serves the same documentation from a domain you control, such as
`docs.yourcompany.com`. The address moves through DNS and certificate checks before it
becomes live.

`Serve your docs from your own domain, like docs.yourcompany.com.`

| If you need to… | Go to |
| --- | --- |
| Choose or rename the Atloria-hosted address | [Set or rename the subdomain](#set-or-rename-the-subdomain) |
| Connect a domain you control | [Connect a custom domain](#connect-a-custom-domain) |
| Check DNS records or respond to a failed check | [Check DNS and handle domain status](#check-dns-and-handle-domain-status) |
| Disconnect a custom domain | [Remove a custom domain](#remove-a-custom-domain) |
| Read the full progression from DNS setup to removal | [Custom domain lifecycle](doc:custom-domain-lifecycle) |
| Find the wider settings area | [System settings overview](doc:system-settings-overview) |
| Configure the surrounding branding settings | [Configure branding](doc:configure-branding) |

## Before you start

Before changing a published address, select the project whose documentation you want
to publish. Have access to the DNS provider for the custom domain and decide whether you
are changing the Atloria-hosted subdomain or connecting a separate domain.

**Prerequisites**

- Know which project you are changing.
- If you are connecting a custom domain, have access to its DNS settings.
- If a custom domain already exists, be ready to check its records and status in the
  management panel.

The current address is shown as text when one exists. The subdomain card also provides
the option to set an address when none exists.

## Open the domain settings

The **Domain** surface is the place where you manage the project's published subdomain
and custom domain. It is a tab in the Branding settings page, not the public address
itself.

**Steps**

1. In **Settings**, select **Branding** for the project.
2. Select **Domain**.

![Select **Domain** in Branding to open the domain settings.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/3b13a777f2967e2e6472a0e7ce0dff16.png)

**Result:** The **Subdomain** and **Custom domain** cards are available.

## Understand the domain settings

The **Subdomain** card controls the Atloria-hosted address. The **Custom domain** card
connects a domain you control and, after connection, provides the DNS records and
status actions for that domain.

| Area | What you use it for |
| --- | --- |
| **Current address** | Read the current subdomain address and copy or open it when one exists. |
| **Rename subdomain** | Enter a new lowercase subdomain value using letters, numbers, and dashes. |
| **Custom domain** | Enter the domain you want to connect. |
| **DNS records** | Read the records to add at your DNS provider and their check results. |
| **Remove domain** | Review the consequence of disconnecting the custom domain. |

The custom-domain area changes with the account state. While settings load, a loading
area appears. If loading fails, the page shows `Could not load your domain settings.`
and **Try again**. When no domain is configured, the connection form appears. When a
domain exists, the management panel shows its domain, DNS records, checks, and removal
area.

The DNS table uses the headers **Type**, **Name**, **Value**, and **Status**. Each DNS
value has a **Copy** control. A registrar link appears when the DNS check identifies
one and supplies a settings address.

When a control is working, its label changes to `Connecting…`, `Saving…`, `Checking…`,
or `Removing…` while the request is in progress. A successful copy shows `Copied!`.

## Set or rename the subdomain

Use this procedure when you want documentation to use an Atloria-hosted address. The
value is checked before it can be saved, so a value that is invalid, unchanged, taken,
or reserved does not complete the change.

**Prerequisites**

- Open the **Domain** surface.
- Have the subdomain value you want to use.

**Steps**

1. In **Rename subdomain**, enter a value containing lowercase letters, numbers, and
   dashes.
2. Check the message below **Rename subdomain**.
3. Choose the next action for the message shown below **Rename subdomain**.

   | Message | Next action |
   | --- | --- |
   | `Checking availability…` | Wait for the availability result. |
   | `Available` | Select **Save subdomain**. |
   | `Already taken — choose another` | Enter a different value in **Rename subdomain**. |
   | `Reserved — choose another` | Enter a different value in **Rename subdomain**. |
   | `Enter a valid subdomain` | Correct the value in **Rename subdomain**. |
   | `This is your current subdomain` | Enter a changed value in **Rename subdomain** or keep the current address. |

When a changed value is valid, the page also shows `Docs will be served at` followed by
the proposed address. After a successful save, the page shows `Subdomain updated`. If
the save fails, it shows `Rename failed` followed by the returned reason.

If no subdomain exists, the card shows `No subdomain yet — publish the project to claim one, or set it here.`

**Result:** The page shows `Subdomain updated` and the saved address in **Current
address**, or it leaves you at **Rename subdomain** with the message that explains what
to correct.

## Connect a custom domain

Use this procedure to serve the documentation from a domain you control. The domain
must pass the page's format check before Atloria can start the connection.

**Prerequisites**

- Open the **Domain** surface.
- Have access to the domain's DNS provider.
- Use a full domain such as `docs.yourcompany.com`.

**Steps**

1. In **Custom domain**, enter the domain you want to connect.
2. Select **Connect domain**.
3. Choose the next action for the message shown below **Custom domain**.

   | Message | Next action |
   | --- | --- |
   | `Enter a valid domain, like docs.yourcompany.com` | Correct the value in **Custom domain**, then return to step 2. |
   | `Apex domains need ALIAS-capable DNS — we recommend a subdomain like docs.yourcompany.com` | Select **use anyway**, then return to step 2. |

The page may show `Could not connect domain` followed by the returned reason when the
connection is refused. After a connection starts, use the DNS records shown in the
management panel at your DNS provider.

**Result:** The custom domain appears in its management panel with the DNS records to
add and check.

## Check DNS and handle domain status

The management panel is where you compare the records at your DNS provider with the
records required for the connected domain. The page checks automatically every few
seconds while the domain is present, and **Check now** starts an immediate check.

| If you need to… | Select |
| --- | --- |
| Start a manual DNS check | **Check now** |
| Retry a verification or certificate failure | **Retry** |
| Restore a domain shown as unavailable | **Recover** |
| Open the registrar's DNS page | **Open DNS settings** |
| Open a live documentation address | **Open** |

The panel shows **Last checked** with either the check time or `never`. Each record can
show `Observed:` followed by the returned value, or `nothing yet` when no value has been
found. A DNS check can also show `Your DNS looks managed by` followed by the registrar
name and **Open DNS settings**.

**Steps**

1. Read the **Type**, **Name**, and **Value** columns for each required DNS record.
2. Add the displayed records at your DNS provider.
3. Select **Check now** to request an immediate check.
4. If a record has a copy control, select **Copy** for the value you need to add.
5. If the check identifies a registrar and shows **Open DNS settings**, select it to
   open the returned DNS settings page.
6. Choose the recovery action shown for the domain.

   | Message | Next action |
   | --- | --- |
   | **Retry** appears after a verification or certificate failure | Select **Retry**. |
   | **Recover** appears after the domain becomes unavailable | Select **Recover**. |

7. If the panel shows `Your docs are live at`, select **Open** to open the published
   documentation address.

**Result:** The panel shows the latest DNS check, the returned record observations, and
the action that applies to the domain's current condition. When the domain is live, it
shows `Your docs are live at` and **Open**.

## Remove a custom domain

Removing a custom domain disconnects that address and deletes its certificate. The
subdomain continues working, but readers using the removed domain lose access. The
removal area states `Disconnects the domain and deletes its certificate. Your subdomain keeps working.`

> **Caution:** Readers using a removed domain lose access. Delete that domain's DNS
> records at your provider after the removal.

**Prerequisites**

- Open the **Domain** surface with a custom domain configured.
- Confirm that disconnecting the domain is the intended correction rather than checking
  or recovering its DNS configuration.

**Steps**

1. Select **Remove domain**.
2. Read the confirmation dialog titled `Remove this domain?`.
3. Choose whether to keep or remove the domain.

   | If you want to… | Next action |
   | --- | --- |
   | Keep the domain | Select **Keep domain**. |
   | Remove the domain | Select **Yes, remove it**. |

4. Delete the domain's DNS records at your provider after confirming the removal.

The confirmation dialog says `Readers using this domain will lose access. Remember to also delete the DNS records at your provider.` After removal, the page shows `Domain removed`. If removal fails, it shows `Remove failed` followed by the returned reason.

**Result:** The custom domain is removed and the connection form is available again;
the subdomain remains the address that continues working.

## Know what happens next

After saving a subdomain, use the address shown in **Current address**. After connecting
a custom domain, add the records shown in **DNS records** and check them until the page
shows the live result. If **Retry** or **Recover** appears, use that action and then
check the records again. The full sequence of domain states and outcomes is described
in [Custom domain lifecycle](doc:custom-domain-lifecycle).

| After you… | Continue with… |
| --- | --- |
| Save a subdomain | Read the new address in **Current address**. |
| Connect a custom domain | Add the records in **DNS records**. |
| Run a DNS check | Review **Observed:** values and the **Status** column. |
| Recover or retry | Select **Check now** after the action completes. |
| Remove a domain | Use the connection form if you need to connect another domain. |

**Result:** You have either a saved subdomain, a custom domain progressing through its
checks, a live published address, or a connection form ready for the next domain.

### When a domain action does not complete

| What you see | What to do |
| --- | --- |
| `Enter a valid subdomain` | Correct **Rename subdomain** and use lowercase letters, numbers, and dashes. |
| `Already taken — choose another` | Enter a different value in **Rename subdomain**. |
| `Reserved — choose another` | Enter a different value in **Rename subdomain**. |
| `This is your current subdomain` | Enter a changed value or keep the current address. |
| `Enter a valid domain, like docs.yourcompany.com` | Enter a full domain in **Custom domain**. |
| `Apex domains need ALIAS-capable DNS — we recommend a subdomain like docs.yourcompany.com` | Select **use anyway** only if you intend to continue with the apex domain. |
| `Could not load your domain settings.` | Select **Try again**. |
| `Could not connect domain` followed by a reason | Correct the domain or DNS setup indicated by the returned reason, then select **Connect domain**. |
| `Retry failed` followed by a reason | Review the returned reason and select **Retry** again after correcting the condition. |
| `Last error:` followed by returned text | Use the returned text with the DNS records and the current status to decide whether to check, retry, or recover. |
| `Remove failed` followed by a reason | Review the returned reason before selecting **Remove domain** again. |

The page also uses `Checking availability…`, `Available`, `Subdomain updated`,
`Rename failed`, `Checking…`, `Last checked`, `never`, `Your DNS looks managed by`,
`Observed:`, `nothing yet`, `Your docs are live at`, and `Domain removed` while these
actions are in progress or complete.