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. Forwww.example.comthat 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:
- Publish the TXT record.
- Let the domain verify.
- Check everything on the new environment.
- 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
Thank you. Good to know it helped.
Thanks — tell us what was missing. Open a ticket from Support in the console, and we answer on the ticket. Open the console