docs: Adds Tutor as a supported installation method (#1952)

* docs: Adds Tutor as a supported installation method

Adds Tutor as a supported (and recommended) installation method starting
on Lilac, consolidates references to the Native Installation, while also
integrating the gist of the "Open edX Installation Options" wiki page.

* docs: tweaks for pr #1952

* docs: link directly to the named releases page

Co-authored-by: Ned Batchelder <ned@edx.org>
(cherry picked from commit fd2e401)

en_us/install_operations/source/installation/devstack.rst

@@ -14,7 +14,8 @@ convenient. For example, `nginx`_ and `gunicorn`_ are disabled in Devstack;
 Devstack uses Django's ``runserver`` instead.
 
 You can install the Open edX developer stack (just known as **Devstack**)
-or the Open edX analytics developer stack (**Analytics Devstack** or just **Analyticstack**).
+or the Open edX analytics developer stack (**Analytics Devstack** or just
+**Analyticstack**).
 
 =====================
 Devstack Installation

en_us/install_operations/source/installation/index.rst

@@ -1,19 +1,74 @@
 .. _Installing and Starting the Open edX Platform:
 
-######################################################
+#############################################
 Installing and Starting the Open edX Platform
-######################################################
+#############################################
 
 This section provides information about options for installing and
 starting the Open edX platform.
-There is one production-like installation option, referred to as Native,
-and a pair of development environment installation options
-which install the Open edX software using Docker.
+
+We've tried to simplify the installation by providing a small number of
+options, prepackaged to varying degrees. Before installing Open edX, you have
+two decisions to make:
+
+* **Version**: What version of the code do you want?
+* **Method**: How do you want to install it?
+
+*******************
+1. Choose a version
+*******************
+
+There are two possibilities for the version to install:
+
+* **Master** is the latest version of the code, newer even than what is running
+  on edx.org.
+* A **Release** is a version of the code marked and tested for wide use.  These
+  are named alphabetically for trees: Juniper, Koa, Lilac, etc.
+
+You should choose master only if you will be modifying the code and
+contributing it back, or if you need a feature or fix that is newer than the
+latest Open edX release.  If you aren't planning to contribute changes, and you
+don't need the absolute latest code, use the latest official Open edX release.
+Details of the releases are on the `Open edX Named Releases page`_.
+
+********************************
+2. Choose an installation method
+********************************
+
+The currently supported installation methods are:
+
+* **Tutor**: (New for Lilac) A community-supported Docker-based environment
+  suited for both production and development.
+* **Native**: (Deprecated in Lilac, to be removed in Maple) Provides a
+  production-ready installation on an Ubuntu machine of your own, using an
+  Ansible playbook.
+* **Devstack**: A development environment based on Docker; useful if you want
+  to modify Open edX code locally.
+
+Broadly speaking, the different methods all install the same collection of
+software.  Which method you choose depends on what you'll be doing with your
+installation:
+
+* If you will be running a production installation on a **Release**, use
+  **Tutor** or **Native**.
+* If you want a production-like installation for testing a **Release**, you
+  should also use either **Tutor** or **Native**.
+* If you want a production-like installation for testing **Master**, you
+  should use **Native**.
+* If you will be modifying code on **Master**, use **Devstack**.
+
+Note that all of them require some foundational skills:
+
+* Comfort with your chosen operating system.
+* Using the command line to perform tasks.
+* Some ability to diagnose and solve problems with system software.
+
+You can find more details on each of the methods below:
 
 .. toctree::
    :maxdepth: 2
 
-   prerequisites
+   tutor
    native_installation
    devstack
 

en_us/install_operations/source/installation/native_installation.rst

@@ -1,8 +1,8 @@
-.. _Lilac Native Open edX platform Installation:
+.. _Lilac Open edX Native Installation:
 
-###########################################
-Lilac Native Open edX Platform Installation
-###########################################
+##################################
+Lilac Open edX Native Installation
+##################################
 
 This page describes how to install the Open edX Lilac release on a single Ubuntu 20.04 64-bit server from scratch.
 
@@ -14,7 +14,27 @@ This page describes how to install the Open edX Lilac release on a single Ubuntu
 For older releases
 ******************
 
-For Juniper and earlier, see `Legacy Open edX Native Installation`_ .
+For Koa and earlier, see `Koa Open edX Native Installation`_ .
+
+*************
+Prerequisites
+*************
+
+This installation option require an understanding of the following items:
+
+* Basic terminal usage. If you are using a Mac computer, see
+  `Introduction to the Mac OS X Command Line`_.
+
+* Diagnosing and fixing failures may involve many different technologies and
+  skills. It will help to know:
+
+  - The basics of how Python web applications are built, installed, and
+    deployed.
+
+  - How to manage a Linux system, including supervisor.
+
+  - The basics of configuration management and automation.  This installation
+    method uses `Ansible`_ to automate the process.
 
 *******************
 Server Requirements

en_us/install_operations/source/installation/tutor.rst

@@ -0,0 +1,15 @@
+.. _Open edX Tutor Installation:
+
+###########################
+Open edX Tutor Installation
+###########################
+
+Tutor is a supported installation method as of Lilac.  Because we expect Tutor
+to completely replace the `Open edX Native Installation` installation for
+Maple, we recommend its use for any new deployment of Lilac and above.
+
+In order to avoid unnecessary duplication of information, please refer to the
+official `Tutor`_ documentation for both details on how to use it and
+differences from the Native Installation.
+
+.. include:: ../../../links/links.rst

en_us/install_operations/source/platform_releases/koa.rst

@@ -36,7 +36,7 @@ Installing the Koa Release
 **************************
 
 You can install the Open edX Koa release using either
-`devstack`_ or the `Open edX Koa Native Installation`_ instructions.
+`devstack`_ or the `Open edX Native Installation`_ instructions.
 
 Koa releases have git tag names like ``open-release/koa.1``.
 The available names are detailed on the `Open edX Named Releases page`_.
@@ -128,7 +128,7 @@ release to another, follow the instructions in `devstack`_.
 Upgrading a Native Installation
 ===============================
 
-If you installed Open edX using the `Open edX Koa Native Installation`_, you can
+If you installed Open edX using the `Open edX Native Installation`_, you can
 upgrade from one Koa release to another by re-running those steps using
 your desired Koa tag as the new value for ``OPENEDX_RELEASE``.
 

en_us/install_operations/source/platform_releases/lilac.rst

@@ -35,8 +35,8 @@ find the most up-to-date git tag for Lilac on the
 Installing the Lilac Release
 ****************************
 
-You can install the Open edX Lilac release using either
-`devstack`_ or the `Open edX Lilac Native Installation`_ instructions.
+You can install the Open edX Lilac release using the `Open edX Installation`_
+instructions.
 
 Lilac releases have git tag names like ``open-release/lilac.1``.
 The available names are detailed on the `Open edX Named Releases page`_.
@@ -53,7 +53,7 @@ To move and upgrade your Koa data onto a Lilac installation, follow these
 steps.
 
 #. Be sure that your Koa installation is on the latest commit from
-   ``open-release/juniper.master``. This ensures that your database is fully
+   ``open-release/koa.master``. This ensures that your database is fully
    migrated and ready for upgrade to Lilac.
 
 #. Stop all services on the Koa machine.
@@ -128,7 +128,7 @@ release to another, follow the instructions in `devstack`_.
 Upgrading a Native Installation
 ===============================
 
-If you installed Open edX using the `Open edX Lilac Native Installation`_, you can
+If you installed Open edX using the `Open edX Native Installation`_, you can
 upgrade from one Lilac release to another by re-running those steps using
 your desired Lilac tag as the new value for ``OPENEDX_RELEASE``.
 

en_us/links/links.rst

@@ -86,6 +86,9 @@
 
 .. _Open edX Named Releases page: https://edx.readthedocs.io/projects/edx-developer-docs/en/latest/named_releases.html
 
+.. _Open edX Installation: https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/installation/
+
+.. _Open edX Native Installation: https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/installation/native_installation.html
 
 .. GitHub Links
 
@@ -235,9 +238,7 @@
 
 .. _Legacy Open edX Native Installation: https://openedx.atlassian.net/wiki/x/g4G6C
 
-.. _Open edX Koa Native Installation: https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/installation/native_installation.html
-
-.. _Open edX Lilac Native Installation: https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/installation/native_installation.html
+.. _Koa Open edX Native Installation: https://openedx.atlassian.net/wiki/x/lIJjdQ
 
 .. _edX Feature Flags: https://openedx.atlassian.net/wiki/spaces/OpenDev/pages/34734726/edX+Feature+Flags
 
@@ -410,6 +411,8 @@
 
 .. _Webpack: https://webpack.js.org/
 
+.. _Tutor: https://docs.tutor.overhang.io/
+
 .. Release Notes
 
 

en_us/open_edx_release_notes/source/koa.rst

@@ -109,7 +109,7 @@ Administrator Experiences
 Dependency updates
 ------------------
 
-These dependencies were upgraded for the `Open edX Koa Native Installation`_:
+These dependencies were upgraded for the `Open edX Native Installation`_:
 
 - Ubuntu was upgraded from 16.04 to 20.04.