Your site always has a free address, <name>.zeloxa.app. This guide puts it
on your own domain as well, such as www.example.com or example.com.
Zeloxa issues the HTTPS certificate for you and renews it.
You need:
- A project that is already deployed (see Deploy your first site).
- Access to the place where your domain's DNS is managed. That is usually the company you bought the domain from (your "DNS provider"), such as Porkbun, GoDaddy, Namecheap or Squarespace.
Add the domain
- Open your project in Hosting and choose the Domains tab.
- Type the domain under Add a custom domain, for example
www.example.com. Type only the name: nohttps://, no/and no port. - If you add
example.comorwww.example.com, a box offers to add the other one too and redirect it to the one you typed. Leave it ticked unless you have a reason not to (see www and the root domain). - Choose Add domain.
What you'll see: the domain in the list as Pending, "Waiting for DNS", and a Connect box with the DNS records to create. If your DNS provider supports automatic setup, the box shows a Connect with <provider> button instead (see Connect automatically).
Some names cannot be added:
- Addresses under
zeloxa.apporzeloxalabs.com. Zeloxa provides those. - IP addresses.
- A domain that is already connected to another site. The message is "<domain> is already connected to a site." A domain that someone added but never verified can be claimed by another account after 72 hours, so nobody can hold your domain hostage.
A project can have up to 10 custom domains, and an organization up to 50.
Connect automatically
For DNS providers that support automatic setup, Zeloxa shows a Connect with <provider> button. The button appears by itself; there is nothing to switch on.
- Choose Connect with <provider>.
- Sign in at your DNS provider if asked.
- Your provider shows exactly which records it will add. Approve them.
- You come back to the Domains tab.
What you'll see: "Records added at your DNS provider. Checking the domain now — this usually takes a few minutes." Zeloxa never sees your DNS provider login.
If you cancel at your provider, you see "Automatic setup was cancelled." You can try again, or add the records yourself. The records are always available under Prefer to add the records yourself?
When automatic setup is not available, the box names your provider where it can tell ("Add these records at Namecheap…") and lists the records.
Add the DNS records yourself
Sign in at your DNS provider, open the DNS settings for your domain, and create every record the Domains tab shows. Each value has a copy button. Copy them rather than typing.
The records
| Type | Name / Host | Value / Points to | Why |
|---|---|---|---|
CNAME (for a subdomain such as www) | The subdomain, for example www | The target shown in the dashboard, today cname.zeloxalabs.com | Sends visitors to your Zeloxa site |
ALIAS, ANAME or flattened CNAME (for the root domain) | @ | The same target | The same, for example.com itself |
TXT (only if the dashboard shows one) | The name shown in the dashboard | The value shown in the dashboard | Proves ownership, for example when the domain is already proxied by another provider |
For most domains that one CNAME or ALIAS record is all you add: once it points at Zeloxa, the HTTPS certificate is validated and issued automatically. Always use the exact names and values on your Domains tab; any TXT value is unique to your domain.
The Name / Host field. Most DNS providers add your domain to the name
for you. So for www.example.com you type www, and for the root you type
@. The dashboard shows this short name, with the full name under it
("Full name: www.example.com") for providers that want the whole thing. If
you type the full name into a provider that adds the domain itself, you end
up with www.example.com.example.com, which does not work.
Root domains need ALIAS, ANAME or CNAME flattening
The root of a domain (example.com, written @) cannot hold a normal CNAME
at most providers. The dashboard shows this row as ALIAS "or CNAME". Use
whichever your provider offers:
- an ALIAS record,
- an ANAME record, or
- a CNAME on
@, if your provider supports CNAME flattening.
If your provider has none of these, use www.example.com as your main
domain, and use your provider's domain forwarding to send example.com to
https://www.example.com.
Delete conflicting A and AAAA records
Before you add the record for a name, delete any existing A or AAAA records for that same name. For the root domain these are often a "parked" page your provider created when you bought the domain. If they stay, some visitors are sent to the old address, and the domain may never verify.
Also delete any older CNAME on the same name. A name can only have one CNAME.
What you'll see: changes usually reach Zeloxa in 2 to 15 minutes. Some providers take longer. When the domain is ready, the list shows Active and "Certificate issued", and the message "<domain> is connected and secured with HTTPS."
Automatic checking
You do not have to keep pressing a button. Zeloxa checks pending domains for you:
- While the Domains tab is open: every 30 seconds, for up to 30 minutes.
- After you close it: every 5 minutes in the background, for 72 hours after you added the domain.
You can also check right away with Connect / Re-check next to the domain. After 72 hours the background checks stop, and the domain stays pending until you press Connect / Re-check.
A domain only becomes Active when both are true: its DNS points to Zeloxa, and its HTTPS certificate is issued. Until then it does not serve your site.
HTTPS certificates
Zeloxa issues a certificate for every custom domain as soon as the records are found, and renews it automatically before it expires. There is nothing to buy or upload.
Keep the records in place after the domain is active. Removing the CNAME or ALIAS record stops the site and its certificate renewal.
The certificate's state is shown next to the domain, for example "Certificate pending validation" or "Certificate issued".
www and the root domain
Most sites should answer on both example.com and www.example.com, with
one redirecting to the other. That way visitors and search engines always see
one address.
When you add the domain. Adding example.com offers to add
www.example.com and redirect it to example.com. Adding www.example.com
offers the reverse. The offer only appears for a plain domain (such as
example.com) and its www. It does not appear for deeper names such as
shop.example.com, or for domains such as example.co.uk.
What you'll see: "Also added www.example.com, redirecting to example.com. Connect it the same way: press Connect on it below." The second domain needs its own DNS records.
Change it later. Choose Edit next to a domain, then pick:
- Serve the project, or
- Redirect to another domain of this project, then choose the Destination and the Status code: 308 Permanent (the default) or 307 Temporary.
Rules for redirects:
- The destination is another domain of the same project, or the project's
<name>.zeloxa.appaddress. - Redirects keep the path and query:
www.example.com/about?x=1goes tohttps://example.com/about?x=1. They always go to HTTPS. - No chains. You cannot redirect to a domain that itself redirects, and a domain that others redirect to must keep serving the project. Change those first.
- A redirect only starts once the domain is Active, the same as serving.
Remove a domain
- On the Domains tab, choose Remove next to the domain.
- Confirm with Remove domain.
What you'll see: "<domain> was removed from this project." It stops serving your project right away and its certificate is released. Domains that redirected to it go back to serving the project.
You can then delete its DNS records at your provider.
Provider tips
Menus change over time, so these are pointers, not exact clicks. In every case, copy the names and values from your Domains tab.
| Provider | Where DNS lives | Root domain (@) | Watch out for |
|---|---|---|---|
| Porkbun | Domain Management → DNS next to the domain | Use an ALIAS record with host left blank or @ | Delete Porkbun's default parking records on the root, www and * first |
| GoDaddy | My Products → your domain → DNS | GoDaddy DNS has no ALIAS record for the root. Use www as the main domain and Forwarding to send the root to https://www.<your domain> | Delete the default "Parked" A record on @ and the default www CNAME before adding yours |
| Namecheap | Domain List → Manage → Advanced DNS | Use an ALIAS Record with host @ | Delete the default URL redirect and parking records. Advanced DNS records only apply while the domain uses Namecheap's own nameservers |
| Cloudflare DNS | Your domain → DNS → Records | Add a CNAME with name @; Cloudflare DNS flattens it automatically | Set Proxy status to DNS only (grey cloud) for the records you add |
| Squarespace | Domains → your domain → DNS (DNS Settings) | Add custom records for subdomains. If there is no ALIAS option for the root, use www as the main domain and forward the root | Remove Squarespace's default records for the name you are connecting |
If your domain's nameservers point somewhere else (for example to your web designer's DNS), the records must go there instead. The Domains tab names the provider it found where it can.
Troubleshooting
Still pending after 30 minutes
The open-page checks stop after 30 minutes, but background checks continue for 72 hours, so you can close the page. If it is still pending after an hour:
- Compare every record at your provider with the Domains tab, character by character. A missing letter or an extra space is enough to fail.
- Check the name did not get your domain added twice
(
www.example.com.example.com). Use the short name. - If the Domains tab lists a TXT record, check you created it too.
- Make sure there are no leftover A or AAAA records on the same name.
- Press Connect / Re-check. If the page shows Validation errors, they say what is still wrong.
Some providers take a few hours to publish changes. If everything matches, wait and re-check later.
Wrong record type
- An A record pointing at an IP address does not work. Zeloxa needs a CNAME (or ALIAS on the root) pointing at the target shown.
- A CNAME on the root is refused by many providers. Use ALIAS or ANAME (see Root domains need ALIAS, ANAME or CNAME flattening).
- A URL redirect or forwarding record is not a DNS record Zeloxa can see. Remove it from the name you are connecting.
- The TXT values must be added as TXT records, not as CNAMEs.
A proxy at your DNS provider
Some DNS providers can put their own proxy or CDN in front of a record. In Cloudflare DNS this is the orange cloud. While the proxy is on, your provider answers instead of Zeloxa, and the domain may not verify or its certificate may not be issued. Turn the proxy off (in Cloudflare DNS, set Proxy status to DNS only) for the records you added for Zeloxa, then press Connect / Re-check.
CAA records
A CAA record limits which certificate authorities may issue certificates for your domain. If your domain has CAA records that do not allow the authority Zeloxa uses, the certificate cannot be issued, and the Validation errors on the Domains tab mention CAA. Most domains have no CAA records; if yours does and you did not add them on purpose, remove them. If you need to keep them, contact Zeloxa support for the authorities to allow.
"is already connected to a site"
The domain is connected to another Zeloxa project, possibly in another organization. Remove it there first. If nobody verified it, it becomes available again 72 hours after it was added.
"was never registered for a certificate"
The domain was saved without its certificate registration. Remove it and add it again to get its DNS records.
The domain works but shows an old site
Your browser or network may have cached the old address. Try a private window, or wait for the old record's time-to-live to pass (often up to an hour).
Related
- Deploy your first site
- Get a
domain.verifiedevent in Slack, Discord or your own endpoint: webhooks - Manage domains from code: the API reference and the CLI