Tutor FAQs for Documentation

[john_curricume (John Swope)]

In today’s Documentation WG, the conversation centered around the Tutor docs and how Tutor docs and docs.openedx.org live together and support each other.

Not all questions were answered but a shared action item was trying to document (or point to existing docs for) the most commonly asked FAQs around Tutor. A loose goal at this point is to determine a Tutor superuser who can answer these FAQs and have the documentation WG transform them into searchable written docs.

Add your own FAQs here.

Format is

Title

Additional Details and links

[sarina (Sarina Canelake)]

I’ll add that it would be helpful, as well, for people to post FAQ’s they’ve previously had and answers to the questions, if you’ve discovered the answer already. Any internal documentation you have - notes on stickies even - that you’d like to see rendered in the public docs would be helpful!

[john_curricume (John Swope)]

Enabling/Disabling Feature Flags

This is documented with an example but I don’t think the example covers enough use cases or describes how to trace a feature that you want to enable through tutor. I documented my case here, but I struggled with: a) what is the right patch name (openedx-lms-common-settings & openedx-cms-common-settings) and b) when to use FEATURE as in this example vs not as in this example.

Enable a plugin

Take forum for example. The majority of new users I think want to enable this, but I can’t see it mentioned in the official tutor docs, only in old support responses. Very common use case and very easy win (“I turned something important on!”) for a new user.

Switch the Theme

I almost never switch the theme and it is documented, but I tried to test it just now by.

1. Copying indigo theme directory to indigo2.
2. Making a test change in the footer.index

<span class="copyright-site">Copyrights ©${datetime.now().year}. All Rights Reserved EDIT.</span>

<span class="copyright-site">Copyrights ©${datetime.now().year}. All Rights Reserved EDIT2.</span>

3. Rebuild the openedx Docker image and use settheme to switch themes:

tutor images build openedx
tutor local do settheme indigo2

In the django admin, now indigo2 is the set theme, but my changes don’t seem reflected:

Enable Python and Javascript Xblocks

Every new Open edX install going back some time leads to this unpleasant error:

I know this is brought up in many discussion forums, but I’m still unclear if it is totally unavailable when installing via Tutor or if there is an approach to fixing. This should be clear from Tutor docs.

• Codejail cannot run without a user set · Issue #162 · openedx/codejail · GitHub
• ("[Errno 2] No such file or directory: 'TMPDIR=tmp'", ) - #6 by Jonathan
• [Errno 2] No such file or directory: 'TMPDIR=tmp'

(In that last discuss post, seems like there is a best-practice solution for this. )

[FarazM (Muhammad Faraz Maqsood)]

@john_curricume

Enable Python and Javascript Xblocks

Every new Open edX install going back some time leads to this unpleasant error:

I know this is brought up in many discussion forums, but I’m still unclear if it is totally unavailable when installing via Tutor or if there is an approach to fixing. This should be clear from Tutor docs.

• Codejail cannot run without a user set · Issue #162 · openedx/codejail · GitHub
• (“[Errno 2] No such file or directory: ‘TMPDIR=tmp’”, ) - #6 by Jonathan
• [Errno 2] No such file or directory: ‘TMPDIR=tmp’

(In that last discuss post, seems like there is a best-practice solution for this. )

Regarding codejail, I have gone through all the Links & details you have attached, codejail repo has already this issue(Link) opened, as you noted.

I also agree that this(Link) is a best-practice solution for above codejail issue.

And it would be good to add this part in tutor documentation, that start using tutor-contrib-codejail if using tutor as mentioned in above link although its not an official tutor plugin. These kind of FAQs can be added to a separate section i.e.unofficial tutor plugins & apps in tutor docs.

[eemaanamir]

@john_curricume

Enabling/Disabling Feature Flags

This is documented with an example but I don’t think the example covers enough use cases or describes how to trace a feature that you want to enable through tutor. I documented my case here, but I struggled with: a) what is the right patch name (openedx-lms-common-settings & openedx-cms-common-settings) and b) when to use FEATURE as in this example vs not as in this example.

Thanks for raising this — the missing piece in the docs is really about how to trace a setting and then choose the correct patch target.

The correct approach is:

1. Find where the setting is defined in the Open edX platform.
   Search the Open edX repository for the setting name (e.g., ENTRANCE_EXAMS, ALLOW_PUBLIC_ACCOUNT_CREATION, etc.).

2. Identify how it is defined:

   • If it is inside the FEATURES dictionary, e.g.
     FEATURES['ENTRANCE_EXAMS'] = True
     then it is a feature flag.

   • If it is defined as a standalone Django setting, e.g.
     SOME_SETTING = ...
     then it should be patched as a regular variable.

3. Decide where it should apply based on your use case:

   • LMS only → openedx-lms-common-settings

   • CMS only → openedx-cms-common-settings

   • Entire platform → openedx-common-settings (preferred when applicable)

You can then choose the appropriate patch target from the Tutor patch catalogue:
https://docs.tutor.edly.io/reference/patches.html

In short:

• Settings defined inside FEATURES are patched as FEATURES['FLAG_NAME'] = value

• Settings defined as regular variables are patched directly as VARIABLE_NAME = value

• The patch target (lms, cms, or common) depends on whether you want it applied to one service or both.

Once you locate the setting in the platform code and determine its scope, selecting the right patch becomes straightforward using the catalogue.

I agree this tracing step isn’t clearly documented today, and we will improve on that.

[eemaanamir]

@john_curricume

Enable a plugin

Take forum for example. The majority of new users I think want to enable this, but I can’t see it mentioned in the official tutor docs, only in old support responses. Very common use case and very easy win (“I turned something important on!”) for a new user.

Regarding this, correct me if I am wrong, you mean mentioning the forum or any plugin that a new user can enable/disable? If that’s the case, we can mention that many Open edX features are distributed as Tutor plugins and are not enabled by default. Tutor keeps the core minimal, so operators explicitly enable only what they need.

To see all installed plugins and their status:

tutor plugins list

To enable a plugin (e.g., forum):

tutor plugins enable forum
tutor config save
tutor local restart

The same applies to any other bundled plugin. We’ll add this to the Quick Start guide, including a list of default plugins enabled, since it’s currently missing and is a common first step for new users.

[FarazM (Muhammad Faraz Maqsood)]

@john_curricume

Switch the Theme

I almost never switch the theme and it is documented, but I tried to test it just now by.

1. Copying indigo theme directory to indigo2.
2. Making a test change in the footer.index

<span class="copyright-site">Copyrights ©${datetime.now().year}. All Rights Reserved EDIT.</span>

<span class="copyright-site">Copyrights ©${datetime.now().year}. All Rights Reserved EDIT2.</span>

3. Rebuild the openedx Docker image and use settheme to switch themes:

tutor images build openedx
tutor local do settheme indigo2

In the django admin, now indigo2 is the set theme, but my changes don’t seem reflected.

Your steps seems right to me.

1. I have copied indigo theme directory to indigo2.

2. Made changes to footer.html

3. Them instead of rebuilding images which takes time, I ran tutor dev run lms bash followed by ./manage.py lms collectstatic and run tutor local do settheme indigo2. Note: It works with tutor images build openedx as well with one addition step mentioned below.

4. One Additional step I followed, I restarted the LMS container after setting the theme and changes reflected. We can surely add this step to the document. Thanks!

   
   
   

[arunmozhi]

I think there is also catch when it comes to FEATURE flags, they might need to go into lms-env-features instead of openedx-lms-common-settings. Eg., LTI Provider discussion here

@ghassan

In the other words the above code wouldn’t run/evalute if you change it at the settings level but on config level (as suggested above by @michael) would make it evaluate.