Tutor (Open edX) MFE Development: A Personal Experience

But first, Happy Eid al-Fitr day! Hope it's a fantastic one filled with joy and yummy treats with your nearest and dearest. 🌙✨

Disclaimer: Just a heads-up, this is me sharing my adventure in developing Micro Frontend (MFE) components for Tutor LMS (Open edX) on my Apple M1 chip. I'm rocking Tutor v17 (Quince release) for this journey. This guide might have its quirks, but hey, it worked for me!

🛠 Installation

📋 Requirements

• Supported OS: Tutor runs on any 64-bit, UNIX-based OS. It was also reported to work on Windows (with WSL 2).

• Architecture: Both AMD64 and ARM64 are supported.

• Required software:

  • Docker: v24.0.5+ (with BuildKit 0.11+)

  • Docker Compose: v2.0.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 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

🚀 Tutor Installation

I totally recommend going with the Python version. Here's how to get the latest Tutor on your block, based on your OS:

# Let's create a cozy virtual environment for Tutor
$ python3 -m venv tutorvenv

# Time to step into our new virtual home
$ source tutorvenv/bin/activate

# And finally, let Tutor move in
$ pip install "tutor[full]"

Boom! You've got Tutor LMS chilling on your machine. Ready to whip up some Micro Frontend magic!

🏃 Running Tutor Locally

Got Tutor all set up? Sweet! Let's get it running locally for all your development shenanigans (don't forget to start Docker Desktop first):

$ tutor dev launch

This might take a hot minute (or several), depending on how fast your internet is and what your hardware setup looks like. Once it's done, Tutor will be hanging out at http://localhost:8000.

Run into a ProgrammingError: relation "django_content_type" already exists error? No sweat, just fix it with:

$ tutor dev run lms python manage.py lms migrate --fake-initial

And give tutor dev launch another go.

🎨 MFE Development

Let's play around with frontend-app-learner-dashboard as our guinea pig.

🌶 Modify The MFE Plugin

Now, the spicy part. Navigating MFE development in Tutor as a newbie can be a bit like finding a needle in a haystack due to some sparse documentation. But here's the gist:

1. Skip the tutor plugins install mfe command. It'll just pull the default MFE instead of your custom masterpiece. You can, but you will need to create a custom plugin to patch the original MFE plugin with your customizations.

2. Time to clone the MFE repo for some prep work:

$ git clone https://github.com/overhangio/tutor-mfe.git

3. Install the plugin by running:

$ pip install -e tutor-mfe

4. This puts the MFE plugin in editable mode, so your tweaks are live without reinstallation.

5. Modify the /tutor-mfe/tutormfe/plugin.py file to introduce your custom MFE component repository (you will need to put your MFE project in a GitHub repository). For example:

// Original
"learner-dashboard": {
        "repository": "https://github.com/openedx/frontend-app-learner-dashboard.git",
        "port": 1996,
    },

// Your custom MFE
"learner-dashboard": {
        "repository": "https://github.com/{USERNAME}/frontend-app-learner-dashboard.git",
        "port": 1996,
    },

🧐 Keep an eye on the GitHub username part. Make sure your repo name matches up.

🚀 MFE Development

Assuming you're flying without a GitHub repo for your MFE for now, you can tether your local development code directly to the plugin:

$ tutor mounts add /path/to/your/frontend-app-learner-dashboard

Then seal the deal with:

$ tutor config save

Fire up Tutor again if you need to:

$ tutor dev launch

Now, any ninja moves you pull on your frontend-app-learner-dashboard code in your local dojo will show up live in Tutor, no GitHub middleman required.

🧠 QnA for Curious Mind

Question	Answer
Do I need to hit npm start every time?	Nah, tutor dev launch has got you covered. It'll get your MFE code up and running, no manual start required. Just give it a sec longer than usual to see your changes.
Should I run tutor config save after every code change?	Nope, once is enough.
Where do I find my shiny new MFE after tweaking it?	It depends on which MFE you're dabbling with. Check out /tutor-mfe/tutormfe/plugin.py (from previous MFE plugin installation step) for the details. For instance, the learner dashboard lives at http://apps.local.edly.io:{PORT}/learner-dashboard/, with the port customizable in your MFE's .env.development.
I run into a ProgrammingError: relation "django_content_type" already exists error. What to do?	Squash it with the tutor dev run lms python manage.py lms migrate --fake-initial command.
Which framework does MFE use?	ReactJS
What if I want to modify the template instead of using MFE?	You can start by modifying the indigo theme. This note is dedicated for MFE, and not template.
I have another question!	Head to Open edX discussion forum.

Happy coding, folks! 🎉