Better installation docs

docs/Makefile

@@ -8,4 +8,4 @@ browse:
 	sensible-browser _build/html/index.html
 
 watch: html browse
-	while true; do inotifywait -e modify *.rst ../*.rst conf.py; $(MAKE) html; done
+	while true; do inotifywait -e modify *.rst */*.rst ../*.rst conf.py; $(MAKE) html; done

docs/install.rst

@@ -3,32 +3,33 @@
 Install Tutor
 =============
 
+.. _requirements:
+
 Requirements
 ------------
 
-The only prerequisite for running this is a working Docker installation. You'll need both the ``docker`` and ``docker-compose`` commands in your system ``$PATH``. Follow the instructions from the official documentation:
+* Supported OS: Tutor runs on any 64-bit, UNIX-based system. It was also reported to work on Windows.
+* Required software:
 
-- `Docker <https://docs.docker.com/engine/installation/>`__: v18.06.0+
+    - `Docker <https://docs.docker.com/engine/installation/>`__: v18.06.0+
-- `Docker Compose <https://docs.docker.com/compose/install/>`__: v1.22.0+
+    - `Docker Compose <https://docs.docker.com/compose/install/>`__: v1.22.0+
 
 .. warning::
     Do not attempt to simply run ``apt-get install docker docker-compose`` on older Ubuntu platforms, such as 16.04 (Xenial), as you will get older versions of these utilities.
 
-Note that the production web server container will bind to port 80 and 443, so if there a web server is running on the same server (Apache or Nginx, for instance), it should be stopped prior to running Tutor. Check the section on :ref:`how to setup a web proxy <web_proxy>` for a workaround.
+* Ports 80 and 443 should be open. If other web services run on these ports, check the section on :ref:`how to setup a web proxy <web_proxy>`.
+* Hardware:
 
-With Tutor, Open edX can run on any platform that supports Docker, including Mac OS and Windows. Tutor was tested under various versions of Ubuntu and Mac OS.
+    - Minimum configuration: 4 Gb RAM, 2 CPU, 8 Gb disk space
-
+    - Recommended configuration: 8 Gb RAM, 4 CPU, 25 Gb disk space
-At a minimum, the server running the containers should have 4 Gb of RAM. With less memory, the deployment procedure might crash during migrations (see the :ref:`troubleshooting <migrations_killed>` section) and the platform will be unbearably slow.
 
 .. note::
-    On Mac OS, by default, containers are allocated 2 GB of RAM, which is not enough. You should follow `these instructions from the official Docker documentation <https://docs.docker.com/docker-for-mac/#advanced>`__ to allocate at least 4-5 Gb to the Docker daemon.
+    On Mac OS, by default, containers are allocated 2 GB of RAM, which is not enough. You should follow `these instructions from the official Docker documentation <https://docs.docker.com/docker-for-mac/#advanced>`__ to allocate at least 4-5 Gb to the Docker daemon. If the deployment fails because of insufficient memory during database migrations, check the :ref:`relevant section in the troubleshooting guide <migrations_killed>`.
 
-At least 9Gb of disk space is required.
+.. _install_binary:
 
-Also, the host running the containers should be a 64 bit platform. (images are not built for i386 systems)
+Direct binary download
-
+----------------------
-Direct binary downloads
------------------------
 
 The latest binaries can be downloaded from https://github.com/overhangio/tutor/releases. From the command line:
 
@@ -36,6 +37,8 @@ The latest binaries can be downloaded from https://github.com/overhangio/tutor/r
 
 This is the simplest and recommended installation method for most people. Note however that you will not be able to use custom plugins with this pre-compiled binary. The only plugins you can use with this approach are those that are already bundled with the binary: see the :ref:`existing plugins <existing_plugins>`.
 
+.. _install_source:
+
 From source
 -----------
 
@@ -55,10 +58,10 @@ Installing from a local clone of the repository::
 
 .. _cloud_install:
   
-Cloud deployment
+Zero-click AWS installation
-----------------
+---------------------------
 
-Tutor can be launched on Amazon Web Services very quickly with the `official Tutor AMI <https://aws.amazon.com/marketplace/pp/B07PV3TB8X>`_. Shell access is not even required, as all configuration will happen through the Tutor web user interface. For detailed installation instructions, we recommend watching the following video:
+Tutor can be launched on Amazon Web Services very quickly with the `official Tutor AMI <https://aws.amazon.com/marketplace/pp/B07PV3TB8X>`__. Shell access is not required, as all configuration will happen through the Tutor web user interface. For detailed installation instructions, we recommend watching the following video:
 
 .. youtube:: xtXP52qGphA
 

docs/k8s.rst

@@ -125,8 +125,8 @@ In particular, the `tutor k8s start` command restarts and reconfigures all servi
 
 All non-persisting data will be deleted, and then re-created.
 
-Recipes
+Guides
--------
+------
 
 Updating docker images
 ~~~~~~~~~~~~~~~~~~~~~~

docs/local.rst

@@ -5,7 +5,7 @@ Local deployment
 
 This method is for deploying Open edX locally on a single server, where docker images are orchestrated with `docker-compose <https://docs.docker.com/compose/overview/>`_.
 
-In the following, environment and data files will be generated in a user-specific project folder which will be referred to as the "**project root**". On Linux, the default project root is ``~/.local/share/tutor``. An alternative project root can be defined by passing the ``--root=...`` option to the ``tutor`` command, or define the ``TUTOR_ROOT=...`` environment variable::
+In the following, environment and data files will be generated in a user-specific project folder which will be referred to as the "**project root**". On Linux, the default project root is ``~/.local/share/tutor``. An alternative project root can be defined by passing the ``--root=...`` option to the ``tutor`` command, or defining the ``TUTOR_ROOT=...`` environment variable::
     
     tutor --root=/path/to/tutorroot run ...
     # Or equivalently:
@@ -168,8 +168,8 @@ You can then view the portainer UI at `http://localhost:9000 <http://localhost:9
 
 Among many other things, you'll be able to view the logs for each container, which is really useful.
 
-Recipes
+Guides
--------
+------
 
 .. _web_proxy:
 
@@ -240,19 +240,27 @@ Of course, your settings should be compatible with the docker installation. You
 Upgrading from earlier versions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Upgrading from v3+
+******************
+
+Just upgrade Tutor using your :ref:`favorite installation method <install>` and run quickstart again::
+
+    tutor local quickstart
+
+Upgrading from v1 or v2
+***********************
+
 Versions 1 and 2 of Tutor were organized differently: they relied on many different ``Makefile`` and ``make`` commands instead of a single ``tutor`` executable. To migrate from an earlier version, you should first stop your platform::
 
     make stop
 
-Then, create the Tutor project root and move your data::
+Then, install Tutor using one of the :ref:`installation methods <install>`. Then, create the Tutor project root and move your data::
 
     mkdir -p "$(tutor config printroot)"
     mv config.json data/ "$(tutor config printroot)"
 
-`Download <https://github.com/overhangio/tutor/releases>`_ the latest stable release of Tutor, uncompress the file and place the ``tutor`` executable in your path.
+Finally, launch your platform with::
-
+    
-Finally, start your platform again::
-
     tutor local quickstart
 
 Backups/Migrating to a different server

docs/plugins/api.rst

@@ -144,14 +144,14 @@ Example::
 
 With the above declaration, you can store plugin-specific templates in the ``templates/myplugin`` folder next to the ``plugin.py`` file.
 
-In Tutor, templates are `Jinja2 <https://jinja.palletsprojects.com/en/2.11.x/>`__-formatted files that will be rendered in the Tutor environment (the ``$(tutor config printroot)/env`` folder) when running ``tutor config save``. The environment files are overwritten every time the environment is saved. Plugin developers can create templates that make use of the built-in `Jinja2 API <https://jinja.palletsprojects.com/en/2.11.x/api/>`__. In addition, a couple additional filters are added by Tutor::
+In Tutor, templates are `Jinja2 <https://jinja.palletsprojects.com/en/2.11.x/>`__-formatted files that will be rendered in the Tutor environment (the ``$(tutor config printroot)/env`` folder) when running ``tutor config save``. The environment files are overwritten every time the environment is saved. Plugin developers can create templates that make use of the built-in `Jinja2 API <https://jinja.palletsprojects.com/en/2.11.x/api/>`__. In addition, a couple additional filters are added by Tutor:
     
 * ``common_domain``: Return the longest common name between two domain names. Example: ``{{ "studio.demo.myopenedx.com"|common_domain("lms.demo.myopenedx.com") }}`` is equal to "demo.myopenedx.com".
 * ``list_if``: In a list of ``(value, condition)`` tuples, return the list of ``value`` for which the ``condition`` is true.
 * ``patch``: See :ref:`patches <plugin_patches>`.
 * ``random_string``: Return a random string of the given length composed of ASCII letters and digits. Example: ``{{ 8|random_string }}``.
 * ``reverse_host``: Reverse a domain name (see `reference <https://en.wikipedia.org/wiki/Reverse_domain_name_notation>`__). Example: ``{{ "demo.myopenedx.com"|reverse_host }}`` is equal to "com.myopenedx.demo".
-* ``walk_templates``: Iterate recursively over the templates of the given folder. For instance: 
+* ``walk_templates``: Iterate recursively over the templates of the given folder. For instance::
 
     {% for file in "apps/myplugin"|walk_templates %}
     ...

docs/quickstart.rst

@@ -22,4 +22,4 @@ Yes :) This is what happens when you run ``tutor local quickstart``:
 
 The whole procedure should require less than 10 minutes, on a server with a good bandwidth. Note that your host environment will not be affected in any way, since everything runs inside docker containers. Root access is not even necessary.
 
-There's a lot more to Tutor than that! To understand what Tutor does and how it works, take a look at the :ref:`getting started guide <gettingstarted>`.
+There's a lot more to Tutor than that! To learn more about what you can do with Tutor and Open edX, check out the :ref:`whatnext` section. If the quickstart installation method above somehow didn't work for you, check out the :ref:`troubleshooting` guide.