Configure a Custom HTTPS Domain on ReadTheDocs

Desired Outcome

Configure a fully‑functional HTTPS URL for your ReadTheDocs project using either an apex domain (e.g., example.com) or a subdomain (e.g., docs.example.com). After completion the site loads over HTTPS, shows a Let’s Encrypt certificate for the exact domain, and HTTP requests redirect to HTTPS.

Prerequisites

• Administrator access to the ReadTheDocs project.
• Ability to edit DNS records for the domain you intend to use.
• Knowledge of whether your DNS provider supports CNAME, ALIAS/ANAME, or URL‑forwarding.
• Optional: command‑line tools such as dig or nslookup for DNS checks and openssl or SSL Labs for HTTPS verification.

Procedure

1. Choose the domain
   • Subdomain: docs.example.com
   • Apex domain (no sub‑label): example.com (requires ALIAS/ANAME support).
2. Configure DNS
   • For a subdomain, create a CNAME record pointing to the ReadTheDocs CDN hostname shown in the project settings after you add the domain (e.g., <project>.readthedocs.io.).
   • For an apex domain, create an ALIAS or ANAME record pointing to the same CDN hostname. If your provider does not support ALIAS/ANAME, use a CDN or forwarding service that terminates HTTPS and forwards to <project>.readthedocs.io.
3. Add the domain in ReadTheDocs
   1. Log in to ReadTheDocs.org and open your project.
   2. Navigate to Settings → Custom Domains.
   3. Click Add Custom Domain, enter the full domain (e.g., docs.example.com), and save.
   4. ReadTheDocs automatically requests a Let’s Encrypt certificate for the entered domain.
4. Trigger a rebuild

   After saving the domain, start a new build from the Builds tab so the new URL is reflected in the generated documentation.

5. Verify DNS propagation

   Use a public resolver to confirm the record points to the CDN. Example with dig:

   dig +short docs.example.com  # Expected output: .readthedocs.io.

6. Test HTTPS

   Open the domain in a browser; you should see a lock icon and a certificate issued by Let’s Encrypt for the exact domain. For a quick check:

   openssl s_client -connect docs.example.com:443 -servername docs.example.com 2>/dev/null | openssl x509 -noout -subject -issuer

7. Confirm HTTP→HTTPS redirect

   Visit http://docs.example.com and ensure it redirects to https://docs.example.com.

Expected Checks

• Project settings: the domain appears under Custom Domains and is marked active.
• DNS query: CNAME or ALIAS resolves to a hostname ending in .readthedocs.io.
• Browser certificate: subject matches the domain and issuer is Let’s Encrypt.
• SSL Labs test: passes all checks (no mixed content, proper chain).
• Redirect test: HTTP request returns a 301/302 to HTTPS without error.

Common Pitfalls & Recovery

• DNS not yet propagated
  • Wait up to 48 hours; during this period visitors may see the default ReadTheDocs error page.
  • Check with dig @8.8.8.8 to see if the authoritative server has returned the record.
• Using CNAME on an apex domain
  • Most registrars reject a CNAME at the zone apex. Use an ALIAS/ANAME record or a forwarding service that supports HTTPS termination.
• Certificate not issued
  • Verify the domain entered in ReadTheDocs matches the DNS record exactly.
  • Inspect the build log for any certificate‑request errors.
• HTTPS disabled in project settings
  • Go to Settings → Advanced and enable Force HTTPS. Leaving it off may cause browsers to block the site.
• Wildcard DNS but single certificate
  • Let’s Encrypt does not issue wildcard certificates via ReadTheDocs; each subdomain must be added individually.

Limitations & Notes

• ReadTheDocs renews the Let’s Encrypt certificate automatically every ~60 days; manual renewal is unnecessary unless you change the domain.
• If your DNS provider lacks ALIAS/ANAME, route apex traffic through a third‑party CDN that can terminate HTTPS and forward to <project>.readthedocs.io.
• Changing the custom domain after a build triggers a new rebuild.
• Only domains that match the project’s canonical domain are accepted; mismatched domains cause redirects to the canonical URL.