Familiarize yourself with Tutor plugin concepts: https://docs.tutor.overhang.io/plugins/intro.html
You can find more information on each of the steps in this document at https://docs.tutor.overhang.io/tutorials/plugin.html#plugin-development-tutorial
Install and run the plugin cookiecutter to create a project skeleton: https://github.com/overhangio/cookiecutter-tutor-plugin
Anywhere you see myplugin in these instructions it will refer to the name of the plugin you have just created
See anything incorrect or missing in the document? Please fix it!
Create a Dockerfile at tutormyplugin/templates/myplugin/build/myplugin/Dockerfile
If you aren’t sure what your service needs take a look at tutor-contrib-exams as a minimal example
This section could probably use more guidance on Dockerfiles…
Add an image build hook to tutormyplugin/plugin.py
################# Docker image management # To build an image with `tutor images build myimage`, add a Dockerfile to templates/exams/build/myimage and write: hooks.Filters.IMAGES_BUILD.add_item(( "myplugin", ("plugins", "myplugin", "build", "myplugin"), "{{ MYPLUGIN_DOCKER_IMAGE }}", (), )) |
Take note of MYPLUGIN_DOCKER_IMAGE
we need to define this config value in plugin.py
as well
######################################## # CONFIGURATION ######################################## hooks.Filters.CONFIG_DEFAULTS.add_items( [ # Add your new settings that have default values here. # Each new setting is a pair: (setting_name, default_value). # Prefix your setting names with 'MYPLUGIN_'. ("MYPLUGIN_VERSION", __version__), ("MYPLUGIN_DOCKER_IMAGE", f'myplugin:{__version__}'), ] ) |
Add docker-compose patches to tutormyplugin/patches
to get your service running locally
To run tutor local and tutor dev you will minimally need:
local-docker-compose-services
local-docker-compose-dev-services
local-docker-compose-jobs-services
As a reference see tutor-contrib-exams or tutor-discovery
Full reference for templates that could be added here https://docs.tutor.overhang.io/reference/patches.html#patches
Create tutor django settings file(s) for your app inside templates/myplugin/apps/setttings/tutor
.
at minimum you’ll need templates/myplugin/apps/settings/tutor/development.py
These files will get mounted into your service's 'settings' folder so you can simply import the existing settings in the repository. This way you only need to define settings that are different in your tutor environment such as urls.
To create additional tutor configuration values that will get rendered you can do that under the CONFIGURATION section of plugin.py
(we did this for MYPLUGIN_DOCKER_IMAGE above)
Mimimal example of tutor/development.py
# tutor/development.py from ..local import * # import local setttins from repo ROOT_URL = "http://{{MYPLUGIN_HOST}}:1111" # MYPLUGIN_HOST defined in plugin.yml {{ patch("exams-development-settings") }} |
If you have common settings across all environments you can create a partial file to reuse in each environment. See https://github.com/overhangio/tutor-discovery/blob/master/tutordiscovery/templates/discovery/apps/settings/partials/common.py as an example in course-discovery.
You service likely has some steps to create database users, run migrations, and run management commands. In devstack these were typically part of a provision script.
For commands that will run against your service, such as running ‘migrate’, add to templates/myplugin/jobs/MYPLUGIN/init
Commands that would run against the mysql container, such as creating a default database user, would get added to templates/myplugin/jobs/MYSQL/init
And so on, where the parent folder indicates the container the script will get executed on
See edx-exams as an example
Install a local copy of your plugin
pip install -e ./myplugin-project-folder |
Enable your plugin
tutor plugins enable myplugin |
Generate config with your plugin enabled
tutor config save |
Run init tasks
tutor dev init |