Serve a project on a domain you own, such as app.example.com. You add the domain in HCode, create one CNAME record at your DNS provider, and HCode sets up HTTPS once the record is in place.
Custom domains are part of your plan. If your plan doesn't include them, the button on the Domains page reads Domains unavailable. Your plan and what it includes are on the Subscription page.
A root domain like example.com or example.co.za works differently: you serve the site on www and redirect the root to it. See Root domains.
Add a domain
- Open the project and go to Domains.
- Click Add domain.
- Type the hostname in Domain, for example
app.example.com. - Click Add domain in the dialog.
You can paste a full URL. HCode keeps only the hostname, so https://App.Example.com:8443/login becomes app.example.com. Keep the www. if you want www.example.com, because that is a different hostname from example.com.
HCode checks the domain as soon as it's added, and the domain's card shows the DNS record it needs and the result of that first check.
Create the DNS record
Where you manage your domain's DNS (often the company you bought the domain from), add the record shown under DNS record on the domain's card. For app.example.com on HCode it looks like this:
Type: CNAME
Name: app
Value: connect.hcode.site
The name is relative to your domain: app for app.example.com, shop.eu for shop.eu.example.com. If your provider adds your domain to the name for you, enter only that part. Use Copy value to copy the target exactly.
Remove any other A, AAAA or CNAME record for the same name. HCode won't set up HTTPS while some visitors are still sent to an old address. A CNAME that reaches connect.hcode.site through a name of your own (for example app.example.com → site.agency.example → connect.hcode.site) works too.
The card shows the record until the domain works. Keep the record in place after that, because it's what sends visitors to HCode.
Checks and statuses
Each check runs these steps in order and shows them under Progress: "DNS record", "Name servers", "Connection to your app", "Security certificate" and "HTTPS". A step only runs once the steps before it pass. DNS troubleshooting lists what each step can report and how to fix it.
While the Domains page is open, HCode checks every domain that isn't working yet: once when the page opens (unless it was checked in the last minute), then every 40 seconds for 10 minutes. After that the card says automatic checks have stopped and asks you to use Check now once your record is in place. Check now runs a check straight away and starts another 10 minutes of automatic checks. HCode also keeps checking in the background when the page is closed.
The badge on each domain tells you where it is:
| Badge | What it means |
|---|---|
| "DNS setup required" | HCode can't see your DNS record yet. Add it, or wait for your DNS change to spread. |
| "HTTPS provisioning" | Your record is in place and HCode is getting the security certificate. |
| "Serving" | Your site works on the domain over HTTPS while the last checks finish. |
| "Ready" | Every check passed. The note under it reads "HTTPS active". |
| "Needs attention" | A check found something you need to fix. The message under the badge says what. |
A domain that is "Ready" but whose project is stopped, failed or suspended shows "Set up, but your site isn't reachable on it right now. Check the project's status."
After the domain works
Once a domain has passed its checks, HCode keeps serving it. A later check that fails, for example because your DNS provider had an outage, changes the badge and message but doesn't disconnect the domain. If you change the record on purpose, the card tells you "Your domain's DNS no longer points to us. Put back the DNS record shown for this domain; we'll check again automatically."
Make a domain primary
Click Make primary on a domain whose DNS is in place. The domain gets a "Primary" badge and the previous primary domain loses it. Your app isn't redeployed. A new project starts with its generated address as the primary domain, and adding a custom domain doesn't change that.
Remove a domain
- Click Remove on the domain's card.
- Click Remove domain to confirm.
The dialog warns that "Traffic using this domain will no longer reach the project." Removing a domain is the only way to stop HCode serving a domain that has passed its checks. Your DNS record is not touched, so delete it at your DNS provider too.
Messages when adding a domain
| Message | What to do |
|---|---|
Enter just the domain name, like app.example.com. |
What you typed isn't a hostname. Type the domain name only. |
| "This domain is already registered" | The hostname is already on this project or another one. Remove it there first. |
| "Custom domains aren't available on your current plan." | Change to a plan that includes custom domains. |
| "This address belongs to the platform, so it can't be added as a custom domain." | The name belongs to HCode, such as the dashboard's own address. Use a domain you own. |
| "We couldn't add this domain. Try again in a minute." | Something went wrong on HCode's side. Try again, and contact [email protected] if it keeps happening. |
Wildcard hostnames such as *.example.com, IP addresses, single names such as intranet, and names under .local, .test, .example, .internal and the other reserved endings can't be added.
Who can change domains
Owners, admins and members can add, check, make primary and remove domains. Viewers see the domains and their status without those buttons, and the page says "Viewers can't add, check or change domains. Ask an owner or admin to change your role." See Roles and permissions.