Skip to Content

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 IPsCNAME to A-Line hostname
RecordsOne A/AAAA record per load balancer addressOne CNAME to a host A-Line.cloud gives you
Apex (example.com)WorksDoes not work, unless your DNS provider offers ALIAS, ANAME or CNAME flattening
When load balancers changeYou update the records yourselfA-Line.cloud's DNS follows them
Depends onOnly your DNS providerA-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?

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.

Steps

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

Console

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

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

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.

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

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.

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.

IaC

First claim ownership with a domain file, then list the host under the app's domains of a project. dns_target is a_records or cname:

projects/shop/project.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop
projects/shop/apps/web.yaml
# 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 for every key.

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:

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 lists the calls.

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.

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.
  • 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

On this page