wagtail-lms 0.8.1

A Learning Management System extension for Wagtail with SCORM 1.2/2004 support

Wagtail LMS

A Learning Management System extension for Wagtail CMS with SCORM 1.2/2004 support.

⚠️ Alpha Release

This package is in early development. That said, it is actively used in production at thinkelearn.com.

Supported versions:

• Python: 3.11, 3.12, 3.13, 3.14
• Django: 4.2 (LTS), 5.0, 5.1, 5.2 (LTS), 6.0
• Wagtail: 6.0, 6.2, 6.3, 7.1, 7.2, 7.3

Selected combinations are tested in CI. See our compatibility matrix for specific version combinations.

Features

• 📚 Course Management - Integrate courses into Wagtail's page system
• 📦 SCORM Support - Full SCORM 1.2 and 2004 package compatibility
• 👥 Enrollment Tracking - Automatic student enrollment and progress monitoring
• 📊 SCORM API - Complete runtime API implementation for content interactivity
• 🔒 Secure Delivery - Path-validated content serving with iframe support
• 💾 Progress Persistence - CMI data model storage with suspend/resume capability
• 🔄 Concurrency Handling - Retry logic for SQLite database lock scenarios
• 🎨 Framework Agnostic - Minimal default styling, easy to customize with any CSS framework

Installation

pip install wagtail-lms

Quick Start

1. Add to INSTALLED_APPS in your Django settings:

   INSTALLED_APPS = [
       # ...
       'wagtail_lms',
       # ...
   ]
   

2. Add wagtail-lms URLs to your urls.py:

   from django.urls import path, include
   
   urlpatterns = [
       # ...
       path('lms/', include('wagtail_lms.urls')),
       # ...
   ]
   

3. Run migrations:

   python manage.py migrate wagtail_lms
   

4. Collect static files:

   python manage.py collectstatic
   

Configuration

Optional settings in your Django settings:

# SCORM package upload directory
WAGTAIL_LMS_SCORM_UPLOAD_PATH = 'scorm_packages/'

# Extracted SCORM content directory
WAGTAIL_LMS_CONTENT_PATH = 'scorm_content/'

# Auto-enroll users when they visit a course
WAGTAIL_LMS_AUTO_ENROLL = False

# Cache-Control rules for SCORM assets (exact MIME, wildcard, and default)
WAGTAIL_LMS_CACHE_CONTROL = {
    "text/html": "no-cache",
    "text/css": "max-age=86400",
    "application/javascript": "max-age=86400",
    "text/javascript": "max-age=86400",
    "image/*": "max-age=604800",
    "font/*": "max-age=604800",
    "default": "max-age=86400",
}

# Redirect audio/video assets to storage URLs (useful for S3 backends)
WAGTAIL_LMS_REDIRECT_MEDIA = False

Usage

Creating a Course

1. Log into Wagtail admin
2. Create a new "Course Page" under Pages
3. Upload a SCORM package via Django Admin → SCORM Packages
4. Assign the SCORM package to your course page

SCORM Package Requirements

• Must be a valid SCORM 1.2 or 2004 ZIP file
• Must contain imsmanifest.xml at the root
• Launch file must be specified in the manifest

Customizing Templates

The package includes minimal, functional styling that works out of the box. To match your project's design:

• Quick: Override the CSS classes in your own stylesheet
• Full control: Override the templates in your project (standard Django approach)
• Examples: See Template Customization Guide for Bootstrap, Tailwind CSS, and Bulma examples

For API-first projects, the templates are optional and can be ignored entirely.

Development

An example project is available in example_project/ for local development and testing. See its README for setup instructions.

Running Tests

The project includes a comprehensive test suite. See current coverage.

# Install testing dependencies (pytest, pytest-django, pytest-cov)
uv sync --extra testing

# Run all tests
PYTHONPATH=. uv run pytest

# Run with coverage report
PYTHONPATH=. uv run pytest --cov=src/wagtail_lms --cov-report=term-missing

# Run specific test file
PYTHONPATH=. uv run pytest tests/test_models.py -v

Database Considerations

SQLite: The package includes retry logic with exponential backoff to handle database lock errors during concurrent SCORM API operations. For development with the example project:

# example_project/settings.py
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": "db.sqlite3",
        "OPTIONS": {
            "timeout": 20,  # Increased timeout for SCORM operations
        },
    }
}

Production: For production deployments, PostgreSQL is recommended for better concurrency handling:

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": "wagtail_lms",
        # ... other PostgreSQL settings
    }
}

Acknowledgments

• Built with Django and Wagtail CMS
• SCORM implementation based on ADL specifications
• Inspired by open-source LMS solutions like Moodle and Open edX

License

This project is licensed under the MIT License. See the LICENSE file for details.