diff --git a/docs/Makefile b/docs/Makefile
index 98c573782841be83d6ab4564dca3e4e4f53f7833..8b29286b31c53ef1c5991364c6cdda08b6401f65 100644
--- a/docs/Makefile
+++ b/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
diff --git a/docs/install.rst b/docs/install.rst
index 7fb93f102c55c0530cafe21b97344995a8cb112a..a96abcd35a433dd379bc4d65d62d9dff6209703c 100644
--- a/docs/install.rst
+++ b/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 Compose <https://docs.docker.com/compose/install/>`__: v1.22.0+
+ - `Docker <https://docs.docker.com/engine/installation/>`__: v18.06.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.
-
-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.
+* 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:
-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.
+ - Minimum configuration: 4 Gb RAM, 2 CPU, 8 Gb disk space
+ - Recommended configuration: 8 Gb RAM, 4 CPU, 25 Gb disk space
.. 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 downloads
------------------------
+Direct binary download
+----------------------
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
diff --git a/docs/k8s.rst b/docs/k8s.rst
index 03b7af3fe2a3f2e1fcfa2a757d54888ab98fe1a5..6dca48ab1a1aa407904c87ad9834946ba67a7682 100644
--- a/docs/k8s.rst
+++ b/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
~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/local.rst b/docs/local.rst
index fd87f8b6ef84aa4ce80b38477a15565897dfc0b0..74d5522e45d2db4b5222f3de63e5cb0209d4c093 100644
--- a/docs/local.rst
+++ b/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, start your platform again::
-
+Finally, launch your platform with::
+
tutor local quickstart
Backups/Migrating to a different server
diff --git a/docs/plugins/api.rst b/docs/plugins/api.rst
index 3d1a52d47e9f884e1283738ba68d71321569cd00..ca5f2afb65e746449a03f54c96d807cb9bb8e3a0 100644
--- a/docs/plugins/api.rst
+++ b/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 %}
...
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index d2666492e811b5c59324d7bec7c54735ac5fc98b..19b1ee9c6ded09412f98d8f1ff6a44d34ef0bbb5 100644
--- a/docs/quickstart.rst
+++ b/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>`.
\ No newline at end of file
+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.
\ No newline at end of file