diff --git a/docs/cli.rst b/docs/cli.rst new file mode 100644 index 0000000000..78d4ce0f3a --- /dev/null +++ b/docs/cli.rst @@ -0,0 +1,30 @@ +Command line interface (CLI) +============================ + +How do I navigate Tutor's command-line interface? +------------------------------------------------- + +Tutor commands are structured in an easy-to-follow hierarchy. At the top level, there are command trees for image and configuration management:: + + tutor config ... + tutor images ... + +as well as command trees for each mode in which Tutor can run:: + + tutor local ... # Commands for managing a local Open edX deployment. + tutor k8s ... # Commands for managing a Kubernetes Open edX deployment. + tutor dev ... # Commands for hacking on Open edX in development mode. + +Within each mode, Tutor has subcommands for managing that type of Open edX instance. Many of them are common between modes, such as ``launch``, ``start``, ``stop``, ``exec``, and ``logs``. For example:: + + tutor local logs # View logs of a local deployment. + tutor k8s logs # View logs of a Kubernetes-managed deployment. + tutor dev logs # View logs of a development platform. + +Many commands can be further parameterized to specify their target and options, for example:: + + tutor local logs cms # View logs of the CMS container in a local deployment. + tutor k8s logs mysql # View logs of MySQL in Kubernetes-managed deployment. + tutor dev logs lms --tail 10 # View ten lines of logs of the LMS container in development mode. + +And that's it! You do not need to understand Tutor's entire command-line interface to get started. Using the ``--help`` option that's availble on every command, it is easy to learn as you go. For an in-depth guide, you can also explore the :ref:`CLI Reference `. diff --git a/docs/concepts/openedx.rst b/docs/concepts/openedx.rst new file mode 100644 index 0000000000..c996ce6c51 --- /dev/null +++ b/docs/concepts/openedx.rst @@ -0,0 +1,21 @@ +.. _openedx: + +Open edX +======== + +What is Open edX? +----------------- + +`Open edX `_ is a thriving open source project, backed by a great community, for running an online learning platform at scale. Open edX comes with an LMS (Learning Management System) where students access course contents, a CMS (Content Management System) that course staff uses to design courses, and a few other components to provide more services to students, course staff, and platform administrators. + +Should I use Open edX? +---------------------- + +Open edX competitors include `Moodle `__, `Instructure's Canvas `__, `Blackboard's Open LMS `__, as well as a slew of hosted, closed source alternatives. Open edX is the only online learning system that satisfies all following properties: + +* Open source software to avoid vendor lock-in +* Scales well in all directions (number of users and courses) +* Multiple extension points for comprehensive customization +* Modern, intuitive user interface to keep students engaged + +Open edX is a safe bet: it is backed by edX.org, a US-based non-profit that is committed to open source and which runs Open edX to service its millions of learners. With Open edX you can be sure that the features you need will be available. If it's good enough for Harvard, the MIT, or the French government, then it will probably also work for you. diff --git a/docs/concepts/tutor.rst b/docs/concepts/tutor.rst new file mode 100644 index 0000000000..d9fe7d2a46 --- /dev/null +++ b/docs/concepts/tutor.rst @@ -0,0 +1,16 @@ +.. _tutor_concepts: + +Tutor +===== + +What is Tutor? +-------------- + +Tutor is an open source distribution of `Open edX `_. It uses the original code from the various Open edX repositories, such as `edx-platform `_, `cs_comments_service `_, etc. and packages everything in a way that makes it very easy to install, administer and upgrade Open edX. In particular, all services are run inside Docker containers. + +Tutor makes it possible to deploy Open edX locally, with `docker-compose `_ or on an existing `Kubernetes cluster `_. + +What is the purpose of Tutor? +----------------------------- + +To make it possible to deploy, administer and upgrade Open edX anywhere, easily. diff --git a/docs/configuration.rst b/docs/configuration.rst index 272b5ea41a..70963b524a 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -6,9 +6,9 @@ Configuration and customisation Tutor offers plenty of possibilities for platform customisation out of the box. There are two main ways in which the base Open edX installation can be customised: a. Modifying the Tutor :ref:`configuration parameters `. -b. Modifying the :ref:`Open edX docker image ` that runs the Open edX platform. +b. Modifying the :ref:`Open edX docker image ` that runs the Open edX platform. -This section does not cover :ref:`plugin development `. For simple changes, such as modifying the ``*.env.yml`` files or the edx-platform settings, *you should not fork edx-platform or tutor*! Instead, you should create a simple :ref:`plugin for Tutor `. +This section does not cover :ref:`plugin development `. For simple changes, such as modifying the ``*.env.yml`` files or the edx-platform settings, *you should not fork edx-platform or tutor*! Instead, you should create a simple :ref:`plugin for Tutor `. .. _configuration: @@ -293,8 +293,6 @@ If you would like to perform SSL/TLS termination with your own custom certificat .. _customise: -.. _custom_openedx_docker_image: - Kubernetes ~~~~~~~~~~ @@ -313,6 +311,8 @@ This configuration parameter sets the Contact Email. This configuration parameter sets the Platform Name. +.. _custom_openedx_docker_image: + Custom Open edX docker image ---------------------------- @@ -497,3 +497,83 @@ In these situations, you can set ``--docker-arg`` flag in the ``tutor images bui --docker-arg="docker.io/myusername/openedx:mytag" This will result in passing the ``--cache-from`` option with the value ``docker.io/myusername/openedx:mytag`` to the docker build command. + + +Modifying ``edx-platform`` settings +----------------------------------- + +The default settings module loaded by ``edx-platform`` is ``tutor.production`` in production and ``tutor.development`` in development. The folders ``$(tutor config printroot)/env/apps/openedx/settings/lms`` and ``$(tutor config printroot)/env/apps/openedx/settings/cms`` are mounted as ``edx-platform/lms/envs/tutor`` and ``edx-platform/cms/envs/tutor`` inside the docker containers. To modify these settings you must create a plugin that implements one or more of the patch statements in those setting files. See the :ref:`plugin_development_tutorial` tutorial for more information on how to create a plugin. + + +.. _theming: + +Installing a custom theme +------------------------- + +Comprehensive theming is enabled by default, but only the default theme is compiled. `Indigo `__ is a better, ready-to-run theme that you can start using today. + +To compile your own theme, add it to the ``env/build/openedx/themes/`` folder:: + + git clone https://github.com/me/myopenedxtheme.git \ + "$(tutor config printroot)/env/build/openedx/themes/myopenedxtheme" + +The ``themes`` folder should have the following structure:: + + openedx/themes/ + mycustomtheme1/ + cms/ + ... + lms/ + ... + mycustomtheme2/ + ... + +Then you must rebuild the openedx Docker image:: + + tutor images build openedx + +Finally, you should enable your theme with the :ref:`settheme command `. + + +Using Google Mail as an SMTP server +----------------------------------- + +By default, Tutor comes with a simple SMTP server for sending emails. Such a server has an important limitation: it does not implement mailing good practices, such as DKIM or SPF. As a consequence. the emails you send might be flagged as spam by their recipients. Thus, you might want to disable the SMTP server and run your own, for instance using your Google Mail account. + +.. warning:: + Google Mail SMTP servers come with their own set of limitations. For instance, you are limited to sending 500 emails a day. Reference: https://support.google.com/mail/answer/22839 + +You should authorize third-party to access your Google Mail account. In your Google Mail account, select "Manage Account", "Security", and turn on "Less Secure App Access". Check the Google documentation for more information on "less secure apps": https://support.google.com/accounts/answer/6010255 + +Then, check that you can reach the Google Mail SMTP service from your own server:: + + $ telnet smtp.gmail.com 587 + +If you get ``Connected to smtp.gmail.com.`` then it means that you can successfully reach the Google Mail SMTP servers. If not, you will have to reconfigure your firewall. + +To exit the ``telnet`` shell, type ``ctrl+]``, then ``ctrl+d``. + +Then, disable the SMTP server that comes with Tutor:: + + $ tutor config save --set RUN_SMTP=false + +Configure credentials to access your SMTP server:: + + $ tutor config save \ + --set SMTP_HOST=smtp.gmail.com \ + --set SMTP_PORT=587 \ + --set SMTP_USE_SSL=false \ + --set SMTP_USE_TLS=true \ + --set SMTP_USERNAME=YOURUSERNAME@gmail.com \ + --set SMTP_PASSWORD='YOURPASSWORD' + +Don't forget to replace your email address and password in the prompt above. If your email password contains special characters, you might have to escape them. + +Then, restart your platform:: + + $ tutor local launch + +That's it! You can send a test email with the following command:: + + $ tutor local run --no-deps lms ./manage.py lms shell -c \ + "from django.core.mail import send_mail; send_mail('test subject', 'test message', 'YOURUSERNAME@gmail.com', ['YOURRECIPIENT@domain.com'])" \ No newline at end of file diff --git a/docs/deployment.rst b/docs/deployment.rst new file mode 100644 index 0000000000..7dba78ac7a --- /dev/null +++ b/docs/deployment.rst @@ -0,0 +1,10 @@ +.. _deployment: + +Deploying Tutor +=============== + +.. toctree:: + :maxdepth: 2 + + local + k8s \ No newline at end of file diff --git a/docs/plugins/v0/api.rst b/docs/developing/legacy/api.rst similarity index 100% rename from docs/plugins/v0/api.rst rename to docs/developing/legacy/api.rst diff --git a/docs/plugins/v0/gettingstarted.rst b/docs/developing/legacy/gettingstarted.rst similarity index 100% rename from docs/plugins/v0/gettingstarted.rst rename to docs/developing/legacy/gettingstarted.rst diff --git a/docs/plugins/v0/index.rst b/docs/developing/legacy/index.rst similarity index 55% rename from docs/plugins/v0/index.rst rename to docs/developing/legacy/index.rst index 72bcff9bcf..f00a48e903 100644 --- a/docs/plugins/v0/index.rst +++ b/docs/developing/legacy/index.rst @@ -1,6 +1,6 @@ -============= -Legacy v0 API -============= +===================== +Plugins Legacy v0 API +===================== .. include:: legacy.rst diff --git a/docs/plugins/v0/legacy.rst b/docs/developing/legacy/legacy.rst similarity index 100% rename from docs/plugins/v0/legacy.rst rename to docs/developing/legacy/legacy.rst diff --git a/docs/tutorials/nightly.rst b/docs/developing/nightly.rst similarity index 100% rename from docs/tutorials/nightly.rst rename to docs/developing/nightly.rst diff --git a/docs/dev.rst b/docs/developing/openedx.rst similarity index 99% rename from docs/dev.rst rename to docs/developing/openedx.rst index 13d75fa0bd..bce6ae17a5 100644 --- a/docs/dev.rst +++ b/docs/developing/openedx.rst @@ -1,4 +1,4 @@ -.. _development: +.. _openedx_development: Open edX development ==================== @@ -226,11 +226,9 @@ This override file will be loaded when running any ``tutor dev ..`` command. The .. note:: The ``tutor local`` commands load the ``docker-compose.override.yml`` file from the ``$(tutor config printroot)/env/local/docker-compose.override.yml`` directory. One-time jobs from initialisation commands load the ``local/docker-compose.jobs.override.yml`` and ``dev/docker-compose.jobs.override.yml``. -Common tasks ------------- XBlock and edx-platform plugin development -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------ In some cases, you will have to develop features for packages that are pip-installed next to the edx-platform. This is quite easy with Tutor. Just add your packages to the ``$(tutor config printroot)/env/build/openedx/requirements/private.txt`` file. To avoid re-building the openedx Docker image at every change, you should add your package in editable mode. For instance:: @@ -251,7 +249,7 @@ You will have to re-build the openedx Docker image once:: You should then run the development server as usual, with ``start``. Every change made to the ``mypackage`` folder will be picked up and the development server will be automatically reloaded. Running edx-platform unit tests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------- It's possible to run the full set of unit tests that ship with `edx-platform `__. To do so, run a shell in the LMS development container:: diff --git a/docs/tutorials/plugin.rst b/docs/developing/plugins/creating.rst similarity index 97% rename from docs/tutorials/plugin.rst rename to docs/developing/plugins/creating.rst index 3970370393..c1f41e189c 100644 --- a/docs/tutorials/plugin.rst +++ b/docs/developing/plugins/creating.rst @@ -47,7 +47,7 @@ Modifying existing files with patches We'll start by modifying some of our Open edX settings files. It's a frequent requirement to modify the ``FEATURES`` setting from the LMS or the CMS in edx-platform. In the legacy native installation, this was done by modifying the ``lms.env.yml`` and ``cms.env.yml`` files. Here we'll modify the Python setting files that define the edx-platform configuration. To achieve that we'll make use of two concepts from the Tutor API: :ref:`patches` and :ref:`filters`. -If you have not already read :ref:`how_does_tutor_work` now would be a good time ☺️ Tutor uses templates to generate various files, such as settings, Dockerfiles, etc. These templates include ``{{ patch("patch-name") }}`` statements that allow plugins to insert arbitrary content in there. These patches are located at strategic locations. See :ref:`patches` for more information. +If you have not already read :ref:`how_tutor_works` now would be a good time ☺️ Tutor uses templates to generate various files, such as settings, Dockerfiles, etc. These templates include ``{{ patch("patch-name") }}`` statements that allow plugins to insert arbitrary content in there. These patches are located at strategic locations. See :ref:`patches` for more information. Let's say that we would like to limit access to our brand new Open edX platform. It is not ready for prime-time yet, so we want to prevent users from registering new accounts. There is a feature flag for that in the LMS: `FEATURES['ALLOW_PUBLIC_ACCOUNT_CREATION'] `__. By default this flag is set to a true value, enabling anyone to create an account. In the following we'll set it to false. diff --git a/docs/plugins/examples.rst b/docs/developing/plugins/examples.rst similarity index 100% rename from docs/plugins/examples.rst rename to docs/developing/plugins/examples.rst diff --git a/docs/developing/plugins/index.rst b/docs/developing/plugins/index.rst new file mode 100644 index 0000000000..ad99eaf8c7 --- /dev/null +++ b/docs/developing/plugins/index.rst @@ -0,0 +1,12 @@ +.. _plugin_development: + +======================== +Tutor plugin development +======================== + +.. toctree:: + :maxdepth: 2 + + creating + examples + indexes diff --git a/docs/reference/indexes.rst b/docs/developing/plugins/indexes.rst similarity index 100% rename from docs/reference/indexes.rst rename to docs/developing/plugins/indexes.rst diff --git a/docs/tutorials/theming.rst b/docs/developing/themes.rst similarity index 50% rename from docs/tutorials/theming.rst rename to docs/developing/themes.rst index 224a5595a2..203623f6d6 100644 --- a/docs/tutorials/theming.rst +++ b/docs/developing/themes.rst @@ -1,39 +1,7 @@ -.. _theming: - -Changing the appearance of Open edX -=================================== - -Installing a custom theme -------------------------- - -Comprehensive theming is enabled by default, but only the default theme is compiled. `Indigo `__ is a better, ready-to-run theme that you can start using today. - -To compile your own theme, add it to the ``env/build/openedx/themes/`` folder:: - - git clone https://github.com/me/myopenedxtheme.git \ - "$(tutor config printroot)/env/build/openedx/themes/myopenedxtheme" - -The ``themes`` folder should have the following structure:: - - openedx/themes/ - mycustomtheme1/ - cms/ - ... - lms/ - ... - mycustomtheme2/ - ... - -Then you must rebuild the openedx Docker image:: - - tutor images build openedx - -Finally, you should enable your theme with the :ref:`settheme command `. - .. _theme_development: -Developing a new theme ----------------------- +Open edX theme development +-------------------------- With Tutor, it's pretty easy to develop your own themes. Start by placing your files inside the ``env/build/openedx/themes`` directory. For instance, you could start from the ``edx.org`` theme present inside the ``edx-platform`` repository:: @@ -54,4 +22,4 @@ Watch the themes folders for changes (in a different terminal):: tutor dev run watchthemes -Make changes to some of the files inside the theme directory: the theme assets should be automatically recompiled and visible at http://local.overhang.io:8000. +Make changes to some of the files inside the theme directory: the theme assets should be automatically recompiled and visible at http://local.overhang.io:8000. \ No newline at end of file diff --git a/docs/faq.rst b/docs/faq.rst index 045eaa550b..2576b79d2d 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -3,17 +3,55 @@ FAQ === -What is Tutor? --------------- +Should I self-host Open edX or rely on a hosting provider? +---------------------------------------------------------- -Tutor is an open source distribution of `Open edX `_. It uses the original code from the various Open edX repositories, such as `edx-platform `_, `cs_comments_service `_, etc. and packages everything in a way that makes it very easy to install, administer and upgrade Open edX. In particular, all services are run inside Docker containers. +Third-party Open edX providers can provide you with custom, closed-source features that they developed internally. However, their pricing is usually per-seat: that makes it difficult to predict how much running Open edX will actually cost you if you don't know in advance how many students will connect to your platform. And once you start scaling up and adding many students, running the platform will become very expensive. -Tutor makes it possible to deploy Open edX locally, with `docker-compose `_ or on an existing `Kubernetes cluster `_. Want to learn more? Take a look at the :ref:`getting started concepts `. +On the other hand, running Open edX on your own servers will help you keep your costs under control. Because you own your servers and data, you will always be able to migrate your platform, either to a different cloud provider or an Open edX service provider. This is the true power of the open source. -What is the purpose of Tutor? ------------------------------ +Should I use Tutor? +------------------- -To make it possible to deploy, administer and upgrade Open edX anywhere, easily. +Running software on-premises is cheaper only if your management costs don't go through the roof. You do not want to hire a full-time devops team just for managing your online learning platform. This is why we created Tutor: to make it easy to run a state-of-the-art online learning platform without breaking the bank. Historically, it's always been difficult to install Open edX with native installation scripts. For instance, there are no official instructions for upgrading an existing Open edX platform: the `recommended approach `__ is to backup all data, trash the server, and create a new one. As a consequence, people tend not to upgrade their platform and keep running on deprecated releases. Tutor makes it possible even for non-technical users to launch, manage and upgrade Open edX at any scale. Should you choose at some point that Tutor is not the right solution for you, you always have an escape route: because Tutor is open source software, you can easily dump your data and switch to a different installation method. But we are confident you will not do that 😉 + +To learn more about Tutor, watch this 7-minute lightning talk that was made at the 2019 Open edX conference in San Diego, CA (with `slides `_): + +.. youtube:: Oqc7c-3qFc4 + +How does Tutor simplify Open edX deployment? +-------------------------------------------- + +Tutor simplifies the deployment of Open edX by: + +1. Separating the configuration logic from the deployment platforms. +2. Running application processes in cleanly separated `docker containers `_. +3. Providing user-friendly, reliable commands for common administration tasks, including upgrades and monitoring. +4. Using a simple :ref:`plugin system ` that makes it easy to extend and customise Open edX. + +.. image:: https://overhang.io/static/img/openedx-plus-docker-is-tutor.png + :alt: Open edX + Docker = Tutor + :width: 500px + :align: center + +Because Docker containers are becoming an industry-wide standard, that means that with Tutor it becomes possible to run Open edX anywhere: for now, Tutor supports deploying on a local server, with `docker-compose `_, and in a large cluster, with `Kubernetes `_. But in the future, Tutor may support other deployment platforms. + +Where can I try Open edX and Tutor? +----------------------------------- + +A demo Open edX platform is available at https://demo.openedx.overhang.io. This platform was deployed using Tutor and the `Indigo theme `__. Feel free to play around with the following credentials: + +* Admin user: username=admin email=admin@overhang.io password=admin +* Student user: username=student email=student@overhang.io password=student + +The Android mobile application for this demo platform can be downloaded at this url: https://mobile.demo.openedx.overhang.io/app.apk + +Urls: + +* LMS: https://demo.openedx.overhang.io +* Studio (CMS): https://studio.demo.openedx.overhang.io + +The platform is reset every day at 9:00 AM, `Paris (France) time `__, so feel free to try and break things as much as you want. .. _native: @@ -33,7 +71,7 @@ Many features that are not included in the native installation, such as a `web u What's the difference with the official devstack? ------------------------------------------------- -The `devstack `_ is meant for development only, not for production deployment. Tutor can be used both for production deployment and :ref:`locally hacking on Open edX `. +The `devstack `_ is meant for development only, not for production deployment. Tutor can be used both for production deployment and :ref:`locally hacking on Open edX `. Is Tutor officially supported by edX? ------------------------------------- @@ -56,3 +94,4 @@ Why should I trust software written by some random guy on the Internet? ----------------------------------------------------------------------- You shouldn't :) Tutor is actively maintained by `Overhang.IO `_, a France-based company founded by `Régis Behmo `_. Régis has been working on Tutor since early 2018; he has been a contributor to the Open edX project since 2015. In particular, he has worked for 2 years at `FUN-MOOC `_, one of the top 5 largest Open edX platforms in the world. In addition, the Tutor project is a community-led project with many contributions from its :ref:`project maintainers `. + diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst deleted file mode 100644 index 3341091c78..0000000000 --- a/docs/gettingstarted.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _gettingstarted: - -Getting started -=============== - -.. toctree:: - :maxdepth: 2 - - install - intro - quickstart - whatnext diff --git a/docs/download/binary.rst b/docs/gettingstarted/download/binary.rst similarity index 91% rename from docs/download/binary.rst rename to docs/gettingstarted/download/binary.rst index 69c1c75ccf..5a19abd9ee 100644 --- a/docs/download/binary.rst +++ b/docs/gettingstarted/download/binary.rst @@ -1,5 +1,3 @@ -.. _cli_download: - .. parsed-literal:: sudo curl -L "\ https\ ://github.com/overhangio/tutor/releases/download/v\ |tutor_version|/tutor-$(uname -s)_$(uname -m)" -o /usr/local/bin/tutor diff --git a/docs/download/pip.rst b/docs/gettingstarted/download/pip.rst similarity index 100% rename from docs/download/pip.rst rename to docs/gettingstarted/download/pip.rst diff --git a/docs/gettingstarted/installation.rst b/docs/gettingstarted/installation.rst new file mode 100644 index 0000000000..7c1cbf0203 --- /dev/null +++ b/docs/gettingstarted/installation.rst @@ -0,0 +1,49 @@ +.. _installation: + +Installation +============ + +Download +-------- + +Choose **one** of the installation methods below. If you install Tutor in different ways, you will end up with multiple ``tutor`` executables, which is going to be very confusing. At any time, you can check the path to your ``tutor`` executable by running ``which tutor``. + +Python package +~~~~~~~~~~~~~~ + +.. include:: download/pip.rst + +Check the "tutor" package on Pypi: https://pypi.org/project/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 + +.. _install_binary: + +Binary release +~~~~~~~~~~~~~~ + +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 who do not have Python 3 on their machine. 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: + +Installing from source +~~~~~~~~~~~~~~~~~~~~~~ + +To inspect the Tutor source code, install Tutor from `the Github repository `__:: + + git clone https://github.com/overhangio/tutor + cd tutor + pip install -e . + +.. _cloud_install: + +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: + +.. youtube:: xtXP52qGphA \ No newline at end of file diff --git a/docs/quickstart.rst b/docs/gettingstarted/quickstart.rst similarity index 62% rename from docs/quickstart.rst rename to docs/gettingstarted/quickstart.rst index 5bb1a63b32..885c350c10 100644 --- a/docs/quickstart.rst +++ b/docs/gettingstarted/quickstart.rst @@ -1,7 +1,5 @@ -.. _quickstart: - Quickstart (1-click install) ----------------------------- +============================ 1. Install the latest stable release of Tutor from pip: @@ -22,8 +20,8 @@ Yes :) This is what happens when you run ``tutor local launch``: 2. Configuration files are generated from templates. 3. Docker images are downloaded. 4. Docker containers are provisioned. -5. A full, production-ready Open edX platform (`Olive `__ release) is run with docker-compose. +5. A full, production-ready Open edX platform (`Nutmeg `__ release) is run with docker-compose. The whole procedure should require less than 10 minutes, on a server with 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 learn more about what you can do with Tutor and Open edX, check out the :ref:`whatnext` section. If the launch installation method above somehow didn't work for you, check out the :ref:`troubleshooting` guide. +If the launch installation method above somehow didn't work for you, check out the :ref:`troubleshooting` guide. diff --git a/docs/gettingstarted/requirements.rst b/docs/gettingstarted/requirements.rst new file mode 100644 index 0000000000..663703a697 --- /dev/null +++ b/docs/gettingstarted/requirements.rst @@ -0,0 +1,33 @@ +.. _requirements: + +Requirements +============ + +* Supported OS: Tutor runs on any 64-bit, UNIX-based OS. It was also reported to work on Windows (with `WSL 2 `__). +* Architecture: support for ARM64 is a work-in-progress. See `this issue `__. +* Required software: + + - `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. + +* 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 `. +* 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 :ref:`relevant section in the troubleshooting guide `. + +Configuring DNS records +----------------------- + +When running a server in production, it is necessary to define `DNS records `__ which will make it possible to access your Open edX platform by name in your browser. The precise procedure to create DNS records varies 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 https://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. diff --git a/docs/whatnext.rst b/docs/gettingstarted/whatsnext.rst similarity index 74% rename from docs/whatnext.rst rename to docs/gettingstarted/whatsnext.rst index f185605222..656391ffb7 100644 --- a/docs/whatnext.rst +++ b/docs/gettingstarted/whatsnext.rst @@ -1,7 +1,5 @@ -.. _whatnext: - -What next? -========== +What's next +=========== You have gone through the :ref:`Quickstart installation `: at this point, you should have a running Open edX platform. If you don't, please follow the instructions from the :ref:`Troubleshooting ` section. @@ -44,3 +42,20 @@ Meeting the community --------------------- Ask your questions and chat with the Tutor community on the official Open edX community forum: https://discuss.openedx.org + +.. _autocomplete: + +Shell autocompletion +-------------------- + +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 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 \ No newline at end of file diff --git a/docs/howtutorworks.rst b/docs/howtutorworks.rst new file mode 100644 index 0000000000..ab0ce12473 --- /dev/null +++ b/docs/howtutorworks.rst @@ -0,0 +1,32 @@ +.. _how_tutor_works: + +How Tutor works +=============== + +Tutor is a piece of software that takes care of exactly three things: + +1. Project configuration: user-specific settings (such as secrets) are stored in a single ``config.yml`` file. +2. Template rendering: all the files that are necessary to run your platform are generated from a set of templates and user-specific settings. +3. Command-line interface (CLI): frequently-used administration commands are gathered in a convenient, unified CLI. + +You can experiment with Tutor very quickly: start by `installing `_ Tutor. Then run:: + + $ tutor config save --interactive + +Then, to view the result of the above command:: + + $ cd "$(tutor config printroot)" + $ ls + config.yml env + +The ``config.yml`` file contains your user-specific Open edX settings (item #1 above). The ``env/`` folder contains the rendered templates which will be used to run your Open edX platform (item #2). For instance, the ``env/local`` folder contains the ``docker-compose.yml`` file to run Open edX locally. + +The values from ``config.yml`` are used to generate the environment files in ``env/``. As a consequence, **every time the values from** ``config.yml`` **are modified, the environment must be regenerated** with ``tutor config save``.. + +Because the Tutor environment is generated entirely from the values in ``config.yml``, you can ``rm -rf`` the ``env/`` folder at any time and re-create it with ``tutor config save``. Another consequence is that **any manual change made to a file in** ``env/`` **will be overwritten by** ``tutor config save`` **commands**. Consider yourself warned! + +You can now take advantage of the Tutor-powered CLI (item #3) to bootstrap your Open edX platform:: + + tutor local launch + +Under the hood, Tutor simply runs ``docker-compose`` and ``docker`` commands to launch your platform. These commands are printed in the standard output, such that you are free to replicate the same behaviour by simply copying/pasting the same commands. diff --git a/docs/index.rst b/docs/index.rst index 7cabf55239..e5449294b7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,26 +12,64 @@ ---------------------------------- -.. include:: quickstart.rst - :start-line: 1 +.. toctree:: + :maxdepth: 1 + :caption: Concepts + + concepts/tutor + concepts/openedx .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + :caption: Getting started + + gettingstarted/requirements + gettingstarted/quickstart + gettingstarted/installation + gettingstarted/whatsnext + +.. toctree:: + :maxdepth: 1 :caption: User guide - gettingstarted + deployment run configuration plugins/index - reference/index - tutorials/index + sysadmin/index + upgrading + uninstallation + cli troubleshooting + +.. toctree:: + :maxdepth: 1 + :caption: Developer guide + + developing/nightly + developing/plugins/index tutor - faq + developing/openedx + developing/themes + developing/legacy/index + +.. toctree:: + :maxdepth: 1 + :caption: Reference + reference/cli/index + reference/api/hooks/index + reference/patches/index + +.. toctree:: + :maxdepth: 1 + :caption: About + + howtutorworks + faq .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Project links Source code diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index 5059b33e2e..0000000000 --- a/docs/install.rst +++ /dev/null @@ -1,175 +0,0 @@ -.. _install: - -Installing Tutor -================ - -.. _requirements: - -Requirements ------------- - -* Supported OS: Tutor runs on any 64-bit, UNIX-based OS. It was also reported to work on Windows (with `WSL 2 `__). -* Architecture: support for ARM64 is a work-in-progress. See `this issue `__. -* Required software: - - - `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. - -* 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 `. -* 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 :ref:`relevant section in the troubleshooting guide `. - -Download --------- - -Choose **one** of the installation methods below. If you install Tutor in different ways, you will end up with multiple ``tutor`` executables, which is going to be very confusing. At any time, you can check the path to your ``tutor`` executable by running ``which tutor``. - -Python package -~~~~~~~~~~~~~~ - -.. include:: download/pip.rst - -Check the "tutor" package on Pypi: https://pypi.org/project/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 - -.. _install_binary: - -Binary release -~~~~~~~~~~~~~~ - -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 who do not have Python 3 on their machine. 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: - -Installing from source -~~~~~~~~~~~~~~~~~~~~~~ - -To inspect the Tutor source code, install Tutor from `the Github repository `__:: - - git clone https://github.com/overhangio/tutor - cd tutor - pip install -e . - -Configuring DNS records ------------------------ - -When running a server in production, it is necessary to define `DNS records `__ which will make it possible to access your Open edX platform by name in your browser. The precise procedure to create DNS records varies 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 https://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 `__. 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 ---------- - -To upgrade Open edX or benefit from the latest features and bug fixes, you should simply upgrade Tutor. Start by upgrading the "tutor" package and its dependencies:: - - pip install --upgrade "tutor[full]" - -Then run the ``launch`` command again. Depending on your deployment target, run one of:: - - tutor local launch # for local installations - tutor dev launch # for local development installations - tutor k8s launch # for Kubernetes installation - -Upgrading with custom Docker images -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you run :ref:`customised ` Docker images, you need to rebuild them before running ``launch``:: - - tutor config save - tutor images build all # specify here the images that you need to build - tutor local launch - -Upgrading to a new Open edX release -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Major Open edX releases are published twice a year, in June and December, by the Open edX `Build/Test/Release working group `__. When a new Open edX release comes out, Tutor gets a major version bump (see :ref:`versioning`). Such an upgrade typically includes multiple breaking changes. Any upgrade is final because downgrading is not supported. Thus, when upgrading your platform from one major version to the next, it is strongly recommended to do the following: - -1. Read the changes listed in the `CHANGELOG.md `__ file. Breaking changes are identified by a "💥". -2. Perform a backup. On a local installation, this is typically done with:: - - tutor local stop - sudo rsync -avr "$(tutor config printroot)"/ /tmp/tutor-backup/ - -3. If you created custom plugins, make sure that they are compatible with the newer release. -4. Test the new release in a sandboxed environment. -5. If you are running edx-platform, or some other repository from a custom branch, then you should rebase (and test) your changes on top of the latest release tag (see :ref:`edx_platform_fork`). - -The process for upgrading from one major release to the next works similarly to any other upgrade, with the ``launch`` command (see above). The single difference is that if the ``launch`` command detects that your tutor environment was generated with an older release, it will perform a few release-specific upgrade steps. These extra upgrade steps will be performed just once. But they will be ignored if you updated your local environment (for instance: with ``tutor config save``) before running ``launch``. This situation typically occurs if you need to re-build some Docker images (see above). In such a case, you should make use of the ``upgrade`` command. For instance, to upgrade a local installation from Nutmeg to Olive and rebuild some Docker images, run:: - - tutor config save - tutor images build all # list the images that should be rebuilt here - tutor local upgrade --from=nutmeg - tutor local launch - -.. _autocomplete: - -Shell autocompletion --------------------- - -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 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 - -Uninstallation --------------- - -It is fairly easy to completely uninstall Tutor and to delete the Open edX platforms that are running locally. - -First of all, stop any locally-running platform and remove all Tutor containers:: - - tutor local dc down --remove-orphans - tutor dev dc down --remove-orphans - -Then, delete all data associated with 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 - - # Optionally, you may want to remove Tutor plugins installed. - # You can get a list of the installed plugins: - pip freeze | grep tutor - # You can then remove them using the following command: - pip uninstall diff --git a/docs/intro.rst b/docs/intro.rst deleted file mode 100644 index bbef116f8d..0000000000 --- a/docs/intro.rst +++ /dev/null @@ -1,137 +0,0 @@ -.. _intro: - -Concepts -======== - -What is Open edX? ------------------ - -`Open edX `_ is a thriving open source project, backed by a great community, for running an online learning platform at scale. Open edX comes with an LMS (Learning Management System) where students access course contents, a CMS (Content Management System) that course staff uses to design courses, and a few other components to provide more services to students, course staff, and platform administrators. - -Should I use Open edX? ----------------------- - -Open edX competitors include `Moodle `__, `Instructure's Canvas `__, `Blackboard's Open LMS `__, as well as a slew of hosted, closed source alternatives. Open edX is the only online learning system that satisfies all following properties: - -* Open source software to avoid vendor lock-in -* Scales well in all directions (number of users and courses) -* Multiple extension points for comprehensive customization -* Modern, intuitive user interface to keep students engaged - -Open edX is a safe bet: it is backed by edX.org, a US-based non-profit that is committed to open source and which runs Open edX to service its millions of learners. With Open edX you can be sure that the features you need will be available. If it's good enough for Harvard, the MIT, or the French government, then it will probably also work for you. - -Should I self-host Open edX or rely on a hosting provider? ----------------------------------------------------------- - -Third-party Open edX providers can provide you with custom, closed-source features that they developed internally. However, their pricing is usually per-seat: that makes it difficult to predict how much running Open edX will actually cost you if you don't know in advance how many students will connect to your platform. And once you start scaling up and adding many students, running the platform will become very expensive. - -On the other hand, running Open edX on your own servers will help you keep your costs under control. Because you own your servers and data, you will always be able to migrate your platform, either to a different cloud provider or an Open edX service provider. This is the true power of the open source. - -Should I use Tutor? -------------------- - -Running software on-premises is cheaper only if your management costs don't go through the roof. You do not want to hire a full-time devops team just for managing your online learning platform. This is why we created Tutor: to make it easy to run a state-of-the-art online learning platform without breaking the bank. Historically, it's always been difficult to install Open edX with native installation scripts. For instance, there are no official instructions for upgrading an existing Open edX platform: the `recommended approach `__ is to backup all data, trash the server, and create a new one. As a consequence, people tend not to upgrade their platform and keep running on deprecated releases. Tutor makes it possible even for non-technical users to launch, manage and upgrade Open edX at any scale. Should you choose at some point that Tutor is not the right solution for you, you always have an escape route: because Tutor is open source software, you can easily dump your data and switch to a different installation method. But we are confident you will not do that 😉 - -To learn more about Tutor, watch this 7-minute lightning talk that was made at the 2019 Open edX conference in San Diego, CA (with `slides `_): - -.. youtube:: Oqc7c-3qFc4 - -How does Tutor simplify Open edX deployment? --------------------------------------------- - -Tutor simplifies the deployment of Open edX by: - -1. Separating the configuration logic from the deployment platforms. -2. Running application processes in cleanly separated `docker containers `_. -3. Providing user-friendly, reliable commands for common administration tasks, including upgrades and monitoring. -4. Using a simple :ref:`plugin system ` that makes it easy to extend and customise Open edX. - -.. image:: https://overhang.io/static/img/openedx-plus-docker-is-tutor.png - :alt: Open edX + Docker = Tutor - :width: 500px - :align: center - -Because Docker containers are becoming an industry-wide standard, that means that with Tutor it becomes possible to run Open edX anywhere: for now, Tutor supports deploying on a local server, with `docker-compose `_, and in a large cluster, with `Kubernetes `_. But in the future, Tutor may support other deployment platforms. - -Where can I try Open edX and Tutor? ------------------------------------ - -A demo Open edX platform is available at https://demo.openedx.overhang.io. This platform was deployed using Tutor and the `Indigo theme `__. Feel free to play around with the following credentials: - -* Admin user: username=admin email=admin@overhang.io password=admin -* Student user: username=student email=student@overhang.io password=student - -The Android mobile application for this demo platform can be downloaded at this url: https://mobile.demo.openedx.overhang.io/app.apk - -Urls: - -* LMS: https://demo.openedx.overhang.io -* Studio (CMS): https://studio.demo.openedx.overhang.io - -The platform is reset every day at 9:00 AM, `Paris (France) time `__, so feel free to try and break things as much as you want. - -.. _how_does_tutor_work: - -How does Tutor work? --------------------- - -Tutor is a piece of software that takes care of exactly three things: - -1. Project configuration: user-specific settings (such as secrets) are stored in a single ``config.yml`` file. -2. Template rendering: all the files that are necessary to run your platform are generated from a set of templates and user-specific settings. -3. Command-line interface (CLI): frequently-used administration commands are gathered in a convenient, unified CLI. - -You can experiment with Tutor very quickly: start by `installing `_ Tutor. Then run:: - - $ tutor config save --interactive - -Then, to view the result of the above command:: - - $ cd "$(tutor config printroot)" - $ ls - config.yml env - -The ``config.yml`` file contains your user-specific Open edX settings (item #1 above). The ``env/`` folder contains the rendered templates which will be used to run your Open edX platform (item #2). For instance, the ``env/local`` folder contains the ``docker-compose.yml`` file to run Open edX locally. - -The values from ``config.yml`` are used to generate the environment files in ``env/``. As a consequence, **every time the values from** ``config.yml`` **are modified, the environment must be regenerated** with ``tutor config save``.. - -Because the Tutor environment is generated entirely from the values in ``config.yml``, you can ``rm -rf`` the ``env/`` folder at any time and re-create it with ``tutor config save``. Another consequence is that **any manual change made to a file in** ``env/`` **will be overwritten by** ``tutor config save`` **commands**. Consider yourself warned! - -You can now take advantage of the Tutor-powered CLI (item #3) to bootstrap your Open edX platform:: - - tutor local launch - -Under the hood, Tutor simply runs ``docker-compose`` and ``docker`` commands to launch your platform. These commands are printed in the standard output, such that you are free to replicate the same behaviour by simply copying/pasting the same commands. - -How do I navigate Tutor's command-line interface? -------------------------------------------------- - -Tutor commands are structured in an easy-to-follow hierarchy. At the top level, there are command trees for image and configuration management:: - - tutor config ... - tutor images ... - -as well as command trees for each mode in which Tutor can run:: - - tutor local ... # Commands for managing a local Open edX deployment. - tutor k8s ... # Commands for managing a Kubernetes Open edX deployment. - tutor dev ... # Commands for hacking on Open edX in development mode. - -Within each mode, Tutor has subcommands for managing that type of Open edX instance. Many of them are common between modes, such as ``launch``, ``start``, ``stop``, ``exec``, and ``logs``. For example:: - - tutor local logs # View logs of a local deployment. - tutor k8s logs # View logs of a Kubernetes-managed deployment. - tutor dev logs # View logs of a development platform. - -Many commands can be further parameterized to specify their target and options, for example:: - - tutor local logs cms # View logs of the CMS container in a local deployment. - tutor k8s logs mysql # View logs of MySQL in Kubernetes-managed deployment. - tutor dev logs lms --tail 10 # View ten lines of logs of the LMS container in development mode. - -And that's it! You do not need to understand Tutor's entire command-line interface to get started. Using the ``--help`` option that's availble on every command, it is easy to learn as you go. For an in-depth guide, you can also explore the `CLI Reference `_. - -I'm ready, where do I start? ----------------------------- - -Right :ref:`here `! diff --git a/docs/k8s.rst b/docs/k8s.rst index a7a80ad693..c7f6df0cf9 100644 --- a/docs/k8s.rst +++ b/docs/k8s.rst @@ -3,7 +3,7 @@ Kubernetes deployment ===================== -With the same docker images we created for :ref:`single server deployment ` and :ref:`local development `, we can launch an Open edX platform on Kubernetes. Always in 1 click, of course :) +With the same docker images we created for :ref:`single server deployment ` and :ref:`local development `, we can launch an Open edX platform on Kubernetes. Always in 1 click, of course :) A word of warning: managing a Kubernetes platform is a fairly advanced endeavour. In this documentation, we assume familiarity with Kubernetes. Running an Open edX platform with Tutor on a single server or in a Kubernetes cluster are two very different things. The local Open edX install was designed such that users with no prior experience with system administration could still launch an Open edX platform. It is *not* the case for the installation method outlined here. diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst index 399f9568bc..eb23b8387c 100644 --- a/docs/plugins/index.rst +++ b/docs/plugins/index.rst @@ -1,11 +1,68 @@ +.. _plugins: -======= +============ Plugins -======= +============ -.. toctree:: - :maxdepth: 2 +Tutor comes with a plugin system that allows anyone to customise the deployment of an Open edX platform very easily. The vision behind this plugin system is that users should not have to fork the Tutor repository to customise their deployments. For instance, if you have created a new application that integrates with Open edX, you should not have to describe how to manually patch the platform settings, ``urls.py`` or ``*.env.yml`` files. Instead, you can create a "tutor-myapp" plugin for Tutor. Then, users will start using your application in three simple steps:: - intro - examples - v0/index + # 1) Install the plugin + pip install tutor-myapp + # 2) Enable the plugin + tutor plugins enable myapp + # 3) Reconfigure and restart the platform + tutor local launch + +For simple changes, it may be extremely easy to create a Tutor plugin: even non-technical users may get started with our :ref:`plugin_development_tutorial` tutorial. We also provide a list of :ref:`simple example plugins `. + +Plugin commands cheatsheet +========================== + +List installed plugins:: + + tutor plugins list + +Enable/disable a plugin:: + + tutor plugins enable myplugin + tutor plugins disable myplugin + +After enabling or disabling a plugin, the environment should be re-generated with:: + + tutor config save + +.. it'd be nice to use ref for the plugins cli link instead, see https://github.com/click-contrib/sphinx-click/issues/15 + +The full plugins CLI is described in the `reference documentation <../reference/cli/tutor.html#tutor-plugins>`_. + +.. _existing_plugins: + +Existing plugins +================ + +Many plugins are available from plugin indexes. These indexes are lists of plugins, similar to the `pypi `__ or `npm `__ indexes. By default, Tutor comes with the "main" plugin index. You can check available plugins from this index by running:: + + tutor plugins update + tutor plugins search + +More plugins can be downloaded from the "contrib" and "wizard" indexes:: + + tutor plugins index add contrib + tutor plugins index add wizard + tutor plugins search + +The "main", "contrib" and "wizard" indexes include a curated list of plugins that are well maintained and introduce useful features to Open edX. These indexes are maintained by `Overhang.IO `__. For more information about these indexes, refer to the official `overhangio/tpi `__ repository. + +Thanks to these indexes, it is very easy to download and upgrade plugins. For instance, to install the `notes plugin `__:: + + tutor plugins install notes + +Upgrade all your plugins with:: + + tutor plugins upgrade all + +To list indexes that you are downloading plugins from, run:: + + tutor plugins index list + +For more information about these indexes, check the `official Tutor plugin indexes (TPI) `__ repository. \ No newline at end of file diff --git a/docs/plugins/intro.rst b/docs/plugins/intro.rst deleted file mode 100644 index bc55b0a74e..0000000000 --- a/docs/plugins/intro.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. _plugins: - -============ -Introduction -============ - -Tutor comes with a plugin system that allows anyone to customise the deployment of an Open edX platform very easily. The vision behind this plugin system is that users should not have to fork the Tutor repository to customise their deployments. For instance, if you have created a new application that integrates with Open edX, you should not have to describe how to manually patch the platform settings, ``urls.py`` or ``*.env.yml`` files. Instead, you can create a "tutor-myapp" plugin for Tutor. This plugin will be in charge of making changes to the platform settings. Then, users will be able to use your application in three simple steps:: - - # 1) Install the plugin - pip install tutor-myapp - # 2) Enable the plugin - tutor plugins enable myapp - # 3) Reconfigure and restart the platform - tutor local launch - -For simple changes, it may be extremely easy to create a Tutor plugin: even non-technical users may get started with our :ref:`plugin_development_tutorial` tutorial. We also provide a list of :ref:`simple example plugins `. - -To learn about the different ways in which plugins can extend Tutor, check out the :ref:`hooks catalog `. - -Plugin commands cheatsheet -========================== - -List installed plugins:: - - tutor plugins list - -Enable/disable a plugin:: - - tutor plugins enable myplugin - tutor plugins disable myplugin - -After enabling or disabling a plugin, the environment should be re-generated with:: - - tutor config save - -The full plugins CLI is described in the :ref:`reference documentation `. - -.. _existing_plugins: - -Existing plugins -================ - -Many plugins are available from plugin indexes. These indexes are lists of plugins, similar to the `pypi `__ or `npm `__ indexes. By default, Tutor comes with the "main" plugin index. You can check available plugins from this index by running:: - - tutor plugins update - tutor plugins search - -More plugins can be downloaded from the "contrib" and "wizard" indexes:: - - tutor plugins index add contrib - tutor plugins index add wizard - tutor plugins search - -The "main", "contrib" and "wizard" indexes include a curated list of plugins that are well maintained and introduce useful features to Open edX. These indexes are maintained by `Overhang.IO `__. For more information about these indexes, refer to the official `overhangio/tpi `__ repository. - -Thanks to these indexes, it is very easy to download and upgrade plugins. For instance, to install the `notes plugin `__:: - - tutor plugins install notes - -Upgrade all your plugins with:: - - tutor plugins upgrade all - -To list indexes that you are downloading plugins from, run:: - - tutor plugins index list - -For more information about these indexes, check the `official Tutor plugin indexes (TPI) `__ repository. diff --git a/docs/reference/api/hooks/index.rst b/docs/reference/api/hooks/index.rst index d668685fcb..c1ac1fe9fa 100644 --- a/docs/reference/api/hooks/index.rst +++ b/docs/reference/api/hooks/index.rst @@ -1,14 +1,15 @@ .. _hooks_api: -========== -Hook types -========== +===== +Hooks +===== This is the Python documentation of the two types of hooks (actions and filters) as well as the contexts system which is used to instrument them. Understanding how Tutor hooks work is useful to create plugins that modify the behaviour of Tutor. However, plugin developers should almost certainly not import these hook types directly. Instead, use the reference :ref:`hooks catalog `. .. toctree:: :maxdepth: 1 + catalog actions filters contexts diff --git a/docs/reference/cli/config.rst b/docs/reference/cli/config.rst deleted file mode 100644 index d97b2f1d10..0000000000 --- a/docs/reference/cli/config.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. click:: tutor.commands.config:config_command - :prog: tutor config - :nested: full diff --git a/docs/reference/cli/dev.rst b/docs/reference/cli/dev.rst deleted file mode 100644 index a72b495112..0000000000 --- a/docs/reference/cli/dev.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. click:: tutor.commands.dev:dev - :prog: tutor dev - :nested: full diff --git a/docs/reference/cli/images.rst b/docs/reference/cli/images.rst deleted file mode 100644 index 7966bae1b2..0000000000 --- a/docs/reference/cli/images.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. click:: tutor.commands.images:images_command - :prog: tutor images - :nested: full diff --git a/docs/reference/cli/index.rst b/docs/reference/cli/index.rst index 6995faf8f1..35780cf813 100644 --- a/docs/reference/cli/index.rst +++ b/docs/reference/cli/index.rst @@ -1,13 +1,9 @@ +.. _cli_reference: + Command line interface (CLI) ============================ .. toctree:: - :maxdepth: 2 + :maxdepth: 3 tutor - config - dev - images - k8s - local - plugins diff --git a/docs/reference/cli/k8s.rst b/docs/reference/cli/k8s.rst deleted file mode 100644 index 9334459124..0000000000 --- a/docs/reference/cli/k8s.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. click:: tutor.commands.k8s:k8s - :prog: tutor k8s - :nested: full diff --git a/docs/reference/cli/local.rst b/docs/reference/cli/local.rst deleted file mode 100644 index 91294d6af2..0000000000 --- a/docs/reference/cli/local.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. click:: tutor.commands.local:local - :prog: tutor local - :nested: full diff --git a/docs/reference/cli/plugins.rst b/docs/reference/cli/plugins.rst deleted file mode 100644 index 7bf378e71a..0000000000 --- a/docs/reference/cli/plugins.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. _cli_plugins: - -.. click:: tutor.commands.plugins:plugins_command - :prog: tutor plugins - :nested: full diff --git a/docs/reference/cli/tutor.rst b/docs/reference/cli/tutor.rst index 233bec5841..661eb7c8c8 100644 --- a/docs/reference/cli/tutor.rst +++ b/docs/reference/cli/tutor.rst @@ -1,3 +1,3 @@ .. click:: tutor.commands.cli:cli :prog: tutor - :nested: full + :nested: full \ No newline at end of file diff --git a/docs/reference/index.rst b/docs/reference/index.rst deleted file mode 100644 index 3281a9cf70..0000000000 --- a/docs/reference/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -Reference -========= - -.. toctree:: - :maxdepth: 2 - - api/hooks/index - api/hooks/catalog - patches - cli/index - indexes diff --git a/docs/reference/patches.rst b/docs/reference/patches/index.rst similarity index 100% rename from docs/reference/patches.rst rename to docs/reference/patches/index.rst diff --git a/docs/run.rst b/docs/run.rst index a4114f6649..b88c7e4c13 100644 --- a/docs/run.rst +++ b/docs/run.rst @@ -3,9 +3,14 @@ Running Open edX ================ -.. toctree:: - :maxdepth: 2 +You have gone through the :ref:`installation `: at this point, you should have a running Open edX platform. If you don't, please follow the instructions from the :ref:`Troubleshooting ` section. - local - k8s - dev +Logging-in as administrator +--------------------------- + +Out of the box, Tutor does not create any user for you. You will want to create a user yourself with staff and administrator privileges to access the studio. There is a :ref:`simple command for that `. + +Importing a demo course +----------------------- + +To get a glimpse of the possibilities of Open edX, we recommend you import the `official demo test course `__. Tutor provides a :ref:`simple command for that `. diff --git a/docs/tutorials/arm64.rst b/docs/sysadmin/arm64.rst similarity index 100% rename from docs/tutorials/arm64.rst rename to docs/sysadmin/arm64.rst diff --git a/docs/tutorials/datamigration.rst b/docs/sysadmin/datamigration.rst similarity index 100% rename from docs/tutorials/datamigration.rst rename to docs/sysadmin/datamigration.rst diff --git a/docs/sysadmin/index.rst b/docs/sysadmin/index.rst new file mode 100644 index 0000000000..95bf930a21 --- /dev/null +++ b/docs/sysadmin/index.rst @@ -0,0 +1,14 @@ +System administration +===================== + +.. toctree:: + :maxdepth: 1 + + scale + portainer + podman + proxy + datamigration + multiplatforms + oldreleases + arm64 diff --git a/docs/tutorials/multiplatforms.rst b/docs/sysadmin/multiplatforms.rst similarity index 100% rename from docs/tutorials/multiplatforms.rst rename to docs/sysadmin/multiplatforms.rst diff --git a/docs/tutorials/oldreleases.rst b/docs/sysadmin/oldreleases.rst similarity index 100% rename from docs/tutorials/oldreleases.rst rename to docs/sysadmin/oldreleases.rst diff --git a/docs/tutorials/podman.rst b/docs/sysadmin/podman.rst similarity index 100% rename from docs/tutorials/podman.rst rename to docs/sysadmin/podman.rst diff --git a/docs/tutorials/portainer.rst b/docs/sysadmin/portainer.rst similarity index 100% rename from docs/tutorials/portainer.rst rename to docs/sysadmin/portainer.rst diff --git a/docs/tutorials/proxy.rst b/docs/sysadmin/proxy.rst similarity index 100% rename from docs/tutorials/proxy.rst rename to docs/sysadmin/proxy.rst diff --git a/docs/tutorials/scale.rst b/docs/sysadmin/scale.rst similarity index 100% rename from docs/tutorials/scale.rst rename to docs/sysadmin/scale.rst diff --git a/docs/tutorials/edx-platform-settings.rst b/docs/tutorials/edx-platform-settings.rst deleted file mode 100644 index e3c5cf2b22..0000000000 --- a/docs/tutorials/edx-platform-settings.rst +++ /dev/null @@ -1,4 +0,0 @@ -Modifying ``edx-platform`` settings ------------------------------------ - -The default settings module loaded by ``edx-platform`` is ``tutor.production`` in production and ``tutor.development`` in development. The folders ``$(tutor config printroot)/env/apps/openedx/settings/lms`` and ``$(tutor config printroot)/env/apps/openedx/settings/cms`` are mounted as ``edx-platform/lms/envs/tutor`` and ``edx-platform/cms/envs/tutor`` inside the docker containers. To modify these settings you must create a plugin that implements one or more of the patch statements in those setting files. See the :ref:`plugin_development_tutorial` tutorial for more information on how to create a plugin. diff --git a/docs/tutorials/google-smtp.rst b/docs/tutorials/google-smtp.rst deleted file mode 100644 index 2352d7115e..0000000000 --- a/docs/tutorials/google-smtp.rst +++ /dev/null @@ -1,42 +0,0 @@ -Using Google Mail as an SMTP server -=================================== - -By default, Tutor comes with a simple SMTP server for sending emails. Such a server has an important limitation: it does not implement mailing good practices, such as DKIM or SPF. As a consequence. the emails you send might be flagged as spam by their recipients. Thus, you might want to disable the SMTP server and run your own, for instance using your Google Mail account. - -.. warning:: - Google Mail SMTP servers come with their own set of limitations. For instance, you are limited to sending 500 emails a day. Reference: https://support.google.com/mail/answer/22839 - -You should authorize third-party to access your Google Mail account. In your Google Mail account, select "Manage Account", "Security", and turn on "Less Secure App Access". Check the Google documentation for more information on "less secure apps": https://support.google.com/accounts/answer/6010255 - -Then, check that you can reach the Google Mail SMTP service from your own server:: - - $ telnet smtp.gmail.com 587 - -If you get ``Connected to smtp.gmail.com.`` then it means that you can successfully reach the Google Mail SMTP servers. If not, you will have to reconfigure your firewall. - -To exit the ``telnet`` shell, type ``ctrl+]``, then ``ctrl+d``. - -Then, disable the SMTP server that comes with Tutor:: - - $ tutor config save --set RUN_SMTP=false - -Configure credentials to access your SMTP server:: - - $ tutor config save \ - --set SMTP_HOST=smtp.gmail.com \ - --set SMTP_PORT=587 \ - --set SMTP_USE_SSL=false \ - --set SMTP_USE_TLS=true \ - --set SMTP_USERNAME=YOURUSERNAME@gmail.com \ - --set SMTP_PASSWORD='YOURPASSWORD' - -Don't forget to replace your email address and password in the prompt above. If your email password contains special characters, you might have to escape them. - -Then, restart your platform:: - - $ tutor local launch - -That's it! You can send a test email with the following command:: - - $ tutor local run --no-deps lms ./manage.py lms shell -c \ - "from django.core.mail import send_mail; send_mail('test subject', 'test message', 'YOURUSERNAME@gmail.com', ['YOURRECIPIENT@domain.com'])" diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst deleted file mode 100644 index d5128a3f3c..0000000000 --- a/docs/tutorials/index.rst +++ /dev/null @@ -1,32 +0,0 @@ -Tutorials -========= - -Open edX customization ----------------------- - -.. toctree:: - :maxdepth: 1 - - plugin - theming - edx-platform-settings - google-smtp - nightly - -System administration ---------------------- - -.. toctree:: - :maxdepth: 1 - - scale - portainer - podman - proxy - datamigration - multiplatforms - oldreleases - arm64 - -.. Note: maybe we should create a dedicated tutorial category in the Open edX forum? -.. Other tutorials can be found in the official Tutor forums, `in the "Tutorials" category `__. diff --git a/docs/uninstallation.rst b/docs/uninstallation.rst new file mode 100644 index 0000000000..1c69eb10ea --- /dev/null +++ b/docs/uninstallation.rst @@ -0,0 +1,29 @@ +Uninstallation +============== + +It is fairly easy to completely uninstall Tutor and to delete the Open edX platforms that are running locally. + +First of all, stop any locally-running platform and remove all Tutor containers:: + + tutor local dc down --remove-orphans + tutor dev dc down --remove-orphans + +Then, delete all data associated with 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 + + # Optionally, you may want to remove Tutor plugins installed. + # You can get a list of the installed plugins: + pip freeze | grep tutor + # You can then remove them using the following command: + pip uninstall + \ No newline at end of file diff --git a/docs/upgrading.rst b/docs/upgrading.rst new file mode 100644 index 0000000000..0cb637eccb --- /dev/null +++ b/docs/upgrading.rst @@ -0,0 +1,45 @@ +.. _upgrade: + +Upgrading +========= + +To upgrade Open edX or benefit from the latest features and bug fixes, you should simply upgrade Tutor. Start by upgrading the "tutor" package and its dependencies:: + + pip install --upgrade "tutor[full]" + +Then run the ``launch`` command again. Depending on your deployment target, run one of:: + + tutor local launch # for local installations + tutor dev launch # for local development installations + tutor k8s launch # for Kubernetes installation + +Upgrading with custom Docker images +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you run :ref:`customised ` Docker images, you need to rebuild them before running ``launch``:: + + tutor config save + tutor images build all # specify here the images that you need to build + tutor local launch + +Upgrading to a new Open edX release +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Major Open edX releases are published twice a year, in June and December, by the Open edX `Build/Test/Release working group `__. When a new Open edX release comes out, Tutor gets a major version bump (see :ref:`versioning`). Such an upgrade typically includes multiple breaking changes. Any upgrade is final because downgrading is not supported. Thus, when upgrading your platform from one major version to the next, it is strongly recommended to do the following: + +1. Read the changes listed in the `CHANGELOG.md `__ file. Breaking changes are identified by a "💥". +2. Perform a backup. On a local installation, this is typically done with:: + + tutor local stop + sudo rsync -avr "$(tutor config printroot)"/ /tmp/tutor-backup/ + +3. If you created custom plugins, make sure that they are compatible with the newer release. +4. Test the new release in a sandboxed environment. +5. If you are running edx-platform, or some other repository from a custom branch, then you should rebase (and test) your changes on top of the latest release tag (see :ref:`edx_platform_fork`). + +The process for upgrading from one major release to the next works similarly to any other upgrade, with the ``launch`` command (see above). The single difference is that if the ``launch`` command detects that your tutor environment was generated with an older release, it will perform a few release-specific upgrade steps. These extra upgrade steps will be performed just once. But they will be ignored if you updated your local environment (for instance: with ``tutor config save``) before running ``launch``. This situation typically occurs if you need to re-build some Docker images (see above). In such a case, you should make use of the ``upgrade`` command. For instance, to upgrade a local installation from Nutmeg to Olive and rebuild some Docker images, run:: + + tutor config save + tutor images build all # list the images that should be rebuilt here + tutor local upgrade --from=nutmeg + tutor local launch \ No newline at end of file