Package: tutor-contrib-coursegraph
CourseGraph is a tool that allowsOpen edXdevelopers and support specialists to inspect their platform instance’s learning content. It consists of two simple components:TheCourseGraph support application, which loads courses from the CMS’s internal course store and dumps them into an instance of…Neo4j, a popular open-source graph database. Staff for an Open edX instance can query the course graph via Neo4j’s Web console using theCypherquery language.CourseGraph was initially an internal tool at edX, Inc., but as of the Maple release it wasshared with the greater Open edX community. This Tutor plugin aims to provide an easy mechanism for developers and operators to trial and deploy CourseGraph.Status & ContributingThis isBetasoftware. It was developed as part of theTutor Adoption Initiativefor the purpose learning about the Tutor Plugin API, and it has been tested to work for with Tutor and Open edX for local development, local deployment, and Kubernetes deployment. However, it hasnotyet been tested with a production Open edX instance. Although this plugin is nominally maintained by the Center for Reimagining Learning, we do not currently have plans to do any comprehensive production-tier testing. You have been warned!If you choose to use this plugin, we’re eager to hear about your experiences! Please let us know by opening an issue in this repository or posting on the Open edX or Tutor forums. Also, if you’re interested in contributing, feel free to open an issue or a pull request. We’ll try to give it a first look within a week.BranchesThis plugin uses the same branching model as Tutor:nightlyLatest development. Compatible with Tutor Nightly and Open edX master. Merged intomasterat each Open edX named release.masterLatest stable release and patches. Compatible with Tutor master and latest Open edX named release. Merged intonightlycontinuously.The syncing between branches is currently done manually.If your change is backwards-compatible with the last Open edX named release, then propose it againstmaster. If not, then propose it againstnightly.This repository aims to adhere to all relevantOpen edX Proposals, includingOEP-55, Conventional Commits.InstallationInstall the latest stable version (requires the latestTutor release):pip install tutor-contrib-coursegraphOr, install the latest nightly version (requiresTutor Nightly):pip install git+https://github.com/openedx/tutor-contrib-coursegraph@nightlyOr, install the plugin to be hacked on:git clone git@github.com:openedx/tutor-contrib-coursegraph
cd tutor-contrib-coursegraph
source {{ PATH TO A VIRTUAL ENVIRONMENT }}
make dev-requirementsSetupEnable the plugin and re-generate your Tutor environment:tutor plugins enable coursegraph
tutor config saveThen, run initialization in order to dump your platform’s existing courses into CourseGraph:tutor [dev|local|k8s] init --limit=coursegraphStart CourseGraph:tutor [dev|local|k8s] start coursegraphUsageFinding the Web interfaceOnce CourseGraph is started and courses have been dumped to it, the tool can be viewed at:http://coursegraph.{{ LMS_HOST }}For example, if your LMS is atopenedx.example.eduand you’re using the default Neo4j HTTP port, that’d be:http://coursegraph.openedx.example.eduWhen running in development mode, you’ll also need to specify port 7474. For example:http://coursegraph.local.overhang.io:7474Using the Web interfaceTheConnect URLshould already be populated correctly. If it’s not, here’s what to enter, substitutingopenedx.example.edufor your own LMS root domain:ModeConnect URLtutor k8sbolt://bolt.coursegraph.openedx.example.edu:80tutor localbolt://bolt.coursegraph.openedx.example.edu:80tutor devbolt://coursegraph.local.overhang.io:7687By default, you can log in usingUsername / Passwordauthentication:Username"neo4j"Password$(tutor config printvalue COURSEGRAPH_NEO4J_PASSWORD)If you setCOURSEGRAPH_NEO4J_PASSWORDtonullbefore initializing CourseGraph, then instead selectNo Authentication.Now that you’re in, tryquerying your courses!OperationsOperating CourseGraph is fairly straightforward, especially if you treat CourseGraph data as a non-critical secondary view into the CMS’s course data. That is: you should be willing to completely drop and re-generate the CourseGraph data stord in Neo4j. By doing so, you avoid needing to back up Neo4j, and you de-risk the Neo4j schema version upgrades that you’ll need to perform over time with new Open edX releases.Managing DataBy default, this plugin configures CMS to dump each course to CourseGraph whenever it is published, allowing you to “set and forget” the tool. You can disable this behavior by settingCOURSEGRAPH_DUMP_COURSE_ON_PUBLISHtofalse, regenerating your Tutor environment, and restarting CMS.If you have disabled automatic dumping, then you’ll need to periodically refresh the data in CourseGraph manually. You can do so via the CMS administration console at, under theCOURSE GRAPH COURSE DUMPSpage in theCOURSE GRAPHapp:Alternatively, you can skip the admin console by using a CMS management command:tutor [dev|local|k8s] exec coursegraph ./manage.py cms dump_to_neo4jManaging Ingress AccessBy default, CourseGraph’s Neo4j service is accessible to the outside world for HTTP and Bolt traffic via Caddy, the proxy provided by Tutor. Neo4j’s bfasic authentication scheme (described inManaging Users) may or may not be sufficient for your security needs. If it isnotsufficient, then you have two options:Use your own Web proxy in place of Tutor’s Caddy service by settingENABLE_WEB_PROXY=false. Via your Web proxy, restrict ingress CourseGraph access as desired. If you’re not already using your own Web proxy, then this is probablynotwhat you want to do, as it’d affect your entire Tutor deployment just for the sake of this plugin.SetCOURSEGRAPH_RUN_NEO4J=falseand self-manage a separate Neo4j service, whose ingress access you could control as desired. Then, configure this plugin to point at your self-managed Neo4j service so that CMS can dump to content to it. See theConfigurationsection for specifics. If you choose to go this route, the authors of this plugin recommend theofficial Neo4j docker imageas a starting point for self-hosting Neo4j.Managing UsersThis plugin currently ships with Neo4j 3.5 Community Edition, which provides some very rudimentary authentication controls via the Neo4j Web console. The Neo4j 3.5 page onprocedures for native user managementdescribes the available operations. Take note that only four operations are available in the Community Edition:CALLdbms.security.createUser(<username>,<password>, <requirePasswordChange>)CALLdbms.security.changePassword(<password>,<requirePasswordChange>)CALLdbms.security.deleteUser(<username>)CALL dbms.security.listUsers()Since authorization control is not availble in the Neo4j Community Edition, all users will have full administrative control over Neo4j data, including ability to to read all graphs, modify nodes, modify relationships, and create new users. Because of this, access to any set of CourseGraph Neo4j credentials confers read access to your entire course catalog, as well as the ability to insert fake data into CourseGraph. As such, if your CourseGraph instance is accessible by the public, thenall Neo4j credential sets should be treated as production secrets.By default, this plugin initializes Neo4j with one user, whose username isneo4jand whose password is set from theCOURSEGRAPH_NEO4J_PASSWORDTutor setting. When CMS pushes data to Neo4j, it also authenticates withneo4jas its username andCOURSEGRAPH_NEO4J_PASSWORDas its password. Keep in mind that:If theneo4juser is destroyed, CMS will be unable to dump new data to Neo4j until a newneo4juser is created.Once CourseGraph is initialized, changingCOURSEGRAPH_NEO4J_PASSWORDalone does not update theneo4juser’s password. You will need to useCALLdbms.security.changePassword(...)from the Neo4j Web console for the password change to take effect.Finally, initializing CourseGraph withCOURSEGRAPH_NEO4J_PASSWORDset to!!nulldisables authentication entirely. Anyone with access to CourseGraph will have full read and write access to the Neo4j database. Obviously, this is only suitable when CourseGraph endpoint access is restricted to trusted private network.ConfigurationThe Tutor plugin can be configured with several settings. The names of all settings below are prefixed withCOURSEGRAPH_.CourseGraph SettingTypeDefaultDescriptionNEO4J_PASSWORDstr(20 random characters)Initialpassword set forneo4juser, as well as password used to by CMS to authenticate asneo4juser. SeeManaging Usersfor more details.NEO4J_VERSIONstr"3.5.28"Version of Neo4j to use. Appended to default image. OverridingNEO4J_DOCKER_IMAGEannuls this setting.NEO4J_DOCKER_IMAGEstr"docker.io/neo4j:3.5.28"Neo4j Docker image to be pulled and used. By default, based on yourDOCKER_REGISTRYandCOURSEGRAPH_NEO4J_VERSION.NEO4J_HOSTstrProd:"coursegraph.www.openedx.com", Dev:"coursegraph.local.overhang.io"Hostname of CourseGraph. By default, based on yourLMS_HOST.DUMP_COURSE_ON_PUBLISHbooltrueShould CMS automatically dump a course to CourseGraph whenever it’s published? If disabled, you will instead need to periodically dump courses via the management command or admin console.RUN_NEO4JbooltrueWhether the Neo4j service should be started. Only disable if you wish to manage your own Neo4j instance outside of Tutor. If you disable this, then setCOURSEGRAPH_NEO4J_HOSTto the hostname of your self-managed instance, setCOURSEGRAPH_NEO4J_PASSWORDto the password of your instance’sneo4juser, and expose port 7687 for unencrypted Bolt traffic.DevelopmentUpgrade version pins:make upgradeRun just static checks:make test-format test-lint test-typesRun all tests:cp $(tutor config printroot)/config.yml tutor_config.bak.yml
make test  # clobbers some Tutor configuration
mv tutor_config.bak.yml $(tutor config printroot)/config.yml  # restore original configLicenseThis software is licensed under the terms of the AGPLv3.