Upgrade an unsupported Open edX release

A site on Redwood, Sumac or Teak usually cannot move straight to the latest named release. Open edX supports only the latest named release at any time, so the upgrade has to pass through Tutor major versions in order, with each step bringing the platform, configuration and data forward to the next point the Tutor project supports. Before any work starts, the team should accept that the upgrade is a sequence of supported stops, not a single version change, and that the number of stops depends on the starting release. Planning the sequence first keeps the rest of the project honest about scope, testing and rollback.

The step list is built from the starting point forward. Record the Tutor version and Open edX release the site runs today, then read the Tutor documentation and the Open edX release notes for each major version between that starting point and the target Verawood release. For every step, note the Tutor version to install, the configuration keys added, renamed or removed, plugin versions that must match, and whether custom Docker images need a rebuild. Confirm the exact order against the official documentation for your own starting release. Do not reconstruct it from memory, from an old runbook or from a forum post, because those sources often skip a stop.

Each step ends only when a defined set of checks passes. Start with a verified backup taken immediately before the step, and confirm the Tutor upgrade command completes without errors. Then confirm that Studio and the LMS load, that a test course opens in Studio and previews for a learner, and that learner sign-in works through the configured identity provider. Check that background tasks and outgoing email run, that the database reports no pending migrations, and that custom XBlocks and themes render. Write the results in the runbook, along with the backup identifier, before starting the next major version. A failed check stops the sequence until it is resolved or rolled back.

Ask any partner to show the full step list for your starting release, the check set for each step, and the rollback method for each one. Confirm who signs off each checkpoint on your side, and who decides whether to roll back. Request a written estimate for the sequence, since the number of steps and the effort per step depend on your plugins, customizations and data volume, and no duration should be assumed until that estimate exists. Each step also needs a staging rehearsal and a backup retained until the final production checkpoint passes.

Rebuild the custom images after every upgrade step, and rebase each fork onto the upstream release for that step before testing anything else. Each Tutor version targets its own Open edX release, so an image built for one step can carry code or settings that the next release no longer accepts. After each step, regenerate the platform image with the Tutor version used for that step, then rebase the edx-platform fork onto the matching upstream release. Record the base commit, the Tutor version and the image digest for every rebuild. That record shows whether a failure came from your changes, from the new release or from the image build. Confirm the exact release tags and Tutor versions for each step in your upgrade plan before rebasing starts.

Move customizations out of the fork wherever Tutor allows it. Tutor's plugin and hooks system is licensed under Apache 2.0, so a plugin can add settings, environment variables, initialization jobs, extra images and patches without editing the platform source. Review each fork change and sort it into one of three groups: a change that a plugin hook can replace, a change that must stay in the fork because no hook covers it, or a change that upstream now provides and that can be dropped. Changes moved into plugins are easier to rebase because each plugin version can be pinned and tested on its own. Check the plugin documentation, or ask the plugin owner, to confirm which hooks each plugin uses in your Tutor version.

List every diff that must be ported before anyone starts porting. Generate the list from the difference between the fork's original base commit and its current head, and include Tutor plugin code, theme files, custom XBlock packages and any modified Dockerfile. For each entry, record the file or setting, the reason it exists, the owning team, the upgrade step where it was last tested, and whether it touches data models or migrations. Entries that touch migrations or stored data belong to the data migration work described elsewhere on this page, so cross-reference them instead of repeating those steps here. Review the list with each owning team, because a diff that looks cosmetic can still change behavior that users or reports depend on.

Check each rebuilt image before it moves to the test environment. Start the container, compare the installed Tutor plugin list with the list in your upgrade record, and confirm the plugin versions and enabled settings match what you expect. Then verify that the custom XBlocks and theme assets load in both the LMS and Studio, and that the build fails when a required plugin is missing. Run a smoke test with a single course and keep the results alongside the image digest. An image that starts with the wrong plugin set is harder to diagnose than one that fails the build, so make these checks a gate in the pipeline. Agree the check list and the tooling with your platform team before the first rebuild.

Test the upgraded site in layers, starting with automation. Run the test suites for every custom XBlock, Tutor plugin and theme against the target release, inside the rebuilt images, so that a removed import or changed base class fails in your pipeline before any learner sees it. Keep the results per component, because a failing XBlock often traces back to a dependency that needs a fork rebase before any code change in your own repository makes sense. Then confirm that the custom images start, that data migrations finish without errors in the logs, and that the LMS and Studio containers pass their health checks. These checks prove that the code loads. They do not prove that a course works end to end, which is why the next layers exist.

The second layer is a scripted set of smoke tests run by people, using named test accounts for a learner, a course team member, an instructor and a platform administrator. A learner enrolls in a published course, sees the course on the dashboard and receives the enrollment email. A course author opens Studio, edits a unit that contains a custom XBlock, publishes it and checks the outline. An instructor opens the redesigned instructor dashboard in the new release, checks enrollment counts and runs a data download. A certificate is previewed and generated for a test passing grade. Each configured identity provider, whether OAuth2, SAML, Shibboleth or LTI, is tested with a real sign-in. Confirm with your own environment which providers are enabled before the test window opens.

The data check runs against records that migrated, not just against the code. Choose a fixed set of sample courses and users before cutover, then record counts and sample values from the old site: course identifiers, enrollments per course, grades, forum threads and replies, library content, issued certificates and user accounts. Compare the same measures on the upgraded site and investigate every difference, including differences that look harmless. Ask the course team to review a sample of forum posts and library components, since they can spot content that loads but displays incorrectly. Keep the comparison as a signed record, because it is the evidence the rollback decision depends on.

Write the rollback decision rule before the cutover window, not during it. Name one decision owner, usually the service owner, and list who is consulted, such as the platform lead and the course operations lead. Set a go or no-go checkpoint and a cutoff time after which the team stops trying to fix forward. Define failure criteria in advance, for example a broken sign-in path, a failed enrollment, missing certificate records or a data count that does not reconcile. Rollback restores from the backup taken immediately before cutover, covering the LMS and Studio databases, the MongoDB store, object storage and the Tutor configuration. State whether learner activity recorded after cutover is kept, because restoring the old state discards it. Rehearse the restore on a copy of the environment first.

Keep the old release reproducible until the owner signs off the new one. Store the previous Tutor version, plugin versions, fork commit tags, image digests, environment files and lockfiles in version control, and rebuild nothing from moving branches. Leave the old environment stopped but intact, with its volumes and backups, and write down the exact commands needed to start it again. Agree in writing how long the old environment and backups are retained after sign-off, and confirm with your hosting team that storage for them is funded and monitored. A rollback that depends on an image nobody can rebuild is not a rollback plan, so test starting the old release once before the cutover.