Skip to main content

Custom domains

By default a published app lives at a Berrybell URL. Connect a custom domain to serve it from your own address — yourbrand.com — with HTTPS handled for you.

Before you start​

  • A paid plan. Adding a domain is a paid feature: on a free workspace the Connect form is disabled and the server refuses the request. A plan that's still on trial counts as paid.
  • Your app must be published. A domain belongs to exactly one environment — production, or an environment you created — and the automatic preview can never have one.
  • You need a domain you own, and access to its DNS settings at your registrar (for example GoDaddy, Namecheap, Cloudflare, or Google Domains).

How to connect a domain​

  1. Open Project settings → Cloud → Domains, or open Workspace settings → Domains and pick the project from the dropdown at the top. See Where to connect from for the difference.
  2. Enter the domain (or subdomain) you want to use, e.g. app.yourbrand.com.
  3. Berrybell shows you the DNS record(s) to add, each with a one-click copy button.
  4. Add those records at your domain registrar.
  5. Leave it. Berrybell keeps checking in the background — the status updates on its own as verification and certificate issuance complete. While a Domains page is open, it re-checks pending domains every 5 seconds.

Your app is then served over HTTPS at your custom domain.

Where to connect from​

Cloud → Domains belongs to the project and shows the domains of one environment: the one selected in the top bar, which is production unless someone on the project has switched it. Above the form it shows Also served at with that environment's Berrybell address, and an All domains in this workspace link to the workspace page. The button reads Connect, or Connect to staging on a project that has other environments, so you can see where the domain will go.

Workspace settings → Domains shows every domain on the project you pick. When the project has other environments, a select listing them (production first) appears before the domain field, and the connected domains are grouped by environment. The line under the form names where a new domain goes — "Connecting to staging, which is also served at" followed by that environment's address.

What the status means​

Each connected domain carries a status that moves through setup:

StatusWhat it means
Add DNS recordsNothing detected yet — the records aren't live at your registrar.
Validating…Berrybell can see your records and is confirming ownership.
Issuing certificate…Ownership is proven; the HTTPS certificate is being issued.
SSL ready · not routing yetThe certificate exists, but traffic for the domain isn't reaching Berrybell yet.
LiveBerrybell checked the domain and confirmed traffic really arrives here.
Needs attentionSetup failed. The domain shows the reason.
"SSL ready · not routing yet" is normal

It means the certificate is issued but your DNS still points somewhere else — Berrybell only marks a domain Live once it has probed the domain and seen traffic actually reach the platform. A domain in this state is already usable: it appears in the address list of the Publish popover for the environment it belongs to, and publishing that environment is how the route gets bound.

You don't have to sit and watch​

Verification and certificate issuance take minutes to hours, so Berrybell closes the loop by email: workspace owners and admins are emailed once when a domain goes Live, and once if it fails — with the reason.

HTTPS is automatic​

You don't need to buy or configure a certificate. Once the domain is verified, Berrybell issues and renews HTTPS for it automatically, so your visitors always get a secure connection.

Publishing to a specific domain​

Once a production domain's certificate is issued and the domain isn't paused, it's offered in the address list of the Publish popover, behind the chevron beside the address. Choosing it makes that domain production's primary domain, so later publishes keep going there. See The address.

Primary is per environment: each environment's primary is its live URL when that environment is published. You can set it on either Domains page:

  • Workspace settings → Domains names the environment: the primary is badged Primary for production (or Primary for staging), and every other domain offers Set primary for production or Set primary for staging, after the environment it belongs to.
  • Cloud → Domains badges it Primary, and the others offer Make primary. On a project with other environments, its tooltip reads "Use as the live URL when this environment is published".

The popover's address list offers only the domains of the environment you're publishing, so choosing staging lists staging's domains and never production's. A new domain isn't primary until you make it so: either pick it from that list before you publish, or press Make primary (or Set primary for staging) once the domain is added. From then on, publishing that environment uses its primary as the live URL on its own; with no primary, the live URL is the environment's Berrybell address.

Every publish re-points the published environment's attached domains at the new build, so a republish never drops a domain and never restarts certificate validation. Two qualifiers, both worth knowing:

  • Each environment's publish binds only its own domains. The automatic preview isn't an environment: it binds none, and leaves your domains pointing where they already point.
  • Only domains whose certificate is ready and that aren't paused get re-bound. A domain still sitting at Add DNS records isn't affected by a republish. If the primary itself is paused or not ready, the publish uses the environment's Berrybell address as its live URL rather than switching to another domain.

If you try to publish to a domain whose DNS or SSL isn't finished, Berrybell says so and asks you to finish setup first. If the domain is fully set up but paused, it tells you that instead. The Publish popover lists only the chosen environment's own domains, so a domain that belongs to another environment can't be picked for a production publish.

Domains and environments​

On a project with environments besides production, every domain belongs to exactly one of them, fixed when you add it.

  • Add a separate domain for each environment. Staging needs a hostname of its own, such as staging.yourbrand.com. Berrybell can't derive it from your production domain, because you create the DNS records at your own DNS provider — add it to staging, then add the records it shows there.
  • A domain can't move between environments. Remove it, switch to the other environment in the top bar, and add it again; DNS validation runs again from the start. Cloud → Domains says so under the list: "To move a domain to another environment, remove it here, switch to the other environment in the top bar, and add it again." On Workspace settings → Domains, pick the other environment in that select instead of switching.
  • Removing asks first on Cloud → Domains: "Remove app.yourbrand.com? It stops serving your app, and its certificate is deleted. To use it again you add it again and publish its DNS records again." On Workspace settings → Domains, Remove acts straight away, without asking.
  • The environment has to be ready. A domain can't be added while the environment is being set up or reset — for example, "Environment "staging" is provisioning. Wait for it to be ready, then add the domain."
  • An environment with domains can't be deleted. Remove its domains first. See Deleting.
  • The same plans apply. Adding a domain to any environment needs a paid plan ("Custom domains are available on Pro and Business plans."), and creating the environment in the first place needs a Business plan.
  • It's public. A domain on a created environment serves that environment's published app to anyone who has the address, just like a production domain.
Not available everywhere yet

Adding a domain to an environment other than production isn't available everywhere yet. Where it isn't, adding the domain is refused with a message that starts "Custom domains for environments other than production are not enabled on this deployment yet", and nothing is created. Production domains work as described on the rest of this page.

If your paid plan lapses​

Domains are paused, not deleted.

  • Traffic stops at the edge straight away, rather than at your next deploy.
  • Your app stays reachable at its Berrybell URL.
  • The certificate and your DNS records are kept exactly as they are, and the settings page shows Paused · no paid plan.
  • A paused domain also disappears from the Publish popover's address list.
  • Resubscribing brings the domain straight back: your certificate is not re-issued and there's nothing to re-validate.

Existing domains stay listable, refreshable and removable after a downgrade — only adding a new one needs a plan.

Names Berrybell won't accept​

  • Wildcards (*.yourbrand.com) aren't supported.
  • IP addresses can't be used as a custom domain.
  • localhost, and private or reserved suffixes — use a public domain name.
  • Berrybell's own domains can't be claimed.

Tips​

  • DNS can take time. Changes at your registrar may take anywhere from a few minutes to a few hours to propagate before verification succeeds.
  • Root vs. subdomain. You can use a bare domain (yourbrand.com) or a subdomain (app.yourbrand.com); follow the exact records Berrybell shows for the one you chose. A subdomain takes one CNAME plus the TXT records, all at once. A bare domain takes two steps: add the TXT records first, and Berrybell shows the A records only once the domain is verified. Those A records must be the only ones for the domain, any AAAA record has to go, and a TTL of 300 seconds lets a later change of address reach visitors quickly. For the sturdiest setup, also connect www.yourbrand.com and forward the bare domain to it from your registrar.
  • Keep the records in place. Removing the DNS records later will disconnect the domain from your app.
  • Removing a domain deletes its certificate with it, and needs edit permission.

Next steps​