mirror of
https://github.com/ChristianLight/tutor.git
synced 2024-11-16 10:05:18 +00:00
b57c65440a
<rant>I attempted to actually run Tutor with Podman and I was sorely disappointed. The only reliable source of docs that I found concerning the integration with docker-compose is this blog post: https://www.redhat.com/sysadmin/podman-docker-compose There are no other official docs 😓 1. The instructions given in the blog post don't work out of the box. Launching the podman service failed altogether on Ubuntu 20.04 and 20.10. It worked on CentOS 8, but some parameters need to changed, such as the docker socket path. 2. After I got the podman service working, I managed to get an Open edX platform running with tutor, but with the root user. Then, containers complained that they could not write data to the bind-mounted volumes. I attempted to run as a non-root user, and discovered that the podman socket is only readable by root. This should explain why all commands from that blog post are prefixed by sudo. Long story short, I was hoping to update the tutorial. Instead, I'm just moving it for the sake of better organisation. For the life of me, I do not understand why some people would want to run Podman instead of Docker. Bad documentation is an immediate turn-off for me. From my perspective, podman is mostly an overblown marketina stunt.</rant>
132 lines
5.7 KiB
ReStructuredText
132 lines
5.7 KiB
ReStructuredText
.. _install:
|
|
|
|
Install Tutor
|
|
=============
|
|
|
|
.. _requirements:
|
|
|
|
Requirements
|
|
------------
|
|
|
|
* 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+
|
|
|
|
.. 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.
|
|
|
|
* Ports 80 and 443 should be open. If other web services run on these ports, check the tutorial on :ref:`how to setup a web proxy <web_proxy>`.
|
|
* Hardware:
|
|
|
|
- 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. If the deployment fails because of insufficient memory during database migrations, check the :ref:`relevant section in the troubleshooting guide <migrations_killed>`.
|
|
|
|
.. _install_binary:
|
|
|
|
Direct binary download
|
|
----------------------
|
|
|
|
The latest binaries can be downloaded from https://github.com/overhangio/tutor/releases. From the command line:
|
|
|
|
.. include:: download/binary.rst
|
|
|
|
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:
|
|
|
|
Alternative installation methods
|
|
--------------------------------
|
|
|
|
If you would like to inspect the Tutor source code, you are most welcome to install Tutor from `Pypi <https://pypi.org/project/tutor/>`_ or directly from `the Github repository <https://github.com/overhangio/tutor>`_. You will need python >= 3.6 with pip and the libyaml development headers. On Ubuntu, these requirements can be installed by running::
|
|
|
|
sudo apt install python3 python3-pip libyaml-dev
|
|
|
|
Installing from pypi
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. include:: download/pip.rst
|
|
|
|
Installing from source
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
::
|
|
|
|
git clone https://github.com/overhangio/tutor
|
|
cd tutor
|
|
pip install -e .
|
|
|
|
DNS records
|
|
-----------
|
|
|
|
When running a server in production, it is necessary to define `DNS records <https://en.wikipedia.org/wiki/Domain_Name_System#Resource_records>`__ which will make it possible to access your Open edX platform by name in your browser. The precise procedure to create DNS records vary from one provider to the next and is beyond the scope of these docs. You should create a record of type A with a name equal to your LMS hostname (given by ``tutor config printvalue LMS_HOST``) and a value that indicates the IP address of your server. Applications other than the LMS, such as the studio, ecommerce, etc. typically reside in subdomains of the LMS. Thus, you should also create a CNAME record to point all subdomains of the LMS to the LMS_HOST.
|
|
|
|
For instance, the demo Open edX server that runs at http://demo.openedx.overhang.io has the following DNS records::
|
|
|
|
demo.openedx 1800 IN A 172.105.89.208
|
|
*.demo.openedx 1800 IN CNAME demo.openedx.overhang.io.
|
|
|
|
.. _cloud_install:
|
|
|
|
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 required, as all configuration will happen through the Tutor web user interface. For detailed installation instructions, we recommend watching the following video:
|
|
|
|
.. youtube:: xtXP52qGphA
|
|
|
|
.. _upgrade:
|
|
|
|
Upgrading
|
|
---------
|
|
|
|
With Tutor, it is very easy to upgrade to a more recent Open edX or Tutor release. Just install the latest ``tutor`` version (using either methods above) and run the ``quickstart`` command again. If you have :ref:`customised <configuration_customisation>` your docker images, you will have to re-build them prior to running ``quickstart``.
|
|
|
|
``quickstart`` should take care of automatically running the upgrade process. If for some reason you need to *manually* upgrade from an Open edX release to the next, you should run ``tutor local upgrade``. For instance, to upgrade from Koa to Lilac, run::
|
|
|
|
tutor local upgrade --from=koa
|
|
|
|
.. _autocomplete:
|
|
|
|
Autocomplete
|
|
------------
|
|
|
|
Tutor is built on top of `Click <https://click.palletsprojects.com>`_, which is a great library for building command line interface (CLI) tools. As such, Tutor benefits from all Click features, including `auto-completion <https://click.palletsprojects.com/en/8.x/bashcomplete/>`_. After installing Tutor, auto-completion can be enabled in bash by running::
|
|
|
|
_TUTOR_COMPLETE=bash_source tutor >> ~/.bashrc
|
|
|
|
If you are running zsh, run instead::
|
|
|
|
_TUTOR_COMPLETE=zsh_source tutor >> ~/.zshrc
|
|
|
|
After opening a new shell, you can test auto-completion by typing::
|
|
|
|
tutor <tab><tab>
|
|
|
|
Uninstallation
|
|
--------------
|
|
|
|
It is fairly easy to completely uninstall Tutor and to delete the Open edX platforms that is running locally.
|
|
|
|
First of all, stop any locally-running platform::
|
|
|
|
tutor local stop
|
|
tutor dev stop
|
|
|
|
Then, delete all data associated to your Open edX platform::
|
|
|
|
# WARNING: this step is irreversible
|
|
sudo rm -rf "$(tutor config printroot)"
|
|
|
|
Finally, uninstall Tutor itself::
|
|
|
|
# If you installed tutor from source
|
|
pip uninstall tutor
|
|
|
|
# If you downloaded the tutor binary
|
|
sudo rm /usr/local/bin/tutor
|