Install Tutor

Requirements

  • Supported OS: Tutor runs on any 64-bit, UNIX-based system. It was also reported to work on Windows.

  • Required software:

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 section on how to setup a 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 to allocate at least 4-5 Gb to the Docker daemon. If the deployment fails because of insufficient memory during database migrations, check the relevant section in the troubleshooting guide.

Direct binary download

The latest binaries can be downloaded from https://github.com/overhangio/tutor/releases. From the command line:

sudo curl -L "https://github.com/overhangio/tutor/releases/download/v10.1.0/tutor-$(uname -s)_$(uname -m)" -o /usr/local/bin/tutor
sudo chmod 0755 /usr/local/bin/tutor

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 existing plugins.

Alternative installation methods

If you would like to inspect the Tutor source code, you are most welcome to install Tutor from Pypi or directly from the Github repository. 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

pip install tutor-openedx

Installing from source

git clone https://github.com/overhangio/tutor
cd tutor
pip install -e .

Zero-click AWS installation

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:

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 customised 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 Ironwood to Juniper, run:

tutor local upgrade --from=ironwood

Autocomplete

Tutor is built on top of Click, which is a great library for building command line interface (CLI) tools. As such, Tutor benefits from all Click features, including auto-completion. After installing Tutor, auto-completion can be enabled by running:

_TUTOR_COMPLETE=source tutor >> ~/.bashrc

If you are running zsh, run instead:

_TUTOR_COMPLETE=source_zsh tutor >> ~/.zshrc

After opening a new shell, you can test auto-completion by typing:

tutor <tab><tab>

Running Tutor with Podman

You have the option of running Tutor with Podman, instead of the native Docker tools. This has some practical advantages: it does not require a running Docker daemon, and it enables you to run and build Docker images without depending on any system component running root. As such, it is particularly useful for building Tutor images from CI pipelines.

The podman CLI aims to be fully compatible with the docker CLI, and podman-compose is a fully-compatible alias of docker-compose. This means that you can use both together with Tutor, without making any changes to Tutor itself.

Warning

You should not attempt to run Tutor with Podman on a system that already has native docker and docker-compose installed. If you want to switch to podman and podman-compose using the aliases described here, uninstall the native Docker packages first.

Enabling Podman

Podman is supported on a variety of development platforms, see the installation instructions for details.

Once you have installed Podman and its dependencies on the platform of your choice, you’ll need to make sure that its podman binary, usually installed as /usr/bin/podman, is aliased to docker, and is included as such in your system $PATH. On some CentOS and Fedora releases you can install a package named podman-docker to do this for you, but on other platforms you’ll need to take of this yourself.

  • If $HOME/bin is in your $PATH, you can create a symbolic link there:

    ln -s $(which podman) $HOME/bin/docker
    
  • If you want to instead make docker a system-wide alias for podman, you can create your symlink in /usr/local/bin, an action that normally requires root privileges:

    sudo ln -s $(which podman) /usr/local/bin/docker
    

Enabling podman-compose

podman-compose is available as a package from PyPI, and can thus be installed with pip. See its README for installation instructions. Note that if you have installed Tutor in its own virtualenv, you’ll need to run pip install podman-compose in that same virtualenv.

Once installed, you’ll again need to create a symbolic link that aliases docker-compose to podman-compose.

  • If you run Tutor and podman-compose in a virtualenv, create the symlink in that virtualenv’s bin directory: activate the virtualenv, then run:

    ln -s $(which podman-compose) $(dirname $(which podman-compose))/docker-compose
    
  • If you do not, create the symlink in /usr/local/bin, using root privileges:

    sudo ln -s $(which podman-compose) /usr/local/bin/docker-compose
    

Verifying your environment

Once you have configured your symbolic links as described, you should be able to run docker version and docker-compose --help and their output should agree, respectively, with podman version and podman-compose --help.

After that, you should be able to use tutor local, tutor build, and other commands as if you had installed the native Docker tools.

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-openedx

# If you downloaded the tutor binary
sudo rm /usr/local/bin/tutor