Custom Domain Setup in BYOB: Step-by-Step DNS Guide
Custom domains in BYOB now run through a guided flow inside the project page. You add the hostname, copy exact DNS records, track verification status, and move to active SSL without jumping across random docs.
If you have ever spent half a day fixing one wrong DNS field, this flow is for you.
TLDR
- Deploy once before adding a custom domain.
- Add one permanent routing record that points traffic to BYOB.
- Add temporary verification records for ownership and SSL.
- Recheck status after DNS propagation.
- Keep verification records until SSL is fully active.
Before you start
Have these ready before opening the modal.
- Domain registrar access.
- DNS management permission.
- Project already deployed at least once.
- Decision on root domain or subdomain.
If one of these is missing, setup slows down immediately.
What happens in the custom domain wizard
The modal separates records into two groups so teams do not confuse permanent routing with temporary validation.
- Routing record is permanent.
- Verification records are temporary until validation finishes.
Record types and lifecycle
| Record purpose | Typical type | Keep after setup |
|---|---|---|
| Traffic routing | CNAME or ALIAS/ANAME | Yes |
| Domain ownership | TXT | Usually no |
| SSL validation | TXT or CNAME | Keep until SSL active |
If your provider supports root flattening, BYOB will still give a target that maps cleanly to your project.
Root domain vs subdomain
Use this decision table.
| Domain choice | Good when | Typical record behavior |
|---|---|---|
example.com |
Main brand site | ALIAS/ANAME or flattened CNAME |
www.example.com |
Marketing site under primary domain | CNAME to BYOB target |
app.example.com |
Product app split from marketing | CNAME to BYOB target |
A lot of teams start on www first because propagation and rollback are usually cleaner.
Copy host/name and value exactly from BYOB. Do not manually normalize dots, prefixes, or quoting unless your registrar explicitly requires it.
Status values and what they actually mean
BYOB status values are useful if you read them as operational signals.
- Pending: registrar accepted record but propagation is incomplete.
- Active: routing is correct and BYOB can resolve host.
- SSL pending: domain is connected, certificate validation still running.
- SSL active: certificate fully issued and serving.
- Error: one or more records are wrong or missing.
Step-by-step setup runbook
- Deploy project once so BYOB has a live origin.
- Open custom domain modal and enter hostname.
- Copy routing record and add it at registrar.
- Copy ownership and SSL verification records.
- Save DNS records.
- Return to BYOB and click check status.
- Wait and repeat status check until active + SSL active.
- Remove verification records only after SSL is stable.
This sequence avoids most of the backtracking loops.
Propagation expectations
Propagation time depends on provider TTL and resolver cache behavior.
- Best case: a few minutes.
- Common case: 15 to 90 minutes.
- Worst case: several hours.
Do not repeatedly delete and recreate records unless you have confirmed a concrete mismatch.
Troubleshooting playbook
If status stalls, run this checklist in order.
- Confirm record type matches BYOB instructions.
- Confirm host/name for root vs subdomain is correct.
- Confirm no conflicting old CNAME/TXT exists.
- Confirm proxy mode is correct where DNS-only is required.
- Confirm record value has no extra protocol or path.
- Wait one TTL window, then recheck.
Common mistakes and fast fixes
| Mistake | Result | Fix |
|---|---|---|
| A record used instead of CNAME | Host never verifies | Replace with expected type |
Wrong host field (www vs root) |
BYOB cannot find ownership record | Recreate with correct host |
| SSL TXT removed too early | SSL stays pending | Re-add validation record and recheck |
| Legacy DNS record left in place | Flapping status | Remove conflict and wait |
A domain can route before SSL finishes. Treat setup as complete only when both domain and SSL are active.
Team workflow recommendation
If multiple people manage infra, assign explicit ownership.
- Product owner triggers domain request in BYOB.
- Infra owner updates DNS records.
- Product owner verifies status and confirms go-live.
- Both sign off in release notes.
This avoids silent assumptions when someone says "DNS is done" but only one record was added.
Go-live checklist
Use this final pass before public launch.
- Domain resolves in browser.
- HTTPS lock is valid.
- Canonical URL points to new domain.
- Redirects from old URL behave as expected.
- Analytics and cookies still function.
- Contact forms and auth callbacks work on new host.
FAQ
Can I add a custom domain before first deploy?
Not yet. BYOB requires one deploy first so the project has a valid publish target.
Do I need to keep ownership TXT forever?
Usually no. Keep it until domain and SSL are stable.
Why is SSL still pending when domain is active?
Domain routing and certificate issuance are separate checks. Routing can finish first.
What if my registrar does not support ALIAS at root?
Use subdomain flow first, or use provider-supported root flattening option if available.
Can I switch domains later?
Yes. Update domain config in BYOB and repeat verification flow for the new hostname.
