christianlight/tutor
7
0
Fork 0
mirror of https://github.com/ChristianLight/tutor.git synced 2024-06-14 03:22:21 +00:00
Code Issues Releases Activity

Better docs organization

Browse Source 
With this reoreganization, we have a cleaner TOC and more intuitive
content navigation.
This commit is contained in:
Régis Behmo 2020-03-16 12:07:58 +01:00
parent 42d698d6e5
commit 28c761fe76
12 changed files with 390 additions and 298 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/gettingstarted.rst Normal file
View File

@ -0,0 +1,12 @@
.. _gettingstarted:
Getting started
===============
.. toctree::
:maxdepth: 2
intro
quickstart
install
whatnext

8
docs/index.rst
View File

@ -19,13 +19,9 @@
:maxdepth: 2
:caption: User guide
intro
install
quickstart
gettingstarted
run
configuration
local
k8s
dev
plugins
extra
troubleshooting

8
docs/install.rst
View File

@ -1,15 +1,15 @@
.. _install:
Installation
============
Install Tutor
=============
Requirements
------------
The only prerequisite for running this is a working Docker installation. You'll need both the ``docker`` and ``docker-compose`` commands in your system ``$PATH``. Follow the instructions from the official documentation:
- `Docker <https://docs.docker.com/engine/installation/>`_: minimum supported version is 18.06.0.
- `Docker Compose <https://docs.docker.com/compose/install/>`_
- `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.

76
docs/intro.rst
View File

@ -1,14 +1,50 @@
.. _intro:
Introduction
============
Concepts
========
`Open edX <http://open.edx.org/>`_ is a thriving open source project, backed by a great community, for running an online learning platform at scale. Historically, it's always been :ref:`difficult <native>` to install Open edX. The goal of Tutor is to solve this issue.
What is Open edX?
-----------------
`Open edX <http://open.edx.org/>`_ 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 <https://moodle.org/>`__, `Instructure's Canvas <https://www.instructure.com/>`__, `Blackboard's Open LMS <https://www.blackboard.com>`__, 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 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 the native installation scripts. For instance, there are no official instructions for upgrading an existing Open edX platform: the `recommended approach <https://docs.bitnami.com/azure/apps/edx/administration/upgrade/>`__ 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 to 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 <https://regisb.github.io/openedx2019/>`_):
.. youtube:: Oqc7c-3qFc4
How does Tutor work, technically speaking?
------------------------------------------
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 <https://www.docker.com/resources/what-container>`_.
3. Providing user-friendly, reliable commands for common administration tasks, including upgrades and monitoring.
4. Using a simple :ref:`plugin system <plugins>` that makes it easy to extend and customize Open edX.
.. image:: https://overhang.io/static/img/openedx-plus-docker-is-tutor.png
:alt: Open edX + Docker = Tutor
@ -17,12 +53,21 @@ Tutor simplifies the deployment of Open edX by:
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 <https://docs.docker.com/compose/overview/>`_, and in a large cluster, with `Kubernetes <http://kubernetes.io/>`_. But in the future, Tutor may support other deployment platforms.
What is Tutor?
--------------
Where can I try Open edX and Tutor?
-----------------------------------
Tutor was presented at the 2019 Open edX conference in San Diego, CA. Here's the 7-minute talk (with `slides <https://regisb.github.io/openedx2019/>`_):
A demo Open edX platform is available at https://demo.openedx.overhang.io. This platform was deployed using Tutor and the `Indigo theme <https://github.com/overhangio/indigo>`__. Feel free to play around with the following credentials:
.. youtube:: Oqc7c-3qFc4
* Admin user: username=admin email=admin@overhang.io password=admin
* Student user: username=student email=student@overhang.io password=student
Urls:
* LMS: https://demo.openedx.overhang.io
* Analytics (from the `Figures plugin <https://pypi.org/project/tutor-figures/>`__): https://demo.openedx.overhang.io/figures
* Studio (CMS): https://studio.demo.openedx.overhang.io
The platform is reset every day at midnight, `UTC time <https://time.is/UTC>`__, so feel free to try and break things as much as you want.
How does Tutor work?
--------------------
@ -42,18 +87,9 @@ The values from ``config.yml`` are used to generate the environment files in ``e
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 ;-)
Another consequence is that **any manual change made to a file in** ``env/`` **will be overwritten by** ``tutor config save`` **commands**. Consider yourself warned!
Running Open edX
----------------
I'm ready, where do I start?
----------------------------
Now that you have generated a configuration and environment, you probably want to run Open edX.
- The most simple and popular use case is to :ref:`run Open edX locally, on a single server <local>`, with docker-compose.
- If you have a running cluster, you can use Tutor to :ref:`deploy Open edX on Kubernetes <k8s>`.
- Are you an Open edX developer? You can use Tutor for :ref:`hacking into the internals of edx-platform <development>`.
Bells and whistles
------------------
For more advanced usage of Tutor, take a look at the :ref:`configuration and customisation <configuration_customisation>`, the :ref:`existing plugins <existing_plugins>` and the :ref:`extra <extra>` sections
Right :ref:`here <gettingstarted>`!

273
docs/plugins.rst
View File

@ -29,271 +29,7 @@ Enable/disable a plugin::
After enabling or disabling a plugin, the environment should be re-generated with::
tutor config save
API
---
Plugins can affect the behaviour of Tutor at multiple levels. First, plugins can define new services with their Docker images, settings and the right initialisation commands. To do so you will have to define custom :ref:`config <plugin_config>`, :ref:`patches <plugin_patches>`, :ref:`hooks <plugin_hooks>` and :ref:`templates <plugin_templates>`. Then, plugins can also extend the CLI by defining their own :ref:`commands <plugin_command>`.
.. _plugin_config:
config
~~~~~~
The ``config`` attribute is used to modify existing and add new configuration parameters:
* ``config["add"]`` are key/values that should be added to the user-specific ``config.yml`` configuration. Add there passwords, secret keys and other values that do not have a default value.
* ``config["defaults"]`` are default key/values for this plugin. These values will not be added to the ``config.yml`` user file unless users override them manually with ``tutor config save --set ...``.
* ``config["set"]`` are existing key/values that should be modified. Be very careful what you add there! Plugins may define conflicting values for some parameters.
"set" and "default" key names will be automatically prefixed with the plugin name, in upper case.
Example::
config = {
"add": {
"SECRET_KEY": "{{ 8|random_string }}"
}
"defaults": {
"DOCKER_IMAGE": "username/imagename:latest",
},
"set": {
"MASTER_PASSWORD": "h4cked",
},
}
This configuration from the "myplugin" plugin will set the following values:
- ``MYPLUGIN_SECRET_KEY``: an 8-character random string will be generated and stored in the user configuration.
- ``MYPLUGIN_DOCKER_IMAGE``: this value will by default not be stored in ``config.yml``, but ``tutor config printvalue MYPLUGIN_DOCKER_IMAGE`` will print ``username/imagename:latest``.
- ``MASTER_PASSWORD`` will be set to ``h4cked``. Needless to say, plugin developers should avoid doing this.
.. _plugin_patches:
patches
~~~~~~~
Plugin patches affect the rendered environment templates. In many places the Tutor templates include calls to ``{{ patch("patchname") }}``. This grants plugin developers the possibility to modify the content of rendered templates. Plugins can add content in these places by adding values to the ``patches`` attribute.
.. note::
The list of existing patches can be found by searching for `{{ patch(` strings in the Tutor source code::
git grep "{{ patch"
The list of patches can also be browsed online `on Github <https://github.com/search?utf8=✓&q={{+patch+repo%3Aoverhangio%2Ftutor+path%3A%2Ftutor%2Ftemplates&type=Code&ref=advsearch&l=&l= 8>`__.
Example::
patches = {
"local-docker-compose-services": """redis:
image: redis:latest"""
}
This will add a Redis instance to the services run with ``tutor local`` commands.
.. note::
The ``patches`` attribute can be a callable function instead of a static dict value.
.. _plugin_hooks:
hooks
~~~~~
Hooks are actions that are run during the lifetime of the platform. For instance, hooks are used to trigger database initialisation and migrations. Each hook has a different specification.
``init``
++++++++
The services that will be run during initialisation should be added to the ``init`` hook, for instance for database creation and migrations.
Example::
hooks = {
"init": ["myservice1", "myservice2"]
}
During initialisation, "myservice1" and "myservice2" will be run in sequence with the commands defined in the templates ``myplugin/hooks/myservice1/init`` and ``myplugin/hooks/myservice2/init``.
``pre-init``
++++++++++++
This hook will be executed just before the ``init`` hooks. Otherwise, the specs are identical. This is useful for creating databases or other resources that will be required during initialisation, for instance.
``build-image``
+++++++++++++++
This is a hook that will be run to build a docker image for the requested service.
Example::
hooks = {
"build-image": {"myimage": "myimage:latest"}
}
With this hook, users will be able to build the ``myimage:latest`` docker image by running::
tutor images build myimage
or::
tutor images build all
This assumes that there is a ``Dockerfile`` file in the ``myplugin/build/myimage`` subfolder of the plugin templates directory.
``remote-image``
++++++++++++++++
This hook allows pulling/pushing images from/to a docker registry.
Example::
hooks = {
"remote-image": {"myimage": "myimage:latest"},
}
With this hook, users will be able to pull and push the ``myimage:latest`` docker image by running::
tutor images pull myimage
tutor images push myimage
or::
tutor images pull all
tutor images push all
.. _plugin_templates:
templates
~~~~~~~~~
In order to define plugin-specific hooks, a plugin should also have a template directory that includes the plugin hooks. The ``templates`` attribute should point to that directory.
Example::
import os
templates = os.path.join(os.path.abspath(os.path.dirname(__file__)), "templates")
With the above declaration, you can store plugin-specific templates in the ``templates/myplugin`` folder next to the ``plugin.py`` file.
.. _plugin_command:
command
~~~~~~~
A plugin can provide custom command line commands. Commands are assumed to be `click.Command <https://click.palletsprojects.com/en/7.x/api/#commands>`__ objects.
Example::
import click
@click.command(help="I'm a plugin command")
def command():
click.echo("Hello from myplugin!")
Any user who installs the ``myplugin`` plugin can then run::
$ tutor myplugin
Hello from myplugin!
You can even define subcommands by creating `command groups <https://click.palletsprojects.com/en/7.x/api/#click.Group>`__::
import click
@click.group(help="I'm a plugin command group")
def command():
pass
@click.command(help="I'm a plugin subcommand")
def dosomething():
click.echo("This subcommand is awesome")
This would allow any user to run::
$ tutor myplugin dosomething
This subcommand is awesome
See the official `click documentation <https://click.palletsprojects.com/en/7.x/>`__ for more information.
Creating a new plugin
---------------------
Plugins can be created in two different ways: either as plain YAML files or installable Python packages. YAML files are great when you need to make minor changes to the default platform, such as modifying settings. For creating more complex applications, it is recommended to create python packages.
YAML file
~~~~~~~~~
YAML files that are stored in the tutor plugins root folder will be automatically considered as plugins. The location of the plugin root can be found by running::
tutor plugins printroot
On Linux, this points to ``~/.local/share/tutor-plugins``. The location of the plugin root folder can be modified by setting the ``TUTOR_PLUGINS_ROOT`` environment variable.
YAML plugins need to define two extra keys: "name" and "version". Custom CLI commands are not supported by YAML plugins.
Let's create a simple plugin that adds your own `Google Analytics <https://analytics.google.com/>`__ tracking code to your Open edX platform. We need to add the ``GOOGLE_ANALYTICS_ACCOUNT`` and ``GOOGLE_ANALYTICS_TRACKING_ID`` settings to both the LMS and the CMS settings. To do so, we will only have to create the ``openedx-common-settings`` patch, which is shared by the development and the production settings both for the LMS and the CMS. First, create the plugin directory::
mkdir "$(tutor plugins printroot)"
Then add the following content to the plugin file located at ``$(tutor plugins printroot)/myplugin.yml``::
name: myplugin
version: 0.1.0
patches:
openedx-common-settings: |
# myplugin special settings
GOOGLE_ANALYTICS_ACCOUNT = "UA-654321-1"
GOOGLE_ANALYTICS_TRACKING_ID = "UA-654321-1"
Of course, you should replace your Google Analytics tracking code with your own. You can verify that your plugin is correctly installed, but not enabled yet::
$ tutor plugins list
myplugin@0.1.0 (disabled)
You can then enable your newly-created plugin::
tutor plugins enable myplugin
Update your environment to apply changes from your plugin::
tutor config save
You should be able to view your changes in every LMS and CMS settings file::
grep -r myplugin "$(tutor config printroot)/env/apps/openedx/settings/"
Now just restart your platform to start sending tracking events to Google Analytics::
tutor local quickstart
That's it! And it's very easy to share your plugins. Just upload them to your Github repo and share the url with other users. They will be able to install your plugin by running::
tutor plugins install https://raw.githubusercontent.com/username/yourrepo/master/myplugin.yml
Python package
~~~~~~~~~~~~~~
Creating a plugin as a Python package allows you to define more complex logic and to store your patches in a more structured way. Python Tutor plugins are regular Python packages that define a specific entrypoint: ``tutor.plugin.v0``.
Example::
from setuptools import setup
setup(
...
entry_points={"tutor.plugin.v0": ["myplugin = myplugin.plugin"]},
)
The ``myplugin.plugin`` python module should then declare the ``config``, ``hooks``, etc. attributes that will define its behaviour.
To get started on the right foot, it is strongly recommended to create your first plugin with the `tutor plugin cookiecutter <https://github.com/overhangio/cookiecutter-tutor-plugin>`__::
pip install cookiecutter
cookiecutter https://github.com/overhangio/cookiecutter-tutor-plugin.git
pip install -e ./tutor-myplugin
tutor plugins list # your plugin should appear here
tutor plugins enable myplugin # hack at it!
.. _existing_plugins:
Existing plugins
@ -305,3 +41,12 @@ Existing plugins
- `MinIO <https://pypi.org/project/tutor-minio>`__: S3 emulator for object storage and scalable Open edX deployment.
- `Notes <https://pypi.org/project/tutor-notes>`__: Allows students to annotate portions of the courseware.
- `Xqueue <https://pypi.org/project/tutor-xqueue>`__: for external grading
Plugin development
------------------
.. toctree::
:maxdepth: 2
plugins/api
plugins/gettingstarted

184
docs/plugins/api.rst Normal file
View File

@ -0,0 +1,184 @@
Plugin API
==========
Plugins can affect the behaviour of Tutor at multiple levels. First, plugins can define new services with their Docker images, settings and the right initialisation commands. To do so you will have to define custom :ref:`config <plugin_config>`, :ref:`patches <plugin_patches>`, :ref:`hooks <plugin_hooks>` and :ref:`templates <plugin_templates>`. Then, plugins can also extend the CLI by defining their own :ref:`commands <plugin_command>`.
.. _plugin_config:
config
~~~~~~
The ``config`` attribute is used to modify existing and add new configuration parameters:
* ``config["add"]`` are key/values that should be added to the user-specific ``config.yml`` configuration. Add there passwords, secret keys and other values that do not have a default value.
* ``config["defaults"]`` are default key/values for this plugin. These values will not be added to the ``config.yml`` user file unless users override them manually with ``tutor config save --set ...``.
* ``config["set"]`` are existing key/values that should be modified. Be very careful what you add there! Plugins may define conflicting values for some parameters.
"set" and "default" key names will be automatically prefixed with the plugin name, in upper case.
Example::
config = {
"add": {
"SECRET_KEY": "{{ 8|random_string }}"
}
"defaults": {
"DOCKER_IMAGE": "username/imagename:latest",
},
"set": {
"MASTER_PASSWORD": "h4cked",
},
}
This configuration from the "myplugin" plugin will set the following values:
- ``MYPLUGIN_SECRET_KEY``: an 8-character random string will be generated and stored in the user configuration.
- ``MYPLUGIN_DOCKER_IMAGE``: this value will by default not be stored in ``config.yml``, but ``tutor config printvalue MYPLUGIN_DOCKER_IMAGE`` will print ``username/imagename:latest``.
- ``MASTER_PASSWORD`` will be set to ``h4cked``. Needless to say, plugin developers should avoid doing this.
.. _plugin_patches:
patches
~~~~~~~
Plugin patches affect the rendered environment templates. In many places the Tutor templates include calls to ``{{ patch("patchname") }}``. This grants plugin developers the possibility to modify the content of rendered templates. Plugins can add content in these places by adding values to the ``patches`` attribute.
.. note::
The list of existing patches can be found by searching for `{{ patch(` strings in the Tutor source code::
git grep "{{ patch"
The list of patches can also be browsed online `on Github <https://github.com/search?utf8=✓&q={{+patch+repo%3Aoverhangio%2Ftutor+path%3A%2Ftutor%2Ftemplates&type=Code&ref=advsearch&l=&l= 8>`__.
Example::
patches = {
"local-docker-compose-services": """redis:
image: redis:latest"""
}
This will add a Redis instance to the services run with ``tutor local`` commands.
.. note::
The ``patches`` attribute can be a callable function instead of a static dict value.
.. _plugin_hooks:
hooks
~~~~~
Hooks are actions that are run during the lifetime of the platform. For instance, hooks are used to trigger database initialisation and migrations. Each hook has a different specification.
``init``
++++++++
The services that will be run during initialisation should be added to the ``init`` hook, for instance for database creation and migrations.
Example::
hooks = {
"init": ["myservice1", "myservice2"]
}
During initialisation, "myservice1" and "myservice2" will be run in sequence with the commands defined in the templates ``myplugin/hooks/myservice1/init`` and ``myplugin/hooks/myservice2/init``.
``pre-init``
++++++++++++
This hook will be executed just before the ``init`` hooks. Otherwise, the specs are identical. This is useful for creating databases or other resources that will be required during initialisation, for instance.
``build-image``
+++++++++++++++
This is a hook that will be run to build a docker image for the requested service.
Example::
hooks = {
"build-image": {"myimage": "myimage:latest"}
}
With this hook, users will be able to build the ``myimage:latest`` docker image by running::
tutor images build myimage
or::
tutor images build all
This assumes that there is a ``Dockerfile`` file in the ``myplugin/build/myimage`` subfolder of the plugin templates directory.
``remote-image``
++++++++++++++++
This hook allows pulling/pushing images from/to a docker registry.
Example::
hooks = {
"remote-image": {"myimage": "myimage:latest"},
}
With this hook, users will be able to pull and push the ``myimage:latest`` docker image by running::
tutor images pull myimage
tutor images push myimage
or::
tutor images pull all
tutor images push all
.. _plugin_templates:
templates
~~~~~~~~~
In order to define plugin-specific hooks, a plugin should also have a template directory that includes the plugin hooks. The ``templates`` attribute should point to that directory.
Example::
import os
templates = os.path.join(os.path.abspath(os.path.dirname(__file__)), "templates")
With the above declaration, you can store plugin-specific templates in the ``templates/myplugin`` folder next to the ``plugin.py`` file.
.. _plugin_command:
command
~~~~~~~
A plugin can provide custom command line commands. Commands are assumed to be `click.Command <https://click.palletsprojects.com/en/7.x/api/#commands>`__ objects.
Example::
import click
@click.command(help="I'm a plugin command")
def command():
click.echo("Hello from myplugin!")
Any user who installs the ``myplugin`` plugin can then run::
$ tutor myplugin
Hello from myplugin!
You can even define subcommands by creating `command groups <https://click.palletsprojects.com/en/7.x/api/#click.Group>`__::
import click
@click.group(help="I'm a plugin command group")
def command():
pass
@click.command(help="I'm a plugin subcommand")
def dosomething():
click.echo("This subcommand is awesome")
This would allow any user to run::
$ tutor myplugin dosomething
This subcommand is awesome
See the official `click documentation <https://click.palletsprojects.com/en/7.x/>`__ for more information.

77
docs/plugins/gettingstarted.rst Normal file
View File

@ -0,0 +1,77 @@
Getting started with plugin development
=======================================
Plugins can be created in two different ways: either as plain YAML files or installable Python packages. YAML files are great when you need to make minor changes to the default platform, such as modifying settings. For creating more complex applications, it is recommended to create python packages.
YAML file
~~~~~~~~~
YAML files that are stored in the tutor plugins root folder will be automatically considered as plugins. The location of the plugin root can be found by running::
tutor plugins printroot
On Linux, this points to ``~/.local/share/tutor-plugins``. The location of the plugin root folder can be modified by setting the ``TUTOR_PLUGINS_ROOT`` environment variable.
YAML plugins need to define two extra keys: "name" and "version". Custom CLI commands are not supported by YAML plugins.
Let's create a simple plugin that adds your own `Google Analytics <https://analytics.google.com/>`__ tracking code to your Open edX platform. We need to add the ``GOOGLE_ANALYTICS_ACCOUNT`` and ``GOOGLE_ANALYTICS_TRACKING_ID`` settings to both the LMS and the CMS settings. To do so, we will only have to create the ``openedx-common-settings`` patch, which is shared by the development and the production settings both for the LMS and the CMS. First, create the plugin directory::
mkdir "$(tutor plugins printroot)"
Then add the following content to the plugin file located at ``$(tutor plugins printroot)/myplugin.yml``::
name: myplugin
version: 0.1.0
patches:
openedx-common-settings: |
# myplugin special settings
GOOGLE_ANALYTICS_ACCOUNT = "UA-654321-1"
GOOGLE_ANALYTICS_TRACKING_ID = "UA-654321-1"
Of course, you should replace your Google Analytics tracking code with your own. You can verify that your plugin is correctly installed, but not enabled yet::
$ tutor plugins list
myplugin@0.1.0 (disabled)
You can then enable your newly-created plugin::
tutor plugins enable myplugin
Update your environment to apply changes from your plugin::
tutor config save
You should be able to view your changes in every LMS and CMS settings file::
grep -r myplugin "$(tutor config printroot)/env/apps/openedx/settings/"
Now just restart your platform to start sending tracking events to Google Analytics::
tutor local quickstart
That's it! And it's very easy to share your plugins. Just upload them to your Github repo and share the url with other users. They will be able to install your plugin by running::
tutor plugins install https://raw.githubusercontent.com/username/yourrepo/master/myplugin.yml
Python package
~~~~~~~~~~~~~~
Creating a plugin as a Python package allows you to define more complex logic and to store your patches in a more structured way. Python Tutor plugins are regular Python packages that define a specific entrypoint: ``tutor.plugin.v0``.
Example::
from setuptools import setup
setup(
...
entry_points={"tutor.plugin.v0": ["myplugin = myplugin.plugin"]},
)
The ``myplugin.plugin`` python module should then declare the ``config``, ``hooks``, etc. attributes that will define its behaviour.
To get started on the right foot, it is strongly recommended to create your first plugin with the `tutor plugin cookiecutter <https://github.com/overhangio/cookiecutter-tutor-plugin>`__::
pip install cookiecutter
cookiecutter https://github.com/overhangio/cookiecutter-tutor-plugin.git
pip install -e ./tutor-myplugin
tutor plugins list # your plugin should appear here
tutor plugins enable myplugin # hack at it!

4
docs/quickstart.rst
View File

@ -1,7 +1,7 @@
.. _quickstart:
Quickstart (1-click install)
============================
----------------------------
1. `Download <https://github.com/overhangio/tutor/releases>`_ the latest stable release of Tutor, uncompress the file and place the ``tutor`` executable in your path. From the command line:
@ -22,4 +22,4 @@ Yes :) This is what happens when you run ``tutor local quickstart``:
The whole procedure should require less than 10 minutes, on a server with a good bandwidth. Note that your host environment will not be affected in any way, since everything runs inside docker containers. Root access is not even necessary.
There's a lot more to Tutor than that! To understand what Tutor does and how it works, take a look at the :ref:`introduction <intro>`.
There's a lot more to Tutor than that! To understand what Tutor does and how it works, take a look at the :ref:`getting started guide <gettingstarted>`.

11
docs/run.rst Normal file
View File

@ -0,0 +1,11 @@
.. _run:
Running Open edX
================
.. toctree::
:maxdepth: 2
local
k8s
dev

2
docs/testimonials.rst
View File

@ -1,5 +1,5 @@
User testimonials
=================
-----------------
*"Tutor is an absolutely fabulous initiative"* -- Lionel Meinertzhagen, Learning engineer - `Université Libre de Bruxelles <https://www.ulb.be/>`__

2
docs/tutor.rst
View File

@ -63,7 +63,7 @@ Releasing a new version
-----------------------
- Bump the ``__version__`` value in ``tutor/__about__.py``.
- Replace "Latest" by the version name in CHANGELOG.md.
- Replace "Latest" by the version name and date in CHANGELOG.md.
- Create a commit with the version changelog.
- ``make release`` (this assumes that there are two remotes named "origin" and "overhangio")

31
docs/whatnext.rst Normal file
View File

@ -0,0 +1,31 @@
.. _whatnext:
What next?
==========
You have gone through the :ref:`Quickstart installation <quickstart>`: at this point you should have a running Open edX platform. If you don't, please follow the instructions from the :ref:`Troubleshooting <troubleshooting>` section.
Making Open edX look better
---------------------------
Tutor makes it easy to :ref:`develop <theming>` and :ref:`install <settheme>` your own themes. We also provide `Indigo <https://github.com/overhangio/indigo>`__: a free, customizable theme that you can install today.
Adding features
---------------
Check out the Tutor :ref:`plugins <plugins>`, :ref:`extra features <extra>` and :ref:`configuration/customization options <configuration_customisation>`.
Hacking into Open edX
---------------------
Tutor works great as a development environment for Open edX developers, both for debugging and developing new features. Please check out the :ref:`development documentation <development>`.
Deploying to Kubernetes
-----------------------
Yes, Tutor comes with Kubernetes deployment support :ref:`out of the box <k8s>`.
Meeting the community
---------------------
Ask your questions and chat with the Tutor community on the official community forums: https://discuss.overhang.io