Read the Docs automatic HTTPS for custom domains and where it breaks down

The problem you actually want solved

You have documentation built on Read the Docs and a stakeholder request for docs.example.com instead of project.readthedocs.io. The useful takeaway is that Read the Docs will automatically provision and renew a Let’s Encrypt TLS certificate once a custom domain is verified via DNS, so you do not manage certbot or upload certificates. The automation is convenient, but it is constrained by DNS record type, tier limits, and the fact that renewal depends on continued DNS correctness.

How automatic HTTPS is triggered

Read the Docs uses Let’s Encrypt to generate and renew TLS certificates for any custom domain linked to a project. HTTPS is enabled by default once the domain is verified; the platform handles DNS validation and certificate issuance behind the scenes.

When a domain is verified, the edge serving your docs also enables HTTP/2 for that host. That is a side effect of the HTTPS termination on Read the Docs’ CDN and improves parallel loading of static assets without extra configuration.

Verifying a custom domain with DNS

Verification is a two-sided change: project settings and DNS.

In the Read the Docs project UI, open Admin > Advanced Settings and add the custom domain, for example docs.example.com. The UI shows the target you should point DNS at, typically .readthedocs.io. The domain appears as Pending until verification succeeds.

At your DNS provider, create a record that allows Read the Docs to prove control. The platform requires a CNAME or ALIAS record pointing the host to the provided target. Some providers do not support ALIAS for apex domains, in which case you must use a subdomain like docs.example.com with a CNAME.

After DNS propagates, Read the Docs re-checks the record. When verification succeeds the domain shows Verified and the HTTPS badge turns green in the project dashboard. The HTTPS endpoint is then served immediately.

Worked example with placeholders

Project slug: mylib-docs. Desired host: docs.example.com.

1. In Read the Docs, Admin > Advanced Settings > Custom domains, add docs.example.com.
2. Note the target shown, e.g. mylib-docs.readthedocs.io.
3. In DNS, create CNAME docs.example.com → mylib-docs.readthedocs.io. No special permissions are required beyond DNS edit access for the zone.
4. Wait for verification. The dashboard lists the domain as Verified and the HTTPS badge is green.

To check the result from a local terminal with network access:

curl -vI https://docs.example.com

Expected checks are a successful TLS handshake and a certificate whose subject matches docs.example.com. In a browser, inspect the certificate to confirm the chain is valid and the protocol is TLS 1.2 or newer. A manual check such as SSL Labs’ SSL Test can confirm HTTPS and HTTP/2 support, but results depend on current provider data.

What the automation does not cover

Let’s Encrypt certificates are valid for 90 days. Renewal is attempted weekly by Read the Docs. Misconfigured DNS, a removed CNAME, or a provider that changes the target can cause renewal failures and temporary service interruption.

Limitations to plan for:

• Free tier supports automatic HTTPS only for public domains. Private or internal domains require a paid plan or self-hosting.
• The free tier limits the number of custom domains per project; exceeding the limit requires an upgrade.
• The automatic process does not support custom Subject Alternative Names beyond the primary domain. Additional subdomains must be added individually in project settings.
• If the project moves from a public to a private Git repository, custom domain verification must be re-checked; otherwise the HTTPS endpoint may become inaccessible.

These constraints mean the automation is best suited for public documentation on standard DNS.

Monitoring renewal health

Because renewal is automatic, the practical risk is silent failure. Check the project’s Builds page for certificate renewal status and any Certificate renewal failed alerts. The dashboard HTTPS badge turning from green to a warning state is the first visible signal.

An actionable closing checklist: verify the domain shows Verified, confirm HTTPS is reachable via a TLS check, and review the Builds page periodically for renewal alerts. If you change DNS providers or move the project to a private repo, re-verify the domain immediately.