diff --git a/docs/user/commercial/index.rst b/docs/user/commercial/index.rst index eb98b394bcf..8107d0f6ef8 100644 --- a/docs/user/commercial/index.rst +++ b/docs/user/commercial/index.rst @@ -4,35 +4,22 @@ Business hosting .. this page is currently moving towards becoming "About Read the Docs for Business" .. rather than an index of features. -We offer |com_brand| for building and hosting commercial documentation. +We offer |com_brand| for building and hosting documentation for private repositories. -Our commercial solutions are provided as a set of subscriptions that are paid and managed through an online interface. -In order to get started quickly and easily, a `trial option `__ is provided free of charge. +In order to get started quickly, you can start a `free 30-day trial `__ to test out the platform. .. seealso:: - `Read the Docs website: Features `__ - A high-level overview of platform features is available on our website, and the + `Read the Docs features `__ + A high-level overview of platform features, and the `pricing page `__ has a feature breakdown by subscription level. - `Read the Docs website: Company `__ - Information about the company running Read the Docs, including our mission, team, and community. - - Commercial documentation solutions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In addition to providing the same features as |org_brand|, commercial subscriptions to Read the Docs add additional features and run on separate infrastructure. -.. figure:: /img/community_in_business.png - :align: center - :scale: 50% - - Read the Docs for Community and Business are a combined system: - All features developed for community benefit the business solution, and most solutions developed for business users - are implemented for the community. - The following list is a high-level overview of the areas covered by |com_brand|. If you want a full feature breakdown, please refer to our `pricing page `__. @@ -42,13 +29,6 @@ Private repositories and private documentation to restrict documentation access to certain users, or to share private documentation via private hyperlinks. -Additional build resources - Do you have a complicated build process that uses large amounts - of CPU, memory, disk, or networking resources? - Commercial subscriptions offer more resources - which results in faster documentation build times. - We can also customize builders, such as with a GPU or multiple CPUs. - Priority support We have a dedicated support team that responds to support requests during business hours. diff --git a/docs/user/commercial/organizations.rst b/docs/user/commercial/organizations.rst index 746d939ae88..c486da13f0c 100644 --- a/docs/user/commercial/organizations.rst +++ b/docs/user/commercial/organizations.rst @@ -3,24 +3,20 @@ Organizations .. include:: /shared/admonition-rtd-business.rst -In this article, we explain how the *organizations* feature on Read the Docs allows you to manage access to your projects. +In this article, we explain how the *organizations* feature allows you to manage access to your projects. On |com_brand|, your account is linked to an *organization*. Organizations allow you to define both individual and team permissions for your projects. -In this article, we use ACME Corporation as our example organization. -ACME has a few people inside their organization, -some who need full access and some who just need access to one project. - .. seealso:: :doc:`/guides/manage-read-the-docs-teams` A step-by-step guide to managing teams. -Member types -~~~~~~~~~~~~ +Important objects +~~~~~~~~~~~~~~~~~ -* **Owners** -- Get full access to both view and edit the Organization and all Projects -* **Members** -- Get access to a subset of the Organization projects +* **Owners** -- Get full access to both view and edit the organization and all projects +* **Members** -- Get access to a subset of the organization projects * **Teams** -- Where you give members access to a set of projects. The best way to think about this relationship is: @@ -35,10 +31,10 @@ The best way to think about this relationship is: Team types ~~~~~~~~~~ -You can create two types of Teams: +You can create two types of teams: -* **Admins** -- These teams have full access to administer the projects in the team. They are allowed to change all of the settings, set notifications, and perform any action under the **Admin** tab. -* **Read Only** -- These teams are only able to read and search inside the documents. +* **Admin** -- Team members have full access to administer the projects assigned to the team. Members are allowed to change all of the settings, set notifications, and perform any action under the :guilabel:`Admin` tab for each project. +* **Read Only** -- Team members are only able to read the documentation of each project, and not able to change anything about each project. Example ~~~~~~~ diff --git a/docs/user/commercial/privacy-level.rst b/docs/user/commercial/privacy-level.rst index b9db95e4f92..25dd1afa743 100644 --- a/docs/user/commercial/privacy-level.rst +++ b/docs/user/commercial/privacy-level.rst @@ -1,20 +1,44 @@ -.. TODO: This is a super weird page.. +Privacy Levels +-------------- -:orphan: +.. include:: /shared/admonition-rtd-business.rst -Project privacy level ---------------------- +Privacy levels allow you to set the visibility of your project and its versions. +This allows you to specify what information is available to the public and what is private. +Privacy can be controlled at the level of the project and each version, +and nothing more granular (eg. specific directories or URLs) can be controlled. -.. include:: /shared/admonition-rtd-business.rst +Project privacy +~~~~~~~~~~~~~~~ By default, only users that belong to your organization can see the dashboard of your project and its builds. -If you want users outside your organization and anonymous users to be able to see the dashboard of your project, +If you want users outside your organization to be able to see the dashboard of your project, and the build output of *public versions* you can set the privacy level of your project to ``Public``. -You can administer this in your :term:`dashboard` by navigating to :menuselection:`Admin --> Settings` +You can set the project privacy level in your :term:`dashboard` by navigating to :menuselection:`Admin --> Settings` and changing :guilabel:`Privacy level` to `Public`. -.. note:: +**Making a project public doesn't give access to any versions.** +So if you want all your versions to be accessible, +you need to configure those to be `Public` as well. + +Version privacy +~~~~~~~~~~~~~~~ + +Each version of your documentation can be set to either `Public` or `Private`. +This allows you to control who can see the documentation for a specific version. + +* Documentation for public versions is visible to everyone. +* Private versions are available only to people who have permissions to see them. + They will not display on any list view, and will 404 when visited by people without viewing permissions. + If you want to share your docs temporarily, see :doc:`/commercial/sharing`. + +You can set the privacy level for each version in your :term:`dashboard` by navigating to :menuselection:`Versions --> $version ... Drop down --> Configure version` and changing :guilabel:`Privacy level` to `Public`. + +Recommended workflow +~~~~~~~~~~~~~~~~~~~~ - To control access to the documentation itself, - see :ref:`versions:Version states`. +We recommend defaulting everything to private, +and only making versions public when you are ready to share them with the world. +This allows you to work on your documentation in private, +and only share it when you are ready. diff --git a/docs/user/commercial/sharing.rst b/docs/user/commercial/sharing.rst index 069c8948f33..28ccc5eacb0 100644 --- a/docs/user/commercial/sharing.rst +++ b/docs/user/commercial/sharing.rst @@ -3,37 +3,36 @@ Sharing private documentation .. include:: /shared/admonition-rtd-business.rst -You can share your project with users outside of your company: +Sharing private documentation is useful for giving quick access to your documentation to users outside of your organization. +It allows you to share specific projects or versions of a project with users who don't have access to your organization. -* by sending them a *secret link*, -* by giving them a *password*. +Common sharing use cases include: -These methods will allow them to view specific projects or versions of a project inside your organization. +* Sharing a project with contractors or partners. +* Sharing documentation for your product only to specific customers. +* Embedding documentation in a SaaS application dashboard. -Additionally, you can use a HTTP Authorization Header. -This is useful to have access from a script. - -Enabling sharing ----------------- +Creating a shared item +---------------------- * Go into your project's :guilabel:`Admin` page and click on :guilabel:`Sharing`. * Click on :guilabel:`New Share` * Select access type (secret link, password, or HTTP header token), - add an expiration date and a *Description* so you remember who you're sharing it with. + add an expiration date and a *Description* to help with managing access in the future. * Check ``Allow access to all versions?`` if you want to grant access to all versions, or uncheck that option and select the specific versions you want grant access to. * Click :guilabel:`Save`. * Get the info needed to share your documentation with other users: - * If you have selected secret link, copy the link that is generated - * In case of password, copy the link and password - * For HTTP header token, you need to pass the ``Authorization`` header in your HTTP request. + * **Secret link:** copy the link that is generated + * **Password:** copy the link and password + * **HTTP header token**: Copy the token, and then pass the ``Authorization`` header in your HTTP request. * Give that information to the person who you want to give access. .. note:: - You can always revoke access in the same panel. + You can always revoke access by removing the sharing item in this page. Sharing methods --------------- @@ -41,7 +40,7 @@ Sharing methods Secret link *********** -Once the person you send the link to clicks the link, +Once the person you send the link to clicks it, they will have access to the documentation while their browser window is open. If you want to link to a specific page, @@ -58,7 +57,7 @@ Password Once the person you send the link to clicks on the link, they will see an *Authorization required* page asking them for the password you -generated. When the user enters the password, they will have access to +generated. When the user enters the password, they will gain access to view your project. .. tip:: @@ -77,12 +76,12 @@ Token Authorization ~~~~~~~~~~~~~~~~~~~ You need to send the ``Authorization`` header with the token on each HTTP request. -The header has the form ``Authorization: Token ``. +The header has the form ``Authorization: Token ``. For example: .. prompt:: bash $ - curl -H "Authorization: Token 19okmz5k0i6yk17jp70jlnv91v" https://docs.example.com/en/latest/example.html + curl -H "Authorization: Token $TOKEN" https://docs.example.com/en/latest/example.html Basic Authorization ~~~~~~~~~~~~~~~~~~~ @@ -92,4 +91,73 @@ For example: .. prompt:: bash $ - curl --url https://docs.example.com/en/latest/example.html --user '19okmz5k0i6yk17jp70jlnv91v:' + curl --url https://docs.example.com/en/latest/example.html --user '$TOKEN:' + + +Typical sharing configurations +------------------------------ + +There are a few common ways to architect sharing, +with trade offs between them, +and you should choose the one that best fits your use case. + +Bulk passwords +************** + +If you want to limit access to a group of users, +you can create a password for each user, +and then share the password with them. +This allows users to access the documentation directly, +but requires more management on your end. +Any time a new user needs access or you want to remove access, +you will need to generate a new password for them. + +Authenticated redirect +********************** + +If you want to share documentation with a group of users, +you need to authenticate those users against your own system first. +The simplest way to do this is to create an authenticated redirect on your site, +which then redirects to the Read the Docs :ref:`Secret link`. + +This should require very little customization, +and will ensure that only authenticated users can access the documentation. +The downside is that users won't be able to access the documentation directly from a bookmark, +and will have to go through your site first. + +Authenticated proxy +******************* + +If you want a more transparent experience for your users, +you can create a proxy that authenticates users against your system, +and then proxies the request to Read the Docs. +This is more complex to set up, +but will allow users to access the documentation directly from a bookmark, + +This approach would use a :ref:`HTTP Authorization Header` to authenticate users, +and would be configured in your proxy server. + +Proxy example +------------- + +Below is an example of how to configure Nginx to proxy requests to Read the Docs while adding the token in the `Authorization` header. + +.. code-block:: nginx + + server { + listen 80; + server_name docs.example.com; + + location / { + proxy_pass https://docs-example.readthedocs-hosted.com; + + # Add Authorization header with the token + proxy_set_header Authorization "Token "; + + # Optionally forward other headers + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } diff --git a/docs/user/index.rst b/docs/user/index.rst index 17724383e61..020874322e5 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -83,11 +83,11 @@ Read the Docs: documentation simplified :hidden: :caption: Business features - /commercial/index /commercial/organizations /commercial/single-sign-on /commercial/sharing /commercial/subscriptions + /commercial/privacy-levels .. toctree:: :maxdepth: 2