Adding a Custom HTTPS Domain to Read the Docs: Minimal Design and Checks

Problem

You want your documentation to be reachable at a domain you control (e.g., docs.example.com) with a valid HTTPS certificate, but you do not want to manage TLS termination or certificate renewal yourself.

Takeaway

Read the Docs (RTFD) can provision and renew a Let’s Encrypt certificate for any custom domain that points to its hostname via a CNAME record. The smallest viable setup is: add the domain in the project settings, create a CNAME to <project>.readthedocs.io, and enable HTTPS in the UI. No extra infrastructure is required.

Requirements

• Ability to edit DNS records for the domain (typically admin access to your DNS provider).
• Owner or maintainer rights on the RTFD project to modify domain settings.
• The project must have at least one successful build (so there is content to serve).

Smallest Suitable Design

1. In the RTFD project UI, go to Admin → Domains and add your custom domain (e.g., docs.example.com).
2. In your DNS provider, create a CNAME record:
1. Name/Host: docs (or the subdomain you chose).
2. Target: myproject.readthedocs.io (replace myproject with your RTFD project slug).
3. TTL: a low value (e.g., 300 s) while testing, then raise to a normal value (e.g., 3600 s).
3. Return to RTFD and toggle the HTTPS switch for the domain. RTFD will request a Let’s Encrypt certificate; this usually completes within a few minutes.

Trust and Data Boundaries

• DNS control: You retain full authority over the domain name and its records.
• Certificate issuance: RTFD acts as the certificate applicant; Let’s Encrypt validates domain control via the CNAME‑to‑RTFD challenge, so the chain is trusted by browsers.
• Content hosting: The built documentation remains on RTFD’s CDN; no files leave the RTFD environment.

Operational Checks

1. DNS resolution: Run dig +short docs.example.com CNAME (or use nslookup) from any machine with network access. Expected answer: myproject.readthedocs.io.
2. SSL handshake: Execute

   openssl s_client -connect docs.example.com:443 -servername docs.example.com

   and verify:
   • The certificate’s Subject Alternative Name includes docs.example.com.
   • The Issuer is "Let’s Encrypt Authority X3" (or the current Let’s Encrypt issuer).
   • No handshake errors are reported.
3. Build status: Check the RTFD UI (Builds tab) or call the API: GET https://readthedocs.org/api/v3/projects/myproject/builds/?limit=1. The latest build should be success and active.
4. End‑to‑end: curl -I https://docs.example.com/ should return 200 OK and a strict-transport-security header.

Failure Modes

• DNS misconfiguration: Missing CNAME, pointing to a wrong host, or using an A record instead of CNAME will cause RTFD to fail domain validation and the HTTPS switch will stay off.
• Let’s Encrypt renewal issues: Rare, but if you exceed Let’s Encrypt rate limits (e.g., >50 certificates per week for the same domain) RTFD cannot renew; browsers will see an expired cert after 90 days.
• Build failures: If the latest commit fails to build, RTFD continues to serve the last successful build; users may see outdated content.

Conditions That Would Prompt a Redesign

• Need for internal‑only documentation (no public internet exposure) → consider self‑hosted static site on S3 or an internal web server.
• Requirement for custom authentication (e.g., SSO, LDAP) → host docs on a private server where you can enforce auth.
• Custom build steps unsupported by RTFD’s default Docker image (e.g., needing specific system packages) → use a custom Docker image via RTFD’s "Advanced settings" or migrate to a self‑hosted CI/CD pipeline.

Concrete Example

Project slug: my‑library. Desired domain: docs.mycompany.com.

1. In RTFD: Admin → Domains → Add docs.mycompany.com → Save.
2. DNS (e.g., Cloudflare):
   • Type: CNAME
   • Name: docs
   • Target: my-library.readthedocs.io
   • TTL: 300 s (temporarily)
3. After DNS propagates, return to RTFD and enable HTTPS for the domain.
4. Verification:

   dig +short docs.mycompany.com CNAME
   # → my-library.readthedocs.io.
   
   openssl s_client -connect docs.mycompany.com:443 -servername docs.mycompany.com 2>/dev/null | openssl x509 -noout -text | grep -A2 "Subject Alternative Name"
   # → DNS:docs.mycompany.com
   
   curl -s -o /dev/null -w "%{http_code}" https://docs.mycompany.com/
   # → 200
   

Limitations and Practical Verification

• DNS changes may take up to 48 hours to propagate globally; during this window the custom domain may be unreachable or serve an expired cert. Mitigate by lowering TTL before the change and monitoring with dig.
• RTFD’s free plan does not guarantee HTTP/2; if HTTP/2 is required, verify your plan’s feature list or consider upgrading.
• Let’s Encrypt rate limits: 50 certificates per week per registered domain. If you manage many subdomains, consolidate them under a single SAN certificate (RTFD does this automatically per domain, so each subdomain counts separately).
• To confirm the setup is working after propagation, run the verification commands above and check that the strict-transport-security header is present.

Rollback (State‑Changing Operation)

Adding a custom domain modifies DNS and RTFD configuration. To revert:

1. In RTFD: Admin → Domains → select the domain → Delete.
2. In your DNS provider: remove the CNAME record for the subdomain (or change it back to its previous value).
3. Wait for DNS propagation; the domain will no longer resolve to RTFD, and any existing TLS certificate will expire unused.