Canvas LMS is a widely used open-source learning management system trusted by institutions for delivering courses, assignments, and digital learning experiences. As the platform evolves specially with new AI features rolling out—keeping your self-hosted instance up to date is essential for performance, security, and long-term stability. In this blog, we break down a recent Canvas LMS code modernization project, highlighting the challenges we faced, what the client needed, how we approached the upgrade, and the results we achieved.

1. The Challenge

Upgrading a very old self-hosted Canvas LMS (more than 2 years old) to the latest current version is far more complex than just running a quick git pull. Major version jumps can introduce several issues that must be handled carefully.

Key Problems With Direct Upgrades

• Merge conflicts: New updates can clash with custom patches and modifications.

• Migration failures: Database migrations may break, skip steps, or cause issues with course or user data.

• Dependency mismatches: Updated gems or libraries may not align with the existing environment.

• Feature incompatibility: Custom themes or plugins can stop working after the upgrade.

• Slow debugging: Fixing conflicts and broken migrations can take hours or even days.

Because the client had an active user base, any downtime or data issues would have caused significant disruption.

2. Client Requirements

The client needed more than just an upgrade—they needed a smooth, uninterrupted transition.

Their priorities were:

• Minimal downtime: Users should continue accessing courses without interruptions.

• No data loss: All assignments, grades, content, and user accounts must remain intact.

• Seamless integration: The upgrade must support existing customizations and plugins.

• Future readiness: The updated system should be easier to maintain and flexible enough to support new features, including upcoming AI tools.

These requirements meant the upgrade had to be planned with precision.

3. Our Modernization Strategy

Before touching the client’s environment, we reviewed the official Canvas LMS upgrade documentation to understand version changes, new dependencies, and migration paths.

Our Staged Approach to a Zero-Downtime Upgrade

1. Matched the client’s existing setup

We installed the same 2023 Canvas LMS version on a staging server to replicate their environment accurately.

2. Performed database-only migrations

Using rails db:migrate, we incrementally ran migrations from 2023 up through the 2025 release. This allowed the database to update safely without touching the production code.

3. Switched to the 2025 codebase

Once the database reached the 2025 migration level, we:

• Removed the old 2023 code

• Installed the fresh 2025 Canvas LMS code

• Connected it to the newly migrated database

This ensured both the codebase and database were perfectly aligned.

The Results

This method provided several advantages:

• Zero downtime for end users

• No data loss—all course data and user information remained intact

• A smooth, conflict-free transition to the latest Canvas version

• A future-ready platform capable of supporting new features and AI tools

Final Thoughts

Upgrading a self-hosted Canvas LMS is not a simple task—it requires strategic planning and a careful, staged process to avoid downtime or data issues. By matching the client’s existing version, migrating the database step-by-step, and then attaching the latest codebase, we delivered a safe and seamless modernization.

The final result: a faster, more reliable, and fully future-ready Canvas LMS that’s prepared to support upcoming AI-powered features and long-term growth.