diff --git a/docs/_release_description.md b/docs/_release_description.md index 1a7c653cced194077c11c372d9ff7b43b4c8b7d3..0e34d97c6fa73a15ac1697b207375418b11474e2 100644 --- a/docs/_release_description.md +++ b/docs/_release_description.md @@ -5,4 +5,4 @@ Tutor can be installed simply by downloading the compiled binaries: See the [installation docs](https://docs.tutor.overhang.io/install.html) for more installation options and instructions. -## Features +## Changes diff --git a/docs/install.rst b/docs/install.rst index 22ea9ef49621463115ed18d3d8b37c742fcf624e..7fb93f102c55c0530cafe21b97344995a8cb112a 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -14,12 +14,15 @@ The only prerequisite for running this is a working Docker installation. You'll .. 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. +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. 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. +.. 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. + At least 9Gb of disk space is required. Also, the host running the containers should be a 64 bit platform. (images are not built for i386 systems) diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 2887eb46e71181bf4a8141ef7e14f550087f1bf5..5958b6311b4c6ca7cb7ec4759d6967d200726546 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -49,20 +49,28 @@ This is not an error with Tutor, but with your Docker installation. This is freq If the above command does not work, you should fix your Docker installation. Some people will suggest to run Docker as root, or with ``sudo``; **do not do this**. Instead, what you should probably do is to add your user to the "docker" group. For more information, check out the `official Docker installation instructions <https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user>`__. -Help! The Docker containers are eating all my RAM/CPU/CHEESE ------------------------------------------------------------- +.. _migrations_killed: -You can identify which containers are consuming most resources by running:: +"Running migrations... Killed!" / "Command failed with status 137: docker-compose" +---------------------------------------------------------------------------------- - docker stats +Open edX requires at least 4 GB RAM, in particular to run the SQL migrations. If the ``tutor local quickstart`` command dies after displaying "Running migrations", you most probably need to buy more memory or add swap to your machine. On Docker for Mac OS, by default, containers are allocated at most 2 GB of RAM. 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. -.. _migrations_killed: +If migrations were killed halfway, there is a good chance that the MySQL database is in a state that is hard to recover from. The easiest way to recover is simply to delete all the MySQL data and restart the quickstart process. After you have allocated more memory to the Docker daemon, run:: + + tutor local stop + sudo rm -rf "$(tutor config printroot)/data/mysql" + tutor local quickstart + +.. warning:: + THIS WILL ERASE ALL YOUR DATA! Do not run this on a production instance. This solution is only viable for new Open edX installations. -"Running migrations... Killed!" -------------------------------- +Help! The Docker containers are eating all my RAM/CPU/CHEESE +------------------------------------------------------------ -Older versions of Open edX required at least 4 GB RAM, in particular to run the Open edX SQL migrations. On Docker for Mac, by default, containers are allocated at most 2 GB of RAM. On Mac OS, if the ``tutor local quickstart`` command dies after displaying "Running migrations", you most probably need to increase the allocated RAM. Follow `these instructions from the official Docker documentation <https://docs.docker.com/docker-for-mac/#advanced>`_. +You can identify which containers are consuming most resources by running:: + docker stats "Build failed running pavelib.servers.lms: Subprocess return code: 1" -----------------------------------------------------------------------