Skip to content

Rework custom domains docs #6844

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Apr 13, 2020
Merged

Rework custom domains docs #6844

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
cd6e773
Rework custom domains docs
stsewd Apr 1, 2020
e286b49
Remove from index
stsewd Apr 1, 2020
2845430
Apply suggestions from code review
stsewd Apr 7, 2020
135a8bf
Suggestions from review
stsewd Apr 7, 2020
67c8b63
Long line
stsewd Apr 7, 2020
738b6b2
Allow to link to a specific tab
stsewd Apr 7, 2020
79b937e
Add note about proxy ssl
stsewd Apr 13, 2020
8ebded6
Deprecate proxy ssl
stsewd Apr 13, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 0 additions & 39 deletions docs/commercial/custom_domains.rst
View file
Open in desktop

This file was deleted.

1 change: 0 additions & 1 deletion docs/commercial/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,6 @@ Advertising-free
.. toctree::
:caption: Additional commercial features

custom_domains
organizations
sharing
analytics
133 changes: 75 additions & 58 deletions docs/custom_domains.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,85 +1,98 @@
Custom Domains
==============

.. note:: These directions are for projects hosted on our community site.
If you want to setup a custom domain on `Read the Docs for Business <https://readthedocs.com/>`_,
please read our :doc:`commercial documentation <commercial/custom_domains>`.
Once a project is imported into Read the Docs,
by default it's hosted under a subdomain on one of our domains.
If you need a custom domain, see :ref:`custom_domains:custom domain support`.

Read the Docs supports a number of custom domains for your convenience. Shorter URLs make everyone happy, and we like making people happy!
Subdomain support
-----------------

Subdomain Support
------------------
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 your documentation.
A good example is https://pip.readthedocs.io
For :doc:`/commercial/index` the subdomain looks like ``<slug>.readthedocs-hosted.com``.

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
.. note::

.. note:: If you have an old project that has an underscore (_) in the name, it will use a subdomain with a hyphen (-).
`RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ has more information on valid subdomains.
If you have an old project that has an underscore (_) in the name,
it will use a subdomain with a hyphen (-).
`RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ has more information on valid subdomains.

Custom Domain Support
---------------------

You can also host your documentation from your own domain by adding a domain to
your project:
Custom domain support
---------------------

* 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.
You can also host your documentation from your own domain.

.. 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.

Using pip as an example, https://pip.pypa.io resolves, but is hosted on our infrastructure.
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.

As another example, fabric's dig record looks like this::
.. tabs::

-> dig docs.fabfile.org
...
;; ANSWER SECTION:
docs.fabfile.org. 7200 IN CNAME readthedocs.io.
.. tab:: Read the Docs Community

- Add a CNAME record in your DNS that points the domain to ``readthedocs.io``
- Go the :guilabel:`Admin` tab of your project
- Click on :guilabel:`Domains`
- Enter your domain and click on :guilabel:`Add`

Custom Domain SSL
-----------------
By default, we provide a validated SSL certificate for the domain.
This service is generously provided by Cloudflare.
The SSL certificate issuance can take about one hour,
you can see the status of the certificate on the domain page in your project.

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.
For example, https://pip.pypa.io resolves, but is hosted on our infrastructure.
As another example, fabric's dig record looks like this:

After configuring your custom domain on Read the Docs,
you can see the status of the certificate on the domain page in your project
admin dashboard (:guilabel:`Domains` > :guilabel:`Edit Domain`).
.. prompt:: bash $, auto

If your domain has configured CAA records, please do not forget to include
Cloudflare CAA entries, see their `Certification Authority Authorization (CAA)
FAQ <https://support.cloudflare.com/hc/en-us/articles/115000310832-Certification-Authority-Authorization-CAA-FAQ>`_.
$ dig docs.fabfile.org
...
;; ANSWER SECTION:
docs.fabfile.org. 7200 IN CNAME readthedocs.io.

.. note::
.. 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.
Point the CNAME to ``readthedocs.io``, with no subdomain, and re-request a certificate
by saving the domain in the project admin (:guilabel:`Domains` >
:guilabel:`Edit Domain`).
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.
Follow the new setup to have a SSL certificate.

If you change the CNAME record, the SSL certificate issuance can take about
one hour.
**Notes for Cloudflare users**

.. important::
- If your domain has configured CAA records, please do not forget to include
Cloudflare CAA entries, see their `Certification Authority Authorization (CAA)
FAQ <https://support.cloudflare.com/hc/en-us/articles/115000310832-Certification-Authority-Authorization-CAA-FAQ>`__.

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``.
- 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`_.

For more details, see this `previous issue`_.
.. _this previous issue: https://github.com/readthedocs/readthedocs.org/issues/4395

.. _previous issue: https://github.com/readthedocs/readthedocs.org/issues/4395
.. tab:: Read the Docs for Business

- Go the :guilabel:`Admin` tab of your project
- Click on :guilabel:`Domains`
- Enter your domain and click on :guilabel:`Add`
- Follow the steps shown on the domain page

By default, we provide a validated SSL certificate for the domain.
The SSL certificate issuance can take a few days,
you can see the status of the certificate on the domain page in your project.

.. note::

Some older setups configured a CNAME record pointing to ``<organization-slug>.users.readthedocs.com``.
These domains will continue to resolve.

Proxy SSL
---------
Expand Down Expand Up @@ -115,7 +128,11 @@ An example nginx configuration for pip would look like:
}
}

rtfd.org
---------
Other domains
-------------

You can also use ``rtfd.io`` and ``rtfd.org`` for short URLs for projects hosted on the community version of Read the Docs.
For example:

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`.
- https://pip.rtfd.io redirects to pip's documentation page
- https://rtfd.io/projects/pip redirects to pip's dashboard page