2018-10-03 10:30:55 +00:00
Custom Domains
==============
2011-01-11 04:37:24 +00:00
2018-10-03 10:30:55 +00:00
.. note :: These setup directions are for our community site.
If you want to setup a custom domain under our `commercial hosting`_ ,
please read our :ref: `commercial documentation <commercial/custom_domains:Custom Domains>` .
2018-06-19 17:48:44 +00:00
2018-10-03 10:30:55 +00:00
.. _commercial hosting: https://readthedocs.com
2018-06-19 17:48:44 +00:00
2017-06-11 09:25:09 +00:00
Read the Docs supports a number of custom domains for your convenience. Shorter URLs make everyone happy, and we like making people happy!
2011-01-11 04:37:24 +00:00
Subdomain Support
------------------
2018-06-19 17:48:44 +00:00
Every project has a subdomain that is available to serve its documentation. If you go to `` <slug>.readthedocs.io `` , it should show you the latest version of documentation. A good example is https://pip.readthedocs.io
2011-01-11 04:37:24 +00:00
2016-06-02 19:19:19 +00:00
.. note :: If you have an old project that has an underscore (_) in the name, it will use a subdomain with a hyphen (-).
2014-07-11 06:03:51 +00:00
`RFC 1035 <http://tools.ietf.org/html/rfc1035> `_ has more information on valid subdomains.
2014-01-18 14:24:57 +00:00
2018-09-13 16:42:13 +00:00
Custom Domain Support
---------------------
2011-01-11 04:37:24 +00:00
2018-09-13 16:42:13 +00:00
You can also host your documentation from your own domain by adding a domain to
your project:
2016-01-30 01:48:24 +00:00
2018-09-13 16:42:13 +00:00
* Add a CNAME record in your DNS that points the domain to: `` readthedocs.io ``
* Add a project domain in the :guilabel: `Domains` project admin page for your project.
2016-01-30 01:48:24 +00:00
2018-09-13 16:42:13 +00:00
.. note ::
We don't currently support pointing subdomains or naked domains to a project
using `` A `` records. It's best to point a subdomain, `` docs.example.com ``
for example, using a CNAME record.
2017-03-09 23:01:40 +00:00
2018-07-24 20:34:09 +00:00
Using pip as an example, https://pip.pypa.io resolves, but is hosted on our infrastructure.
2011-01-11 04:37:24 +00:00
2017-03-09 23:01:40 +00:00
As another example, fabric's dig record looks like this::
2011-03-15 06:28:02 +00:00
-> dig docs.fabfile.org
...
;; ANSWER SECTION:
2016-04-27 23:14:36 +00:00
docs.fabfile.org. 7200 IN CNAME readthedocs.io.
2016-01-30 01:48:24 +00:00
2018-09-13 16:42:13 +00:00
Custom Domain SSL
-----------------
2013-12-16 15:55:05 +00:00
2018-07-24 20:34:09 +00:00
By default, when you setup a custom domain to host documentation at Read the Docs,
we will attempt to provision a domain validated SSL certificate for the domain.
This service is generously provided by Cloudflare.
2018-08-13 20:03:41 +00:00
After configuring your custom domain on Read the Docs,
2018-09-13 16:42:13 +00:00
you can see the status of the certificate on the domain page in your project
admin dashboard (:guilabel: `Domains` > :guilabel: `Edit Domain` ).
2018-08-13 20:03:41 +00:00
If your domain has configured CAA records, please do not forget to include
2018-08-10 12:54:24 +00:00
Cloudflare CAA entries, see their `Certification Authority Authorization (CAA)
FAQ <https://support.cloudflare.com/hc/en-us/articles/115000310832-Certification-Authority-Authorization-CAA-FAQ>`_.
2018-07-24 20:34:09 +00:00
.. note ::
Some older setups configured a CNAME record pointing to `` readthedocs.org ``
or another variation. While these continue to resolve,
they do not yet allow us to acquire SSL certificates for those domains.
2019-03-01 15:37:47 +00:00
Point the CNAME to `` readthedocs.io `` , with no subdomain, and re-request a certificate
2018-09-13 16:42:13 +00:00
by saving the domain in the project admin (:guilabel: `Domains` >
:guilabel: `Edit Domain` ).
2018-07-24 20:34:09 +00:00
2018-09-13 16:42:13 +00:00
If you change the CNAME record, the SSL certificate issuance can take about
one hour.
2018-08-07 21:47:09 +00:00
2018-07-24 20:34:09 +00:00
.. important ::
Due to a limitation, a domain cannot be proxied on Cloudflare
to another Cloudflare account that also proxies.
This results in a "CNAME Cross-User Banned" error.
In order to do SSL termination, we must proxy this connection.
If you don't want us to do SSL termination for your domain --
**which means you are responsible for the SSL certificate** --
then set your CNAME to `` cloudflare-to-cloudflare.readthedocs.io ``
instead of `` readthedocs.io `` .
For more details, see this `previous issue`_ .
.. _previous issue: https://github.com/rtfd/readthedocs.org/issues/4395
Proxy SSL
---------
If you would prefer to do your own SSL termination
on a server you own and control,
you can do that although the setup is a bit more complex.
2013-12-16 15:55:05 +00:00
2018-07-24 20:34:09 +00:00
Broadly, the steps are:
2013-12-16 22:46:26 +00:00
2013-12-16 15:55:05 +00:00
* Have a server listening on 443 that you control
2018-07-24 20:34:09 +00:00
* Procure an SSL certificate for your domain and provision it
and the private key on your server.
2013-12-16 15:55:05 +00:00
* Add a domain that you wish to point at Read the Docs
* Enable proxying to us, with a custom `` X-RTD-SLUG `` header
An example nginx configuration for pip would look like:
.. code-block :: nginx
:emphasize-lines: 9
server {
2018-07-24 20:34:09 +00:00
server_name pip.pypa.io;
2013-12-16 15:55:05 +00:00
location / {
2016-04-27 23:14:36 +00:00
proxy_pass https://pip.readthedocs.io:443;
2013-12-16 15:55:05 +00:00
proxy_set_header Host $http_host;
2016-04-09 00:35:42 +00:00
proxy_set_header X-Forwarded-Proto https;
2013-12-16 15:55:05 +00:00
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Scheme $scheme;
proxy_set_header X-RTD-SLUG pip;
proxy_connect_timeout 10s;
proxy_read_timeout 20s;
}
}
2011-01-11 04:37:24 +00:00
2014-01-18 14:21:09 +00:00
rtfd.org
2011-01-11 04:37:24 +00:00
---------
2018-07-24 20:34:09 +00:00
You can also use `rtfd.io` and `rtfd.org` for short URLs for Read the Docs. For example, https://pip.rtfd.io redirects to its documentation page. Any use of `rtfd.io` or `rtfd.org` will simply be redirected to `readthedocs.io` .