> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# Add a custom domain

> Serve an app on your own host name over HTTPS, with A/AAAA records or a CNAME.

**Goal**: your app answers on a host such as `shop.example.com`, with a
certificate A-Line.cloud issues and renews for you.

## Before you start

- A running app or static site.
- Access to the DNS records of your domain (at your registrar or DNS
  provider).

## Pick A/AAAA or CNAME

The **DNS setup** choice decides which records you create.

| | **Point to load balancer IPs** | **CNAME to A-Line hostname** |
| --- | --- | --- |
| Records | One `A`/`AAAA` record per load balancer address | One `CNAME` to a host A-Line.cloud gives you |
| Apex (`example.com`) | Works | Does not work, unless your DNS provider offers ALIAS, ANAME or CNAME flattening |
| When load balancers change | You update the records yourself | A-Line.cloud's DNS follows them |
| Depends on | Only your DNS provider | A-Line.cloud's DNS as well, which has no availability SLA yet |

Use A/AAAA records for an apex domain, or when you want no dependency on
A-Line.cloud's DNS. Use a CNAME for a subdomain when you want the records to
follow your load balancers.

### Which records for my hostname?

<DomainHelper>

An apex such as `example.com` takes `A`/`AAAA` records; a host below it such as
`shop.example.com` takes `A`/`AAAA` records or one `CNAME`. Ownership is a TXT
record at `_a-line-verify.` plus the hostname.

</DomainHelper>

## Steps

Pick how you work; the choice is remembered on every page.

<InterfaceTabs items={['Console', 'IaC', 'API', 'MCP']}>
<InterfaceTab value="Console">

<Steps>
<Step>

Open the app on the canvas, go to the **Domain** tab and select **Add
domain**.

</Step>
<Step>

Leave **Domain source** on **Use my own domain** and enter the host, such
as `shop.example.com`.

</Step>
<Step>

Keep **Protocol** on HTTPS for a website. Set the **Container port** to
the port your app listens on. Add a **Path prefix** only to route part of
the site.

</Step>
<Step>

Pick the **DNS setup** (see above) and select **Add domain**.

</Step>
<Step>

If your organization has not verified the domain yet, a dialog asks what
to verify: the base domain with every subdomain, or only this host.
Select **Start verification**.

</Step>
<Step>

At your DNS provider, create the TXT record the dialog shows
(`_a-line-verify.example.com`), and the A/AAAA or CNAME records listed
on the **Domain** tab.

</Step>
</Steps>

</InterfaceTab>
<InterfaceTab value="IaC">

First claim ownership with a [domain file](/iac/domains), then list the
host under the app's `domains` of a [project](/iac/apps). `dns_target`
is `a_records` or `cname`:

```yaml title="projects/shop/project.yaml" iac tree=custom-domain
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop
```

```yaml title="projects/shop/apps/web.yaml" iac tree=custom-domain
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/web:2.0.0
port: 3000
domains:
  - domain: shop.example.com
    dns_target: cname
```

The sync result lists the records to create. See
[Networking](/iac/networking#domains) for every key.

</InterfaceTab>
<InterfaceTab value="API">

Add the host to the app. Your organization must have verified a domain
that covers it; `pending_verification: true` accepts a host whose domain is
still being verified, and it routes once that verifies:

```http api
POST /v1/clusters/{cluster_id}/apps/{app_id}/domains
Authorization: Bearer $ALC_API_KEY
Content-Type: application/json

{ "domain": "shop.example.com", "port": 3000, "dns_target": "a_records" }
```

The DNS records to create can be read back later; the
[API reference](/api/reference/domains) lists the calls.

</InterfaceTab>
<InterfaceTab value="MCP">

Ask your connected client, for example: "Add shop.example.com to the web
app in production." It finds the app with `find_app` and calls
`add_domain`, which answers with the domain's status and the DNS records to
create. See [Connect an AI client](/mcp).

</InterfaceTab>
</InterfaceTabs>

## Verify

The verification is checked about every minute; select **Check now** to
check right away. Once the domain is verified, the host is routed.

On the **Domain** tab, each host shows its state. **DNS resolves correctly**
means your records point at the cluster. The certificate badge moves from
**Cert pending** to **Cert issued** a short time later. Then open
`https://shop.example.com`.

## Troubleshooting

- **Not verified** or **Pending verification**: the TXT record is missing or
  not visible yet. DNS changes can take a few minutes, sometimes longer at
  some providers. Check the record's exact name and value.
- **Not resolving yet**: the A/AAAA or CNAME records are missing or point
  elsewhere. Compare them with the records listed on the **Domain** tab.
- **Cert failed**: the certificate could not be issued. Hover the badge for
  the error. The most common cause is a CDN or proxy in front of the domain
  that answers the HTTP challenge itself: turn on **Behind a CDN or proxy**
  and create the **Certificate challenge CNAME** it shows. See
  [Use a CDN or proxy](/concepts/cdn-proxy).
- **CNAME at the apex**: not possible. Switch the **DNS setup** to **Point to
  load balancer IPs**.

## Without your own domain

Pick **Generate a domain** as the **Domain source** to get a host on the
platform's domain instead. It needs no DNS records and no verification.

## Next steps

- [Domains and certificates](/concepts/domains): how verification and
  certificates work.
- [Use a CDN or proxy](/concepts/cdn-proxy): Cloudflare, Fastly, Bunny and
  CloudFront.
- Manage your verified domains under **Domains** in the sidebar.
