Root domains

A root domain is your domain with nothing in front of it, such as example.com or example.co.za. It can't point to HCode directly, so you serve the site on www.example.co.za and redirect the root to it at your domain provider.

DNS doesn't allow a CNAME record on a root domain, and the addresses behind connect.hcode.site are shared and change, so copying them into A records would break your site sooner or later. HCode therefore doesn't add a root domain and doesn't offer A records for one.

HCode treats a name as a root domain when it sits directly under a public suffix: example.com, example.co.za and example.org.za are root domains, shop.example.co.za is not.

#Set up www and the redirect

1. On the project's Domains page, click Add domain and enter the root domain, for example example.co.za.

2. HCode doesn't add it. The dialog explains that example.co.za is a root domain and shows the two steps below.

3. Click Add www.example.co.za instead.

4. At your DNS provider, add the CNAME record the dashboard shows for www:

   textCopy

   Type:  CNAME
   Name:  www
   Value: connect.hcode.site
   

5. At your domain provider, set up a 301 redirect from example.co.za to www.example.co.za. Your provider may call this domain forwarding or a URL redirect.

www.example.co.za then goes through the usual checks and gets its certificate like any other custom domain. The redirect runs at your provider, so HCode never sees requests to example.co.za and doesn't list it as a domain.

If you already added www.example.co.za to the project, the dialog says so and only asks for the record and the redirect.

#Root domains added earlier

A project can still have a root domain that was added before HCode started refusing them. It keeps its card. The card is headed "Use www.example.co.za instead" and shows the same CNAME record and redirect steps, with an Add www.example.co.za button. Adding www never removes the root domain. If the root domain still works, the card says it "keeps working while you set up www.example.co.za".

Once www.example.co.za is set up, the card says "www.example.co.za is set up. Set up a 301 redirect from example.co.za to www.example.co.za at your domain provider, then remove example.co.za here." To finish:

1. Check that the redirect works: opening http://example.co.za in a browser should land on https://www.example.co.za.
2. Click Remove example.co.za on the card.
3. Read the warning and click Remove example.co.za again to confirm.

After this, visitors to example.co.za only reach your site through the redirect, so set it up first.

The checks for an old root domain say the same thing in their DNS step: "example.co.za is a root domain, which can't point to us directly. Add www.example.co.za as a domain instead, point it to us with a CNAME record, and set up a 301 redirect from example.co.za to www.example.co.za where you manage your domain." A root domain that used to work and no longer points to HCode is told "example.co.za no longer points to us. Move your site to www.example.co.za", and stays connected to your app while you move.

#Through the API

Adding a root domain through the customer API is refused with HTTP status 422 and the error code root_domain_use_www:

{
  "error": {
    "code": "root_domain_use_www",
    "message": "example.co.za is a root domain, which can't point to us directly. Add www.example.co.za instead.",
    "requestId": "...",
    "retryable": false
  }
}

Add www.example.co.za as the domain instead, create its CNAME record and set up the redirect yourself, as above.