diff --git a/docs/Makefile b/docs/Makefile index 98c5737..8b29286 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 7fb93f1..a96abcd 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 `__: v18.06.0+ -- `Docker Compose `__: v1.22.0+ + - `Docker `__: v18.06.0+ + - `Docker Compose `__: 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 ` 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 `. +* 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. - -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 ` 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 `__ 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 `__ 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 `. -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 `. +.. _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 `_. 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 `__. 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 03b7af3..6dca48a 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 fd87f8b..74d5522 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 `_. -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 ` 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 `. Then, create the Tutor project root and move your data:: mkdir -p "$(tutor config printroot)" mv config.json data/ "$(tutor config printroot)" -`Download `_ 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 3d1a52d..ca5f2af 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 `__-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 `__. In addition, a couple additional filters are added by Tutor:: +In Tutor, templates are `Jinja2 `__-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 `__. 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 `. * ``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 `__). 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 d266649..19b1ee9 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 `. \ 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