Skip to main content
Open console

Domains

Adding your own domain, proving it is yours, choosing the primary and canonical one, and where each certificate comes from.

10 min read

Every environment answers on a platform hostname, and on your own domains once you have proved they are yours. Manage both on the environment's Routing tab.

The platform hostname

Each environment gets one, built from the environment's name and the project's:

production.gwfdxo99.vallic.cloud

It is created with the environment, already verified, and its DNS is ours. You cannot remove it or switch it off, and renaming the project does not change it.

It is never put behind the CDN. When you are checking whether something is broken, it is the address that does not depend on a cache.

Adding a domain

Routing → Add domain. It asks for the hostname and, if something sits in front of us, which CDN that is (below).

A hostname is refused if:

Refused Why
It contains * Wildcards are issued by the platform, not added by hand
It is under vallic.cloud Only the platform issues names there
It is already on this project, on any environment One name routes to one place
Somebody else on the platform has already verified it Whoever proves control first has it
It is an IP address There is nothing to issue a certificate for

A hostname somebody else added but never verified does not block you.

Pointing DNS at us

When you add a domain, the tab shows the records to create, values filled in, each with a Copy button. Copy them rather than retyping: one wrong character in the verification value reads as "not propagated yet".

Your domain Record
A subdomain — www.example.com, shop.example.com CNAME to the environment's CNAME target
An apex — example.com A record to the environment's IPv4 address, or ALIAS/ANAME to the CNAME target if your provider offers it
An apex, with the platform CDN on ALIAS/ANAME to the pull zone
Any name, behind a CDN of your own No record pointing at us. The tab shows the origin to give your CDN (below)

The CNAME target is shown at the foot of the tab. It is the platform hostname, or the CDN's pull zone when the environment has one.

DNS does not let an apex hold a CNAME. Prefer ALIAS or ANAME where your provider has them: an A record names an address, and an address can change.

Behind the platform CDN there is no address to give. If your provider then has neither ALIAS nor ANAME, use a subdomain such as www and redirect the apex to it.

Only IPv4 addresses are given. There is no AAAA record to create.

Proving it is yours

A domain does not route until it is verified. Until then it shows Awaiting DNS on the tab, and requests for it get nothing from us.

Either of two records verifies it:

  • The CNAME itself, once the hostname's CNAME points at the environment's target.
  • A TXT record at _vallic-challenge. in front of the hostname, holding the value shown on the tab. For www.example.com that is _vallic-challenge.www.example.com.

An apex can only verify by TXT: its A record points at a shared address. So can a name behind a CDN of your own.

To bring a live site across without a gap, verify by TXT before you move traffic:

  1. Publish the TXT record.
  2. Let the domain verify.
  3. Check everything on the new environment.
  4. Change the CNAME.

Check now on the row looks straight away, up to twelve times an hour per domain. A pending domain is also checked on a schedule, until it verifies or you remove it. If a check fails, the row says why: no TXT record found, a TXT record with the wrong value, or the name already verified somewhere else.

Once verified, a domain stays verified. It is not re-checked, so you can remove the TXT record afterwards. Pointing its DNS somewhere else does not remove it from the environment. Remove it here as well.

Primary and canonical

One hostname per environment is primary, marked on the Routing tab. It sets PROJECT_BASE_URL, the address your production is checked at, and the CDN its visitors' addresses are read from. At first it is the platform hostname.

On a verified domain of your own What it does
Make primary It becomes primary. The platform hostname redirects permanently to it, keeping the path. Your other domains go on serving the site
Make canonical It becomes primary, and every other hostname the environment answers on redirects to it: the platform hostname, the apex, www, an old domain
Primary only, on the canonical domain It stays primary, and your other domains serve again

From a terminal:

vallic domain primary shop.example.com
vallic domain canonical shop.example.com

domain primary on the canonical domain is Primary only.

An unverified domain can be neither primary nor canonical.

There is no separate apex-to-www setting. Add both, make the one you want canonical, and the other redirects.

To stop redirecting altogether, make the platform hostname primary again — or remove your primary domain, and the platform hostname takes the role back on its own.

HTTPS

Everything is HTTPS. A request on plain HTTP is redirected permanently to the same address over HTTPS, on every hostname. The only exception is the path certificate authorities use to prove a domain.

You do not choose how a certificate is obtained: it follows from what is in front of the domain. The row on the Routing tab shows which applies:

Shown as Covers Issued by You need to
Platform wildcard The platform hostnames Us, one wildcard per project, renewed 30 days before it expires Nothing
Let's Encrypt Your domain, pointed straight at us Let's Encrypt, on the machine, renewed automatically Verify the domain and point it at us
Terminated at the CDN Your domain, behind a CDN The CDN Nothing, if it is the platform CDN; your CDN's own certificate otherwise

A Let's Encrypt certificate is asked for once the domain is verified and resolves to us. Expect a short window after you change DNS where the domain answers but its certificate is still arriving.

The Domains page shows the certificate on the domain's own row, with the date it is valid until. If there is none yet, the row gives the reason from Let's Encrypt:

The row says What to do
It found no DNS record for the name Publish the record shown under the domain. A record made in the last quarter of an hour may not be visible to Let's Encrypt yet
Another server answered for the name The name still points at your old host, or a CDN is in front of it. Behind a CDN the certificate is the CDN's: say so under Edit
It could not reach the environment on port 80 Check that the name points here
It has refused the name too often Nothing. It takes no more requests for that name for an hour

Once the cause is fixed, the machine asks again by itself. That is about twenty minutes after a refusal, and less often for a name that keeps being refused. The row says when. A name with no DNS record at all is not asked for until it has one.

You cannot upload a certificate of your own, and you cannot add a wildcard domain. If you need either, talk to us before you build around it.

Behind a CDN of your own

If your domain reaches us through Cloudflare, Fastly, Akamai, your own Bunny account or another proxy, say so under CDN in front when adding or editing it. That does not buy the platform CDN, which is bought under the project's commercial terms.

Where things point. The tab shows an origin for the name instead of a CNAME: the environment's platform hostname.

Your CDN's origin The origin the tab shows, over HTTPS, forwarding the visitor's hostname (the Host header)
Your domain's DNS record At your CDN, as your CDN tells you
Where the CDN is also your DNS and proxies the record: Cloudflare, Bunny DNS with acceleration One record does both: a CNAME to the origin, with the proxy on

Visitors get a browser warning if you point the name straight at us while a CDN is declared. Nothing then holds a certificate for it. If the CDN is gone, set CDN in front back to None and the machine obtains one.

The certificate. The visitor sees the CDN's certificate, and we do not obtain one for that name on the machine. Your CDN has to connect to us over HTTPS, and it will not find a publicly-issued certificate for your domain at our end. Plain HTTP is redirected to HTTPS, which a CDN following it does in a loop.

Who the visitor is. The platform reads the visitor's real address from the header your CDN sets on every request: CF-Connecting-IP for Cloudflare, Fastly-Client-IP for Fastly. Allow and deny lists are matched against that address. Your application receives it in X-Forwarded-For and X-Real-Ip. A framework that trusts the proxy in front of it has nothing to configure.

The header is believed only from the CDN's own addresses: the network's published edge ranges, which the platform fetches daily. A request from anywhere else is judged by the address it connected from.

Akamai publishes no list of its edges, so behind it the header is never believed. The same holds for a CDN we have no entry for. The rules then see the CDN's own address: a block list stops nobody and an allow list stops everybody.

Your own Bunny account needs one edge rule. Bunny's X-Real-IP does not reach us intact, so the platform reads X-Vallic-Ip. Your zone sends it once it has this rule, with a second action on it:

Bunny edge rule
Action Set Request Header
Header name X-Vallic-Ip
Header value %{User.IP}
Second action Set Request Header X-Vallic-Key, to the key the domain's dialog shows
Condition Request URL matches *

X-Vallic-Ip is believed only from Bunny's published edge addresses, and only beside your environment's key. Without the rule, or without the key, the rules see Bunny's address rather than your visitors', and the header is taken off before your application sees it.

Behind Fastly, have your service send the key. Any Fastly account's service can send requests from Fastly's addresses with Fastly-Client-IP set to anything. In your Fastly service, add the request header X-Vallic-Key, with the key the domain's dialog shows, to every request it sends to the origin. Then tick My Fastly service sends this header on the domain, or send "cdn_key": true to PATCH /domains/{id}.

From then on, the address is believed only with the key. Without the key the header is taken off and the rules see Fastly's address. This takes effect once every Fastly domain of the environment is ticked, since the rules read one header for the whole environment. Tick it only once the service sends the key: ticked before, your allow list, rate limit and probe rules see one Fastly address for all your visitors.

With the platform CDN, the pull zone, its certificate and its header are set up for you. The CDN in front field is not shown.

How many domains

Two custom domains per project are included, across all its environments. Platform hostnames do not count. A domain awaiting verification does.

Past the count, a domain is refused rather than billed. The console says so, and the API and vallic domain add answer 409 domain_allowance_spent.

More are bought under Commercial terms on the project's configuration page. There are three bands: up to 10, up to 25 and up to 100 domains. What each costs is on the price list. Past 100, talk to us.

Removing a domain

Remove on the row. The name stops routing on the next reconcile and its certificate is no longer renewed. Your DNS is not touched: records still pointing at us are yours to remove. Until you do, visitors get nothing useful from them.

The primary domain cannot be removed while it is primary; make another one primary first. You can add a removed name back later.

Who can do what

Role needed
See the Routing tab Viewer
Add, edit, check, make primary or canonical Developer
Remove Admin

On production, every change needs the Owner. See Teams.

The API can list, add, verify and remove domains, and make one primary or canonical (PATCH with primary or canonical). Declaring a CDN is done in the console.

Next

  • The edge — what happens to a request once it has reached us
  • CDN — putting the platform's CDN in front