Repository navigation
docs: status page custom domain certificates and renewal - #792
Conversation
New custom domains validate their certificate over HTTP with only the CNAME record, so the TXT step is now conditional. Adds a section on automatic renewal, CAA records, the certificate messages shown in the status page settings, and the renewal emails. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Removed the sentence about certificate problem emails: whether those emails are sent in production couldn't be confirmed from the code, so the page no longer promises them. |
hlenke
left a comment
There was a problem hiding this comment.
Needs changes · The setup steps and the quoted messages match the app. Before merging, limit the automatic-renewal claim to HTTP-validated domains and list the second certificate-failure message.
CI passes, the PR merges cleanly, and main hasn't changed communicate/status-pages/custom-domain.mdx since the merge base. The only other open PR on this file is draft #774 (sentence case), which changes the frontmatter title only. The new ## Certificate renewal and troubleshooting heading already uses sentence case, so the two shouldn't conflict. The new section goes at the end, after the setup steps, which is the right place.
The PR description says the new section covers "the email Checkly sends when a certificate can't be issued or renewed", but the diff doesn't mention an email. Add it if that's intended, or update the description.
Inline: 2 important, 1 wording.
What I checked
- Read the full diff from the merge base
7da4a04and the whole page at the PR head. gh pr checks 792: all 6 checks pass.gh pr view: MERGEABLE / CLEAN.git log <base>..origin/main -- communicate/status-pages/custom-domain.mdx: no new commits.pr_impact.py: no cross-file findings. Searched all.mdxonmainfor other custom domain, TXT and CAA setup instructions and found none outside this page.- Checked against source (monorepo origin/main@2d79b98589):
- New custom hostnames are created with HTTP domain control validation. HTTP-validated hostnames renew without DNS changes, while TXT-validated ones needed new records at renewal:
apps/backend/api/src/common/services/status-pages/lib/cloudflare-hostname-service.ts. - Records listed after saving (the CNAME, plus the ownership TXT and any TXT validation records Cloudflare returns), the save prompt, the green check (shown only once the hostname and certificate are active), and Refresh domain status:
apps/webapp/src/pages/status-pages/status-pages-editor/StatusPageEditorCustomDomain.vue. The CNAME targetcustom-domain.checkly-status-page.comcomes from configuration and matches the existing step. - The four quoted messages match the UI copy in
apps/webapp/src/pages/status-pages/StatusPage.i18n.ts, quoted up to the first sentence. The "usually takes a few minutes" timing and "start a new certificate order" also match that copy. The same file has a fallback validation-failure message and a read-only variant of the timeout message. - The "Cloudflare has not returned the certificate validation records yet" message only appears for domains that aren't HTTP-validated.
- New custom hostnames are created with HTTP domain control validation. HTTP-validated hostnames renew without DNS changes, while TXT-validated ones needed new records at renewal:
- Could not verify: how often Cloudflare returns an ownership TXT record for new HTTP-validated domains. The UI lists that record whenever Cloudflare returns one, so readers may still see a TXT row. "Add them if Checkly shows them" covers that case. I also couldn't confirm the certificate email mentioned in the description in source.
- No end-to-end test: certificate issuance and renewal go through Cloudflare and can't be exercised against local Checkly.
What changed
Updates
communicate/status-pages/custom-domain.mdx:Why
The page told every user to add TXT records, which no longer matches how custom domain certificates are issued. Users regularly hit certificate validation and renewal questions, and the page had no guidance on renewal or on the messages shown in the app.
Verified against the product code; certificate issuance and renewal can't be exercised locally.
Checks
python3 .github/scripts/check_frontmatter.py: passednpm run check:anchors: passednpm run check:links: passednpx mint broken-links: no broken linksnode .github/scripts/check-redirect-destinations.mjsand sitemap regeneration: passed, no changes🤖 Generated with Claude Code