Update BYOD docs: clarify DNS options and staging workflows

[Copilot]

Users were unclear about DNS management options when using custom domains, particularly around avoiding repeated defang cert gen calls for staging environments and the difference between using Route 53 vs external DNS providers.

Changes

docs/concepts/domains.mdx

• Restructured BYOD section with two DNS management options:
  • Option 1: External DNS (CloudFlare, Namecheap) with direct domain or CNAME approaches
  • Option 2: Route 53 (automatic DNS/cert management, no cert gen needed)
• Documented both domain formats provided on deployment: defang.app and cloud provider (e.g., AWS ELB)
• Added guidance on using --project-name for environment separation

docs/tutorials/use-your-own-domain-name.mdx

• Split into two approaches: Route 53 (recommended) vs external DNS providers

• Added CNAME workflow for staging environments that frequently deploy/teardown without DNS reconfiguration:

  services:
      web:
          # No domainname - use defang.app domain
          ports:
          - mode: ingress
            target: 3000
            protocol: http

  Then CNAME staging.example.com → web--3000.myproject.user.defang.app once. Subsequent deployments work without DNS changes.

• Added multi-environment management section with name: field and --project-name flag examples

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Update BYOD docs</issue_title>
<issue_description>Update the BYOD docs to reflect the questions and answers from this dialog:

you once mentioned that if i used route 53 to maintain my domain's dns I would not need to change configurations on my cloudflare everytime i needed to a defang cert gen. do you have a tutorial on how i should set it up? or is it auto-setup if i move my domain management to the same aws account?

I have my domain in namecheap, and the DNS is at cloudflare, i could move it to aws if that will make the up and down easier without having tio reconfigure, Particularly because i want to set up a staging environment that I will keep putting down to save costs when i dont need it and put it up when i have to run a demo..... would hate to have to change a cname entry everytime i put it up....

well, you can always have your subdomains be a CNAME to the xyz.defang.app domain.. defang stack will make that easier.
But you can already do that using custom project names, either setting different name: in compose files, or by passing --project-name
(our new stack feature will basically do this for you, and it becomes your project-name suffix, eg. project "hello" and stack "Staging" would deploy as "hello-staging")

If you use the defang.app as CNAMEs , you wouldn't have to do anything. You'd still have do defang cert gen to recreate SSL certs after up.
THAT's the part you can skip if you move the DNS to Route53

does it give it to me when i defang up, i have never noticed it, i have always noticed something like this: defang-xyz-b0f79bb-123456789012.ca-central-1.elb.amazonaws.com

It does both! Typically people want to use the amazon one, because then you're not dependent on Defang

Perfect, then i can configure it to project name and it would work perfectly..... :)

The defang one will always be ...defang.app, or even --… if you have more ports on a service
</issue_description>

<agent_instructions>Update the BYOD docs to reflect the answers in this dialog.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Update BYOD docs #325

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[defangdevs]

Assigned here to review for technical accuracy before merge (defangdevs box).

CI is green and most of the restructuring is a solid improvement, but I found one factual error worth fixing before this ships to users, verified against the defang CLI source (DefangLabs/defang, src/pkg/cli/cert.go):

defang cert generate is a no-op without domainname

Both new "CNAME to the Defang domain" flows say to skip domainname on the service and still run defang cert generate once to get a cert for the custom domain:

• docs/concepts/domains.mdx, Option 1B, step 5: "You'll still need to run defang cert generate once to create the SSL certificate..."
• docs/tutorials/use-your-own-domain-name.mdx, Approach 2 / Option B, steps 1 and 5: "Don't add a domainname..." then "Run defang cert generate once to create the SSL certificate for your CNAME."

But collectDomainJobs in cert.go skips any service with no domainname entirely:

if si.Domainname == "" {
    term.Warnf("service %q: `domainname` is deployed without a domainname, skipping cert generation", svc.Name)
    continue
}

and GenerateLetsEncryptCert short-circuits with "No domainname found in compose file; no HTTPS cert generation needed" when there are no jobs at all. So as written, step 5 does nothing — no cert is ever issued for staging.example.com, and browsers hitting it over HTTPS would get the *.defang.app wildcard cert (a hostname mismatch), not a valid cert for the custom domain.

Suggested fix: keep domainname: staging.example.com on the service in this flow too (don't drop it) — defang cert generate needs it to know which hostname to issue for. The part of the workflow that's actually stable across redeploys is only the CNAME target choice, not whether domainname is set.

One thing I couldn't fully confirm from the docs repo alone, worth double-checking with whoever answered the original Slack/Discord thread (looks like it might have been you, Lio, based on the quoted excerpt): getDomainTargets in cert.go explicitly prefers the raw ALB LbDnsName over the defang.app domain when generating the cert's required DNS records ("Only use the ALB for aws cert gen to avoid defang domain in the middle"). If that ALB hostname isn't stable across defang down/up cycles for the same project, then CNAMEing to it (rather than to the stable <service>.<project>.<user>.defang.app) would reintroduce exactly the DNS-churn problem this doc section is trying to solve. Worth confirming which hostname cert generate's printed instructions actually tell users to CNAME to in this scenario before merging.

Not blocking the rest of the PR — the Route 53 section and the multi-environment / --project-name guidance look accurate and are a nice addition. Happy to push a fix commit for the domainname issue if useful once the CNAME-target question above is settled.

[lionello]

@defangdevs please take over this pr

[defangdevs]

Took over per Lio's request. Pushed a fix for the blocking issue from the earlier review:

• Both docs now keep domainname set on the service in the "CNAME to Defang domain" flow — defang cert generate silently skips any service with no domainname, so as written the custom domain never actually got a cert.
• Reframed the win of that flow: it avoids DNS record churn, not the need to rerun defang cert generate. Confirmed against pulumi-defang (CreateProjectInfra in provider/defangaws/aws/alb.go/infra.go): the ALB has no RetainOnDelete/deletion protection, so defang compose down + up destroys and recreates it, and its *.elb.amazonaws.com hostname changes every cycle. The defang.app domain doesn't, so CNAMEing to it is what's actually stable — you still need to rerun defang cert generate after each redeploy (matches the original Slack thread: "You'd still have to do defang cert generate to recreate SSL certs after up. THAT's the part you can skip if you move the DNS to Route53").
• Dropped the "CNAME to either the defang.app domain or the AWS load balancer domain" framing in the tutorial, since the ALB one isn't stable and defeats the point of that option.

CI is green. Route 53 section and multi-environment guidance were already accurate, untouched. Over to you for merge, Lio.

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 43076c43-90f2-4bef-9f61-3507f46ad301

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[defangdevs]

Your latest edit (3db719c) added a blank line before </TabItem> on line 47 — that broke MDX parsing (the parser treated the closing tag as a continuation of the preceding list item instead of the tag closing the tab). Pushed a fix (4e85648) removing the blank line, consistent with every other </TabItem> in the file. Waiting on CI.

[lionello]

@defangdevs still failing tho

[defangdevs]

Found the actual root cause — my earlier "removing the blank line" fix (4e85648) just reverted Lio's edit back to the previous broken state; that state was never actually green (checked: d7e6d6d's "Test deployment" run was red too, my earlier "CI is green" comment was wrong/premature).

The real bug: the list right before the closing ::: has no blank line separating it from :::, so CommonMark's lazy-continuation keeps that list item "open" through the ::: line. </TabItem> is a JSX close tag, and unlike an ATX heading it doesn't interrupt a list — so without a blank line before it either, it gets swallowed into the same open list item, which is what trips up mdast-util-mdx-jsx.

Pushed a fix (f318f09): blank line before ::: (closes the list) and blank line before </TabItem> (closes the admonition block). Verified locally with docusaurus build — reproduces the exact CI error without those blank lines, builds clean with them. Waiting on CI now.

[defangdevs]

Confirming CI is green on the latest commit (f318f09) — all checks (Test deployment, CodeQL, CodeRabbit) pass.

Both concerns from my earlier CHANGES_REQUESTED review are resolved:

• domainname no-op issue → fixed in d7e6d6d (kept domainname set in the CNAME flow).
• MDX build failure (the actual reason CI kept failing after that) → root-caused and fixed in f318f09: the list before the closing ::: needs a blank line before and after it, not just before </TabItem> as the original suggestion had it. Verified locally with docusaurus build.

Approving to clear my own stale review. Merge decision stays with Lio.

[defangdevs]

CI is green on f318f09 (Test deployment, CodeQL, CodeRabbit all passing) and I've approved to clear my own stale CHANGES_REQUESTED review — both flagged concerns are resolved. Ready for you to merge whenever, Lio.