What an Open edX implementation involves
The Open edX platform has two main applications: the LMS, where learners take courses, and Studio, where authors build them. Its core repository, edx-platform, is licensed under the AGPL-3.0, and the project is stewarded by Axim Collaborative, a nonprofit founded by Harvard and MIT. Learner and authoring screens are increasingly React micro-frontends (MFEs) in front of the Django services.
Tutor is the official Docker-based distribution for deploying, customizing and upgrading Open edX, on one host or on Kubernetes. A customized implementation usually means a Tutor configuration, plugins and XBlocks, a branded frontend, integrations with identity and business systems, and a course structure authors can work in.
Discovery covers who builds and reviews courses, self-paced or instructor-paced delivery, how learners are grouped, certificates and programs, the systems that hold learner records and the content to migrate.
Map courses and programs onto Open edX
Open edX organizes learning around course runs and a fixed outline of sections, subsections, units and components.
| Concept | What to decide | Check |
|---|---|---|
| Course keys | Each course is keyed by organization, course number and run, and keys cannot be renamed. Set naming rules, including letter case, before authors start. | Pilot courses follow the naming rules. |
| Runs and pacing | Whether courses are rerun for each intake, and whether runs are self-paced or instructor-paced with dates. | A rerun copies content and applies the new dates. |
| Cohorts and content groups | Whether learners are split into cohorts and whether content groups show different material to each. | A learner sees only the content and discussions for their cohort. |
| Content libraries | Verawood deprecates legacy libraries, so new reusable content goes into Content Libraries and old libraries are migrated. | Library content appears in courses as expected. |
| Programs and certificates | Course certificates are set per course. Programs rely on the separate course discovery and credentials services, which add components to run. | Completing a program's courses issues the expected credential. |
Configuration, extensions and custom code
Tutor builds the platform configuration from its settings, and Tutor plugins add configuration patches, services and image changes. Keep the configuration and your own Tutor plugins in version control so development, staging and production are built the same way.
XBlocks are the component model for course content. A custom XBlock is a Python package with its own frontend code, added to the image build. In Verawood, built-in blocks such as HTML, Video and Problem moved to the xblocks-core package, with the built-in versions planned for removal in Willow, so check custom blocks that extend them.
Django app plugins add backend features without forking edx-platform. The Hooks Extension Framework provides Open edX Events, which notify your code, and Filters, which change platform behavior at defined points. A fork must be rebased onto every named release, so keep changes in plugins and hooks.
MFEs are customized with brand packages and frontend plugin slots. Verawood is the first release to support the new frontend-base architecture, and the project expects all MFEs to be converted by Xylon in June 2027. Build on plugin slots and budget for porting.
Integrations to plan
Open edX connects to other systems through third-party authentication, LTI, REST APIs and events.
Single sign-on
Third-party authentication supports SAML, with the LMS as service provider, and OAuth2 providers through python-social-auth. Decide whether accounts are created on first login and which attributes fill the profile.
Enrollment and records
HR, student or CRM systems can create accounts and enrollments through REST APIs and read grades back. Open edX Events, optionally sent over the event bus, let other services react to changes.
LTI tools
The LTI consumer XBlock embeds external tools, including LTI 1.3 tools, as course components. Test launch and grade passback for each tool.
Tutor's default SMTP server does not implement TLS, so production sites usually send through an external relay. Verawood turns notifications and notification emails on by default.
Analytics
Aspects, a Tutor plugin, builds dashboards on ClickHouse and Superset. By default its reports do not identify individual learners.
Migration, accessibility and rollout
Courses move between Open edX instances as OLX exports from Studio. Learner records do not travel with them, so plan separately for grades and certificates. From Moodle or another LMS, the usual route is an IMS Common Cartridge export converted with cc2olx, an Open edX tool that produces archives Studio can import. It does not convert images, and Moodle exports only some activity types, so expect authors to rebuild assessments and interactive content. Pilot a few courses first.
Transcripts, alternative text and problem markup are authored in Studio, so give authors an accessibility checklist. Custom XBlocks, MFE plugins and brand changes need keyboard, screen reader and contrast testing.
Test on staging built from the same Tutor configuration. Roll out with a pilot course team, then train authors, course staff and administrators.
Hosting and scaling with Tutor
tutor local runs Open edX with Docker Compose on one server. tutor k8s deploys to Kubernetes when services need to scale independently.
| Component | Role | Planning note |
|---|---|---|
| LMS and Studio | Django applications for learners, authors and APIs. | Scale LMS replicas with learner concurrency. |
| Celery workers and Redis | Background work such as grading, exports and email, with Redis as broker and cache. | Watch queue length during launches and bulk email. |
| MySQL | Users, enrollments and grades. | Can be a managed database. Verawood adds PostgreSQL for fresh installs only. |
| MongoDB | Course content structures from Studio. | Can run as a separate cluster. Include it in every backup. |
| Meilisearch | Search backend in current Tutor releases. | Tutor v22 requires a full reindex after its Meilisearch upgrade. |
| Caddy | Web proxy that obtains TLS certificates. | Turn it off when a load balancer terminates TLS. |
Security, privacy and backups
Limit Django admin access to staff who sign in through SSO with multi-factor authentication, and audit superuser and global staff accounts. Apply security fixes by rebuilding images and deploying through your normal pipeline. Custom XBlocks run inside the platform, so review them like any web code.
The user retirement process removes or anonymizes a learner's personal data across services when an account is deleted. Test it with every service you run, including Aspects, and decide what learner identity staff and analytics users can see.
Back up MySQL, MongoDB, uploaded media and the Tutor configuration together; search indexes can be rebuilt. Rehearse a restore and check logins, content, grades and certificates.
Releases, upgrades and common questions
Which release should we deploy?
Verawood, released in mid-2026, is the current named release. Willow is planned for December 2026 and Xylon for June 2027. The project supports only the latest release, so plan to upgrade with each one.
How do upgrades work?
Each Tutor major version targets a named release; Tutor v22 supports Verawood. Upgrade one release at a time on staging, read the operator notes and rebuild images with your plugins. Verawood includes a MariaDB column conversion that rewrites edx-enterprise tables and a course key check that fails on keys differing only by case.
What does the AGPL mean for our customizations?
The AGPL-3.0 requires a modified version offered to users over a network to make its source available to them. Tutor is AGPL, while its plugin and hooks system is Apache 2.0. Confirm obligations with counsel.
Do we need Kubernetes?
Not for every site. tutor local suits pilots and smaller deployments on one server. Kubernetes helps when services must scale separately or several environments share infrastructure.
Open edX operating ownership
Ownership spreads across platform engineers, course teams, developers and the people responsible for learner data.
Platform team
- Maintains Tutor configuration and image builds.
- Upgrades with each named release.
- Monitors workers, databases and search.
Course operations
- Sets naming rules and grading policies.
- Supports authors and course staff.
- Manages cohorts and certificates.
Development
- Owns custom XBlocks, plugins and MFE slots.
- Tracks deprecations in release notes.
- Keeps tests for custom code.
Security and privacy
- Reviews staff and superuser access.
- Verifies user retirement requests.
- Decides learner identification in analytics.
Scope and handover
Effort depends on the number of courses, custom XBlock and frontend work, integrations, migration volume, analytics needs and whether the target is one server or Kubernetes.
DeployOpen runs discovery, designs the course structure, deploys Open edX with Tutor in your infrastructure, builds XBlocks, plugins and frontend components, connects SSO and business systems, sets up Aspects, migrates pilot courses and trains authors and administrators. Security testing and compliance readiness support are available for regulated organizations. Handover includes the Tutor configuration and plugin repositories, a naming guide, integration runbooks, restore test results and an upgrade plan.
