Add a custom domain

Every project is reachable at {subdomain}.sites.deploybase.eu from its first deploy. Adding your own domain takes two DNS records and a few minutes of propagation. SSL is issued for you, with nothing to upload or renew.

There are two routes, and the first is the right one for almost everyone:

• You keep your DNS. Add a CNAME and a TXT record at your provider. Described below.
• We host your DNS. Delegate the domain’s nameservers to us once. Useful when your provider cannot point a root domain at a hostname.

Before you start

Add the domain to your project first, in the dashboard or over the API.

Domain changes need the Admin role

Adding, verifying and removing domains is restricted to team owners and admins. API keys act with Member permissions, so they cannot make these calls: use the dashboard, or a signed-in user’s token as $DEPLOYBASE_TOKEN below.

curl -X POST https://api.deploybase.eu/api/v1/domains \
  -H "Authorization: Bearer $DEPLOYBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "'"$PROJECT_ID"'", "domain": "blog.example.com"}'

deploybase then shows you two values, on the domain’s page and in the API response:

Value	What it looks like	Where it goes
CNAME target	deploybase-d-0123456789abcdef.b-cdn.net	The value of the record that routes traffic
Verification token	0123456789abcdef0123456789abcdef	The value of the _deploybase-verify TXT record

Both examples are deliberately fake. Neither looks like a tidy 0123456789abcdef run in real life, and every domain you add gets its own pair, so copy the values from your own domain’s page rather than from here. Adding example.com and www.example.com gives you two different CNAME targets, which is why the tables below use a different fake pair for the subdomain and for the root.

Examples on this page use example.com, which RFC 2606 reserves for documentation so that nobody can own it.

Point a subdomain at your project

blog.example.com, www.example.com, docs.example.com: all the same, because a CNAME is allowed anywhere except the root of a zone.

Type	Name	Value
CNAME	blog	deploybase-d-0123456789abcdef.b-cdn.net
TXT	_deploybase-verify.blog	0123456789abcdef0123456789abcdef

Most DNS panels want the relative name, so type blog and the provider appends .example.com. Typing the full blog.example.com creates a record for blog.example.com.example.com, which is the single most common mistake on this page.

Delete any existing A or AAAA record at that name first. A CNAME must be the only record at its name, and providers reject the combination or, worse, silently keep serving the old address.

Point a root domain at your project

A root domain (example.com, no subdomain) cannot use a CNAME: the DNS specification forbids it at the zone apex. Providers work around this with a record type called ALIAS, ANAME, or “CNAME flattening”, which resolves the target and answers with addresses.

Type	Name	Value
ALIAS / ANAME	@ or empty	deploybase-d-fedcba9876543210.b-cdn.net
TXT	_deploybase-verify	fedcba9876543210fedcba9876543210

An A record can never work here

deploybase serves from a CDN with no fixed IP address, so there is no number to put in an A record. One copied from a dig result works for as long as that edge node keeps the address and then fails, and a stale A record at the apex also blocks certificate issuance.

If your provider has no ALIAS or ANAME, use www as your canonical hostname or let us host the zone. Do not reach for an A record.

DNS provider compatibility lists which European providers support apex records, verified against each provider’s own documentation. Domain Chief has a step-by-step guide.

Serve both the root and www

deploybase treats example.com and www.example.com as two separate domains, as Vercel and Netlify do. Serving both means adding both to the project and creating a record for each, using that domain’s own CNAME target.

Once both are live, pick one of them as your primary address and let deploybase redirect the other. That is described next, and it replaces the old advice of setting up web forwarding at your DNS provider.

Choosing www as canonical works at every provider, because it needs only a CNAME. Choosing the root is tidier in print and needs ALIAS support.

Choose a primary address

A project can answer on several addresses at once: your custom domains, their www companions, and the {subdomain}.sites.deploybase.eu address it started with. Search engines treat those as separate sites showing identical content, which splits your ranking between them.

Naming one of them primary fixes that. Every other address then answers with a permanent redirect (301) to the primary one, keeping the rest of the URL intact, so www.example.com/pricing?ref=x becomes example.com/pricing?ref=x.

In the dashboard, open your project’s Domains page and use Primary address. Over the API, set primary_domain_id on the project to the id of one of its verified domains:

curl -X PATCH "https://api.deploybase.eu/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $DEPLOYBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"primary_domain_id": "'"$DOMAIN_ID"'"}'

Only a domain that is verified and has its certificate is eligible, because a redirect to an address that cannot answer yet would take the site down everywhere else.

By default your {subdomain}.sites.deploybase.eu address redirects too. If you use it as a staging address and want it to keep serving, set platform_url_mode to serve:

curl -X PATCH "https://api.deploybase.eu/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $DEPLOYBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"platform_url_mode": "serve"}'

Send "primary_domain_id": "" to clear the choice and go back to every address serving your site directly.

Browsers remember a 301 for up to 30 days

That is what makes a primary address worth having, and it is also why changing it later takes a while to show up for people who already visited. Pick the address you want on your business cards before you point anything at it.

Setting a primary address needs the Admin role

Like other domain changes, this is restricted to team owners and admins.

Verify, then wait for SSL

Once the records resolve, trigger verification from the dashboard or:

curl -X POST "https://api.deploybase.eu/api/v1/domains/$DOMAIN_ID/verify" \
  -H "Authorization: Bearer $DEPLOYBASE_TOKEN"

Verification is rate limited to once per 60 seconds per domain. DNS changes usually propagate in 5 to 30 minutes; the TTL on the records you replaced sets the ceiling.

A certificate is requested automatically as soon as verification passes, and the domain serves traffic when it is issued. Until then the hostname answers with a TLS error, which is expected rather than a sign that something went wrong.

Once it is live, the domain accepts TLS 1.2 and TLS 1.3 only. TLS 1.0 and 1.1 are refused, and there is nothing to configure either way.

GET /api/v1/domains/{id} reports where the domain has got to:

status	Meaning
pending_verification	The TXT record has not been seen yet
awaiting_delegation	Managed DNS only: the nameserver change has not reached the registry
verified	Ownership confirmed
failed	Verification could not be completed. The domain’s page says why

ssl_status	Meaning
pending	Queued
provisioning	The certificate is being issued
issued	Live. The domain serves HTTPS
failed	Issuance failed, usually a stale A record or a CAA record that excludes our issuer

Choose where a custom domain is served from

New custom domains are served only from edge locations in the EEA. Edge delivery region explains the trade-off and what the setting covers.

Open the project, go to Domains, and find the Serving region card on a live domain. Choose EEA only or Worldwide and select Save. Only team admins and owners can change it; members and viewers see the current region.

As a team admin, through the API:

curl -X PATCH "https://api.deploybase.eu/api/v1/domains/$DOMAIN_ID/edge-delivery" \
  -H "Authorization: Bearer $DEPLOYBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "eea"}'

mode is eea or global. GET /api/v1/domains/{id} returns the current value as edge_delivery, and supports_edge_delivery is false while a domain is still being set up on its own CDN zone. Changing it then returns 409 EDGE_DELIVERY_UNAVAILABLE.

A 502 EDGE_DELIVERY_CDN_APPLY_FAILED means your choice was saved but the CDN did not accept it yet. Send the same request again; it is safe to repeat.

Let deploybase host your DNS (beta)

Instead of managing records, you can delegate the whole domain to us: the name stays registered where it is, and we run the zone. Root domains then work at any registrar, because the apex is resolved inside our own nameservers.

Choose We host your DNS when adding the domain, or:

curl -X POST https://api.deploybase.eu/api/v1/domains \
  -H "Authorization: Bearer $DEPLOYBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "'"$PROJECT_ID"'",
    "domain": "example.com",
    "connection_mode": "managed_dns"
  }'

The response lists two NS records to set at your registrar, replacing the existing ones. There is no verification TXT record in this mode: controlling the delegation is the proof of ownership.

When the domain you delegate is a root domain, both example.com and www.example.com are wired up for you. Delegating a subdomain wires up that subdomain alone.

We check for the delegation by querying the registry directly rather than a caching resolver, so the change is usually picked up within a minute of your registrar publishing it. The dashboard polls every few seconds while you wait, and Check now forces a check (once per 60 seconds per domain):

curl -X POST "https://api.deploybase.eu/api/v1/domains/$DOMAIN_ID/check-delegation" \
  -H "Authorization: Bearer $DEPLOYBASE_TOKEN"

The response reports whether delegation was detected, which nameservers we expect, which ones the domain currently publishes, and whether DNSSEC is enabled at the registry.

Turn off DNSSEC first, and give it a day

If your domain publishes a DS record at the registry, remove it at your registrar before you change nameservers, and wait for the removal to propagate.

Our zone is unsigned. With a stale DS record in place, validating resolvers reject every answer, and the domain goes dark for a large share of visitors even though the nameservers are correct. Registry changes can take up to 24 hours, so treat it as its own step on its own day.

Check the imported zone before you delegate

Delegation moves all DNS for the domain, email included. We import the MX and TXT records we can see when the zone is created, but the import is best-effort: records on subdomains we cannot enumerate, DKIM selectors above all, are not discoverable and will not come across.

Compare the created zone against your current records, add anything missing, and only then change the nameservers at your registrar. Getting this wrong takes your email down, not just your website.

Managed DNS is functional but young, which is what the beta label is for. If your provider supports ALIAS records, keeping your zone where it is remains the lower-risk option.

Remove a domain

curl -X DELETE "https://api.deploybase.eu/api/v1/domains/$DOMAIN_ID" \
  -H "Authorization: Bearer $DEPLOYBASE_TOKEN"

This removes the domain, its certificate and its CDN hostname mapping. Traffic falls back to {subdomain}.sites.deploybase.eu.

You can add the domain again later. The CNAME target is derived from the domain name, so it comes back identical and any record you left in place still points somewhere correct. The verification token is new, so you will need to update the TXT record.