Migrating and Upgrading an Open edX® Instance Nine Versions at Once

Our approach combined early discovery, parallel technical workstreams, and the migration of a staging environment to reduce risk during the production migration. This strategy allowed us to meet our fixed deadline.

OpenCraft immediately began interviewing the Penn State Extension team to understand the customized functionality they were using. We identified the custom API endpoints and data models that integrated with their e-commerce system and walked through the custom registration process end to end. This enabled us to map which features of the custom extensions were actually in use and how they fit together.

Complicating the upgrade was the age of their existing version, which was approximately five years old. During that time, deployment methods had evolved significantly, shifting from virtual machines to container-based solutions such as Docker and Kubernetes. In addition, the database schema had changed substantially between versions.

All of our clients are assigned a dedicated team member who serves as their primary point of contact and sees the project through from start to finish. This role is known as the “Client Owner.” In this case, the Client Owner was Fox, a team member who has been contributing to the Open edX project since 2013.

Fox outlined a plan to address all of these challenges within the deadline by completing several workstreams in parallel. While one team member focused on the database, another handled forward-porting the customizations, and a third rewrote the configuration for the new system.

We created a new staging environment that integrates with the staging copy of the client’s e-commerce platform. Team member Arunmozhi was tasked with scripting the data migration work.

There is no official method to jump forward across as many platform versions as required. For more recent versions of the platform, performing upgrades using the official deployment tool, Tutor, works very well. However, for older versions that predate Tutor, or are old enough that the required Tutor-based tools no longer run, an alternative approach is required.

Arun leveraged Atlas, a database migration planning tool, which allowed him to directly compare the client’s customized Open edX database with a standard, modern installation of the platform. Using this approach, along with custom scripting to reconcile non-schema changes between versions, he was able to demonstrate that a migration would work using a copy of the staging databases.

Samuel, another team member, dug into the installation and determined which custom extensions were still used by Penn State. He then set to work porting these extensions to the latest version. This involved upgrading the version of Python in use and switching the extensions to modern APIs. To ensure the software continued to function correctly, he drafted comprehensive test plans that could be used to verify functionality in future updates.

Meanwhile, a colleague, Pooja, examined the old system configuration to manage the custom-routed requests to Penn State Extension’s e-commerce platform. She ensured that user profiles and logins continued to work as they had previously, despite the transition to an entirely new redirection system.

After developing solutions for all identified issues, we migrated the staging environment to the new installation. This allowed us to test the entire migration process end to end and identify any remaining gaps. After another couple of weeks spent addressing these issues, we migrated the production instance, applying everything we had learned.

The instance was quite large, with an extensive historical dataset. The day-of migration required approximately 12 hours of dedicated work, followed by several days of rapid efforts to resolve any lingering issues.

Planning an upgrade from an older version of the Open edX platform? Contact us to discuss your migration and how we can help reduce risk, minimize downtime, and ensure a smooth transition.

“I can’t thank you enough for a successful migration this week. By measure of the incoming cases from our customer service team, this was by far our most successful major platform upgrade to date. Your attention to detail and responsiveness were key, and I appreciate everything [OpenCraft] did to set us up for success.”