mirror of
https://github.com/ChristianLight/tutor.git
synced 2025-01-11 09:35:06 +00:00
Better installation docs
This commit is contained in:
Régis Behmo
parent
325deb4210
commit
390c39fa19
@ -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
|
||||
|
||||
@ -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.
|
||||
* 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.
|
||||
|
||||
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
|
||||
|
||||
|
||||
@ -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
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -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,18 +240,26 @@ 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
|
||||
|
||||
|
||||
@ -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 %}
|
||||
...
|
||||
|
||||
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user