Securing Your Docs: How Read the Docs Custom Domain HTTPS Works

Why HTTPS on a Custom Domain Matters

When you expose your API or library documentation to the world, you want visitors to trust the connection. A custom domain that serves content over HTTPS gives that confidence and keeps search engines happy. Read the Docs (RTD) offers a built‑in way to map a domain to your project and automatically provision a TLS certificate from Let’s Encrypt. The result is a secure, branded URL without the hassle of certificate renewal.

Getting Started: Enable the Feature in RTD

1. Navigate to your project’s settings. In the RTD web UI, click the project name, then select Advanced Settings → Custom Domains.
2. Add your domain. Enter the fully‑qualified domain you want to use, e.g. docs.example.com, and click Add domain. RTD will validate DNS ownership immediately.
3. Wait for validation. The build log shows entries like Domain validation successful and Certificate issued once the DNS record resolves to one of RTD’s IP addresses.

DNS: Pointing Your Domain to RTD

RTD accepts either an A record or a CNAME record. The choice depends on your DNS provider and whether you want to keep the IP static.

• A record (recommended for static IPs): docs.example.com A 185.199.108.153 (placeholder IP – RTD publishes the current IP list in the docs).
• CNAME record (simpler when RTD’s IP changes): docs.example.com CNAME docs.readthedocs.io.

Make sure the record is publicly resolvable; private or internal DNS will prevent Let’s Encrypt from validating the domain.

Worked Example

Suppose you own example.com and want docs.example.com to host the docs for your my-lib project.

# DNS configuration (example.com provider)
# Add a CNAME
docs.example.com.  IN  CNAME  docs.readthedocs.io.

# Or add an A record
docs.example.com.  IN  A  185.199.108.153

After updating the DNS, go back to RTD, add docs.example.com in the Custom Domains section, and wait for the build log to confirm success. Once the certificate is issued, visiting https://docs.example.com will show the docs served over HTTPS with a Let’s Encrypt certificate.

What Happens Behind the Scenes?

• RTD contacts Let’s Encrypt via the ACME protocol to prove ownership of the domain. The ACME challenge succeeds only if the DNS record points to RTD’s servers.
• Let’s Encrypt issues a 90‑day certificate. RTD automatically renews it before expiration, so you never need to touch the certificate again.
• All HTTP requests to the domain are redirected to HTTPS by default, ensuring secure access even if a user types http://.

Trade‑offs and Limitations

• DNS propagation. Changes can take up to 48 hours to become globally visible. During this window, HTTPS may fail with a certificate error.
• Let’s Encrypt limits. An account can request up to 50 new certificates per week. Adding many custom domains in a short period may hit this ceiling.
• Free tier inactivity pause. Projects on the free tier are automatically paused after 3 months of inactivity. Pausing removes custom domain configuration; you must re‑enable the domain after unpausing.
• Public DNS requirement. Private or internal DNS records will not satisfy Let’s Encrypt, so the certificate will not be issued.
• Domain ownership. If the domain is already in use by another service, certificate issuance may fail due to conflicting CNAME/A records.

How to Verify the Setup

1. Open a browser and navigate to https://docs.example.com.
2. Click the lock icon in the address bar and inspect the certificate. It should be issued to docs.example.com and signed by Let's Encrypt Authority X3 (or ISRG Root X1).
3. Check the RTD build log for a line such as Domain validation successful – Certificate issued. If you see Domain validation failed, double‑check the DNS record.

Actionable Take‑aways

• Use a CNAME record to avoid future IP changes.
• Keep your DNS record unchanged; any modification will break renewal.
• Verify the certificate in a browser and confirm the RTD logs show a successful validation.
• If you’re on the free tier, monitor inactivity and unpause the project if you’re about to hit the 3‑month pause.

With these steps you can confidently expose your documentation on a branded, secure domain, letting users focus on learning your API rather than worrying about security warnings.