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?
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:
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop# 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: cnameThe 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
- Domains and certificates: how verification and certificates work.
- Use a CDN or proxy: Cloudflare, Fastly, Bunny and CloudFront.
- Manage your verified domains under Domains in the sidebar.