Enable and Test Event Bus–Based XQueue Submissions

Enable and Test Event Bus–Based XQueue Submissions#

This guide explains how to enable and test event bus–based XQueue submissions in openedx-platform. It is written for Open edX contributors and operators who want to validate event-driven external grading on the master branch.

Architecture Overview #

With event bus enabled, submission flow changes from direct polling to event-driven routing:

Learner Submission

→ LMS stores submission

→ LMS publishes submission event

→ Event bus distributes event

→ XQueue worker / watcher consumes event

→ Watcher posts result via edx-submissions API

→ LMS updates grade

The watcher authenticates using a Django superuser that must belong to the xqueue group.

Prerequisites #

Local clone of openedx-platform (master branch recommended)
Custom watcher script (e.g., XQueue Custom Watcher Script)
Django superuser account
Superuser added to group named xqueue
Event bus enabled in LMS settings
edx-submissions service available

Environment Setup #

Option A (Using Tutor (Recommended Modern Setup))#

Repository reference: overhangio/tutor

Step 1. Install Tutor#

pip install tutor

Initialize:

tutor local quickstart

Start platform:

tutor local start

Step 2. Create Superuser#

tutor local run lms ./manage.py createsuperuser

Step 3. Create `xqueue` Group#

tutor local run lms ./manage.py shell

Then:

from django.contrib.auth.models import Group
Group.objects.get_or_create(name="xqueue")

Add user to group:

from django.contrib.auth import get_user_model
User = get_user_model()
user = User.objects.get(username="your_username")
user.groups.add(Group.objects.get(name="xqueue"))

Step 4. Ensure Event Bus is Running#

Tutor uses RabbitMQ by default.

Verify:

tutor local ps

RabbitMQ should be listed.

Step 5. Enable XQueue Event Bus Waffle Flag#

Open LMS admin:

http://localhost:8000/admin

Go to:

Waffle → Flags

Create flag:

Name: enable_xqueue_event_bus

Active: True

Rollout: 100

Optional: course override via Waffle → Overrides.

Option B (Using Deprecated Legacy Devstack)#

Repository reference: edx/devstack

Step 1. Clone and Start Devstack#

git clone https://github.com/edx/devstack.git
cd devstack
make dev.up

This brings up LMS, CMS, MySQL, Mongo, RabbitMQ, etc.

To rebuild after changes:

make dev.build
make dev.up

Step 2. Create Superuser#

make lms-shell

Inside container:

./manage.py createsuperuser

Step 3. Create `xqueue` Group#

Inside LMS shell:

from django.contrib.auth.models import Group
Group.objects.get_or_create(name="xqueue")

Add superuser to group:

from django.contrib.auth import get_user_model
User = get_user_model()
user = User.objects.get(username="your_username")
user.groups.add(Group.objects.get(name="xqueue"))

Step 4. Enable Event Bus#

Ensure RabbitMQ container is running:

docker ps | grep rabbit

If needed:

make dev.up

Confirm event bus settings in LMS environment file.

Create Advanced `code_response` Problem #

In Studio, add Advanced problem with:

<problem display_name="XQueue Event Bus Test Problem">
  <response
      response_type="code_response"
      label="Enter any code"
      language="python"
      max_attempts="5"
      grader="xqueue">
  </response>
</problem>

Ensure:

grader="xqueue"
The course is published

Running the Custom Watcher #

Ensure credentials inside watcher:

LMS_URL = "http://localhost:8000"
USERNAME = "admin"
PASSWORD = "password"

Run:

python custom_watcher.py

Expected output:

Connected to LMS Polling for jobs Graded submission with score = 1

Submit as Learner #

Log in as learner
Open problem
Submit response
Wait a few seconds

You should see score update automatically.

Verification and Debugging #

Check Submissions in Django Shell#

from submissions.models import Submission
Submission.objects.all()

Check Logs#

Tutor:

tutor local logs lms

Legacy Devstack:

docker logs lms

Common Issues#

403 Forbidden → User not in xqueue group

No grading → Watcher not running

No event → Waffle flag disabled

Auth failure → Wrong credentials

Final Checklist #

Tutor (or Devstack) running
Superuser created
xqueue group exists
User added to xqueue group
Waffle flag enabled
Advanced problem created
Watcher running
Submission graded successfully

Enable and Test Event Bus–Based XQueue Submissions

Contents

Enable and Test Event Bus–Based XQueue Submissions#

Option A (Using Tutor (Recommended Modern Setup))#

Step 1. Install Tutor#

Step 2. Create Superuser#

Step 3. Create xqueue Group#

Step 4. Ensure Event Bus is Running#

Step 5. Enable XQueue Event Bus Waffle Flag#

Option B (Using Deprecated Legacy Devstack)#

Step 1. Clone and Start Devstack#

Step 2. Create Superuser#

Step 3. Create xqueue Group#

Step 4. Enable Event Bus#

Check Submissions in Django Shell#

Check Logs#

Common Issues#

Step 3. Create `xqueue` Group#

Step 3. Create `xqueue` Group#