Docs / Reference
DNS change runbook
Every production DNS or nameserver change requires this post-change verification before the change can be closed. The app may keep loading while mail authentication, verification records, or API routing silently break.
Repeatable verification
Run the automated check first. It covers routing, application responses, TLS validity and hostname coverage, MX, SPF, and DMARC, and prints a timestamped pass or fail report to attach to the change ticket.
npm run verify:dns-change
Checks that depend on infrastructure not yet in place report SKIP with the reason rather than failing, and activate automatically once configured. A non-zero exit blocks closing the change. The manual checks below remain required for anything the script reports as skipped.
Change gate
- Open a production DNS change ticket with owner, reviewer, affected zones, expected records, rollback plan, and maintenance window.
- Export the current DNS state before the change, including authoritative nameservers and all records for application, mail, and vendor verification.
- Manage DNS through version-controlled infrastructure where possible. Review and merge the DNS change before applying it.
- Lower TTLs before planned migrations, then restore the standard TTL after verification passes.
- Do not close the ticket until the checks below are captured with timestamps and command output or screenshots.
Required checks
| Area | Pass condition |
|---|---|
| Routing | A, AAAA, CNAME, apex, and www records resolve from authoritative DNS and at least two public resolvers. |
| Application | Homepage, docs, auth, dashboard, and critical static assets return expected 2xx or 3xx responses. |
| API | Health, readiness, scan, agent, webhook, and websocket endpoints route to the intended production service. Conditional — no API host is published today; applies once one exists. |
| TLS | Certificates are valid, unexpired, match all hostnames, and serve the expected chain after redirects. |
| Mail routing | MX records still point to the approved provider with the expected priority order. |
| SPF | Exactly one SPF TXT record exists at the sending domain and includes all approved senders. |
| DKIM | Every active selector for marketing, transactional, and support email resolves to the expected TXT or CNAME record. Conditional — no selector is published yet; applies once transactional sending is configured. |
| DMARC | The DMARC TXT record exists at _dmarc, has the approved policy, and keeps reporting addresses intact. |
| Verification | Search console, email provider, payment, analytics, security, and hosting verification records remain present. Conditional — verification currently uses a served HTML file, not DNS, so a DNS change cannot break it. |
| Transactional email | Password reset, invite, alert, and receipt-style messages send successfully and pass SPF, DKIM, and DMARC alignment. |
Command template
Replace perryscope.ai, hostnames, selectors, and endpoint paths with the production values in the change ticket.
# authoritative nameservers and core web records dig NS perryscope.ai +short dig A perryscope.ai +short dig AAAA perryscope.ai +short dig CNAME www.perryscope.ai +short dig A perryscope.ai @1.1.1.1 +short dig A perryscope.ai @8.8.8.8 +short # app, api, redirects, and TLS curl -I https://perryscope.ai/ curl -I https://perryscope.ai/docs # conditional — only once an API host is published # curl -I https://api.perryscope.ai/health openssl s_client -connect perryscope.ai:443 -servername perryscope.ai -showcerts < /dev/null # mail routing and authentication dig MX perryscope.ai +short dig TXT perryscope.ai +short # conditional — substitute the live selector once DKIM is published # dig TXT SELECTOR._domainkey.perryscope.ai +short dig TXT _dmarc.perryscope.ai +short
Transactional-email proof
- Send one transactional message from production, preferably a low-risk password reset or invite to an internal mailbox.
- Inspect the delivered headers and record SPF, DKIM, and DMARC results. All must pass with aligned domains.
- Confirm the message is not quarantined, rejected, or routed to spam by the receiving mailbox.
- Check the transactional provider dashboard for bounces, deferrals, domain warnings, and webhook delivery failures.
Rollback triggers
- Any production hostname resolves to the wrong target or fails from multiple public resolvers after propagation time.
- Any critical application, API, TLS, or websocket check fails.
- MX, SPF, DKIM, DMARC, or required vendor verification records are missing or materially different from the approved baseline.
- Transactional email cannot be delivered with passing SPF, DKIM, and DMARC alignment.
Control:Required for production DNS and nameserver modifications.