docs: move installation instructions from wiki to readthedocs #1948

Squashed from three original commits:

docs: add the native installation page to docs and reorganized installation index page

(cherry picked from commit 9ea7240)

docs: added legacy to reference title to old installation wiki and added changes to redirect to current and legacy native installation steps

(cherry picked from commit 194ebfd)

docs: add 'for old releases' subsection to display hyperlink to legacy native installation wiki

(cherry picked from commit 598aedb)

en_us/install_operations/source/installation/devstack.rst

@@ -0,0 +1,48 @@
+.. _Devstack install:
+
+********
+Devstack
+********
+
+Devstack is a deployment of the Open edX platform within a set of Docker
+containers designed for local development. Running the Open edX platform
+locally allows you to discover and fix system configuration issues early in
+development.
+
+Devstack simplifies certain production settings to make development more
+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**).
+
+=====================
+Devstack Installation
+=====================
+
+To run either Devstack or Analytics Devstack, see the `devstack`_ repository.
+
+You can run Devstack or Analytics Devstack on Linux or macOS. See the
+`Docker`_ downloads page for information about the operating systems and
+architectures on which you can run Docker.
+Devstack using `Docker for Windows`_ has not been tested and it is not
+supported.
+For more information about Docker, see the `Docker documentation`_.
+
+==================
+Analytics Devstack
+==================
+
+Some users might want to develop Analytics features on their instance of the
+Open edX platform. Because of the large number of dependencies needed to
+develop extensions to Analytics, edX has created a modified version of Devstack
+that provides the services and tools needed to modify the
+Open edX Analytics Pipeline.
+
+For information on running Analytics Stack,
+see the `Getting Started on Analytics`_ document in the devstack repository.
+
+Insights and the Analytics Data API are currently not included in
+Analytics Devstack.
+
+.. include:: ../../../links/links.rst

en_us/install_operations/source/installation/index.rst

@@ -10,77 +10,11 @@ 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.
 
-*************
-Prerequisites
-*************
+.. toctree::
+   :maxdepth: 2
 
-These installation options 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 these things.
-
-  - 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.  We use `Ansible`_
-    to automate the installation process.
-
-*******************
-Native Installation
-*******************
-
-The Native installation installs the Open edX software on your own Ubuntu 16.04
-machine in a production-like configuration. Details are at the `Open edX
-Native Installation`_ page on the edX wiki.
-
-********
-Devstack
-********
-
-Devstack is a deployment of the Open edX platform within a set of Docker 
-containers designed for local development. Running the Open edX platform 
-locally allows you to discover and fix system configuration issues early in 
-development.
-
-Devstack simplifies certain production settings to make development more
-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**).
-
-=====================
-Devstack Installation
-=====================
-
-To run either Devstack or Analytics Devstack, see the `devstack`_ repository.
-
-You can run Devstack or Analytics Devstack on Linux or macOS. See the
-`Docker`_ downloads page for information about the operating systems and
-architectures on which you can run Docker.
-Devstack using `Docker for Windows`_ has not been tested and it is not
-supported.
-For more information about Docker, see the `Docker documentation`_.
-
-==================
-Analytics Devstack
-==================
-
-Some users might want to develop Analytics features on their instance of the
-Open edX platform. Because of the large number of dependencies needed to
-develop extensions to Analytics, edX has created a modified version of Devstack
-that provides the services and tools needed to modify the
-Open edX Analytics Pipeline.
-
-For information on running Analytics Stack,
-see the `Getting Started on Analytics`_ document in the devstack repository.
-
-Insights and the Analytics Data API are currently not included in
-Analytics Devstack.
+   prerequisites
+   native_installation
+   devstack
 
 .. include:: ../../../links/links.rst

en_us/install_operations/source/installation/native_installation.rst

@@ -0,0 +1,120 @@
+.. _Lilac/Koa Native Open edX platform Installation:
+
+###################################################################
+Lilac/Koa Native Open edX platform Installation
+###################################################################
+
+This page describes how to install the Open edX Koa release on a single Ubuntu 20.04 64-bit server from scratch.
+
+
+.. warning:: Installing and running an Open edX instance is not simple.  We **strongly recommend** that you use a `service provider <https://open.edx.org/get-started/>`_ to run the software for you.  They have free trials that make it easy to get started: https://open.edx.org/get-started/
+
+    Only proceed with these installation steps if you are comfortable with installing and diagnosing complex Linux systems.
+
+****************
+For old releases
+****************
+For Juniper and earlier, see `Legacy Open edX Native Installation`_ .
+
+*******************
+Server Requirements
+*******************
+The following server requirements will be fine for supporting hundreds of registered students on a single server.
+
+*Note: This will run MySQL, Memcache, Mongo, nginx, and all of the Open edX services (LMS, Studio, Forums, ORA, etc) on a single server. In production configurations we recommend that these services run on different servers and that a load balancer be used for redundancy. Setting up production configurations is beyond the scope of this wiki page.*
+
+* **Ubuntu 20.04 amd64** (oraclejdk required). It may seem like other versions of Ubuntu will be fine, but they are not.
+* **Minimum 8GB of memory**
+* **At least one 2.00GHz CPU or EC2 compute unit**
+* **Minimum 25GB of free disk, 50GB recommended for production servers**
+
+For hosting in Amazon we recommend an t2.large with at least a 50Gb EBS volume, see https://aws.amazon.com/ec2/pricing. Community Ubuntu AMIs have 8GB on the root directory, make sure to expand it before installing.
+
+*************************
+Installation instructions
+*************************
+
+.. warning::
+    * These instructions will potentially **destroy the server** they are run on, you should only do them on a freshly installed virtual machine. But if you still want to have a try to re-install the Open edX stack on the same server, please see `Re install Open edX in Ubuntu 12.04`_ for some issues you may face and how to fix them.
+    * **By default ssh will only allow key based authentication**. Please setup key based SSH logins or modify the configuration repo to allow for password based SSH logins before running Ansible.
+
+.. note::
+    * If you are running your services behind a proxy, please see `EdX Proxy Instructions`_
+
+===============
+Prep the server
+===============
+Launch your Ubuntu 20.04 64-bit server and log in to it as a user that has full sudo privileges.
+
+Update your Ubuntu package sources:
+
+.. code-block:: shell
+
+    $ sudo apt-get update -y
+    $ sudo apt-get upgrade -y
+    $ sudo reboot
+
+==============
+Installation
+==============
+You will run a few scripts to accomplish the installation. Please read the contents of the scripts before running this to ensure you are aware of everything they will do: they are quite extensive. The scripts require that the running user can run commands as root via sudo.
+
+#. **Set** the OPENEDX_RELEASE variable. You choose the version of software by setting the OPENEDX_RELEASE variable before running the commands. See the `Open edX Named Releases page`_ for the tags you can use.
+
+    .. code-block:: shell
+
+        $ export OPENEDX_RELEASE=the-tag/you-want-to-install
+
+#. **Create** a config.yml file.  This file specifies the hostname (and port, if needed) of the LMS and Studio.   Create a file in the current directory named **config.yml**, like this:
+
+    .. code-block:: yaml
+
+        # The host names of LMS and Studio. Don't include the "https://" part:
+        EDXAPP_LMS_BASE: "online.myeducation.org"
+        EDXAPP_CMS_BASE: "studio.online.myeducation.org"
+
+    Your LMS host and Studio host must either be the same hostname (on different ports), or Studio must be a subdomain of the LMS.  If you need a different configuration, you may need to also set EDXAPP_SESSION_COOKIE_DOMAIN.
+
+    **NOTE** : Open edX and edX are registered trademarks.  You **may not** use "openedx." or "edx." as subdomains when naming your site. For more details, see the `edX Trademark Policy`_.  Here are some examples of **unacceptable domain names**:
+
+        * **DON'T:** openedx.yourdomain.org
+        * **DON'T:** edx.yourdomain.org
+        * **DON'T:** openedxyourdomain.org
+        * **DON'T:** yourdomain-edx.com
+
+#. **Bootstrap** the Ansible installation:
+
+    .. code-block:: shell
+
+        $ wget https://raw.githubusercontent.com/edx/configuration/$OPENEDX_RELEASE/util/install/ansible-bootstrap.sh -O - | sudo -E bash
+
+    .. warning:: DO NOT activate a virtualenv at this point, even if the ansible-bootstrap script tells you to.
+
+#. **Randomize** passwords. If this is to replace an older installation, copy your my-passwords.yml file from that installation.  If this is a new installation:
+
+    .. code-block:: shell
+
+        $ wget https://raw.githubusercontent.com/edx/configuration/$OPENEDX_RELEASE/util/install/generate-passwords.sh -O - | bash
+
+    **IMPORTANT**: Be sure to save the generated my-passwords.yml in a safe place. If you ever need to access your services directly, you'll need these credentials. More details of password generation and other security measures are here: `How to Override Default Configuration Passwords and Verify Exposed Services`_.
+
+#. **Install** the Open edX software.  This can take some time, perhaps an hour. (Note: for Ginkgo and earlier, this file was called sandbox.sh):
+
+    .. code-block:: shell
+
+        $ wget https://raw.githubusercontent.com/edx/configuration/$OPENEDX_RELEASE/util/install/native.sh -O - | bash
+
+#. **Finish** configuring your server, for example to set the LMS_ROOT_URL setting, before everything will work properly. The `Managing Open edX Tips and Tricks`_ page may be useful.
+
+
+************************************
+Do not upgrade!
+************************************
+Some Open edX components are outdated. If you see a message suggesting that you update something manually, **don't do it** -- something is probably relying on the outdated software remaining at that older version. Specifically:
+
+* Ubuntu may alert you that a newer version of Ubuntu available when you SSH in to your server, and may suggest that you run :code:`do-release-upgrade` to upgrade to that newer version. **Don't do it.**
+* Pip may alert you that there is a newer version of pip available, and may suggest that you run :code:`pip install --upgrade pip` to install it. **Don't do it.**
+
+If you arbitrarily upgrade parts of Open edX software, *things will break*. Instead, you should submit a pull request to change the line in the Open edX project where that specific version of the software is defined. All pull requests need to be reviewed before they can be merged, and part of the review process will consist of testing the full platform with the updated software, identifying any breakages, and fixing them as part of the pull request.
+
+.. include:: ../../../links/links.rst

en_us/install_operations/source/installation/prerequisites.rst

@@ -0,0 +1,23 @@
+.. _Prerequisites:
+
+*************
+Prerequisites
+*************
+
+These installation options 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 these things.
+
+  - 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.  We use `Ansible`_
+    to automate the installation process.
+
+.. include:: ../../../links/links.rst

en_us/install_operations/source/platform_releases/ficus.rst

@@ -74,7 +74,7 @@ release to another, run the following commands in the host operating system:
 Upgrading a Native Installation
 ===============================
 
-If you installed Open edX using the `Open edX Native Installation`_, you can
+If you installed Open edX using the `Legacy Open edX Native Installation`_, you can
 upgrade from one Ficus release to another by re-running those steps using your
 desired Ficus tag as the new value for ``OPENEDX_RELEASE``.
 

en_us/install_operations/source/platform_releases/ginkgo.rst

@@ -176,7 +176,7 @@ release to another, run the following commands in the host operating system:
 Upgrading a Native Installation
 ===============================
 
-If you installed Open edX using the `Open edX Native Installation`_, you can
+If you installed Open edX using the `Legacy Open edX Native Installation`_, you can
 upgrade from one Ginkgo release to another by re-running those steps using your
 desired Ginkgo tag as the new value for ``OPENEDX_RELEASE``.
 

en_us/install_operations/source/platform_releases/hawthorn.rst

@@ -48,7 +48,7 @@ Installing the Hawthorn Release
 *******************************
 
 You can install the Open edX Hawthorn release using either 
-`devstack`_ or the `Open edX 
+`devstack`_ or the `Legacy Open edX 
 Native Installation`_ instructions.
 
 Hawthorn releases have git tag names like ``open-release/hawthorn.1``.
@@ -157,7 +157,7 @@ release to another, follow the instructions in `devstack`_.
 Upgrading a Native Installation
 ===============================
 
-If you installed Open edX using the `Open edX Native Installation`_, you can
+If you installed Open edX using the `Legacy Open edX Native Installation`_, you can
 upgrade from one Hawthorn release to another by re-running those steps using
 your desired Hawthorn tag as the new value for ``OPENEDX_RELEASE``.
 

en_us/install_operations/source/platform_releases/ironwood.rst

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

en_us/install_operations/source/platform_releases/juniper.rst

@@ -36,7 +36,7 @@ Installing the Juniper Release
 *******************************
 
 You can install the Open edX Juniper release using either
-`devstack`_ or the `Open edX Native Installation`_ instructions.
+`devstack`_ or the `Legacy Open edX Native Installation`_ instructions.
 
 Juniper releases have git tag names like ``open-release/juniper.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 Native Installation`_, you can
+If you installed Open edX using the `Legacy Open edX Native Installation`_, you can
 upgrade from one Juniper release to another by re-running those steps using
 your desired Juniper tag as the new value for ``OPENEDX_RELEASE``.
 

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 Installation`_ instructions.
+`devstack`_ or the `Open edX Koa 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 Native Installation`_, you can
+If you installed Open edX using the `Open edX Koa 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

@@ -36,7 +36,7 @@ Installing the Lilac Release
 ****************************
 
 You can install the Open edX Lilac release using either
-`devstack`_ or the `Open edX Lilac Installation`_ instructions.
+`devstack`_ or the `Open edX Lilac Native 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`_.
@@ -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 Native Installation`_, you can
+If you installed Open edX using the `Open edX Lilac 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``.