TL;DR

In this post, I describe tackling a complex triple migration of a large legacy system: upgrading outdated Spring versions, replacing WebSphere with Tomcat, and moving from on-premises servers to a private cloud solution. Despite technical obstacles around transaction management and knowledge gaps, we successfully migrated the million-line codebase while active development continued. The key lessons for tackling these legacy migrations: invest heavily in testing, approach migration incrementally, and don’t underestimate the human aspects of change management.

The Migration Challenge

In my career, I’ve faced many challenging migrations, but one project stands out for its complexity. We needed to execute three simultaneous migrations on a mission-critical system with approximately one million lines of code:

1. Upgrading from legacy Spring versions to modern ones
2. Moving from WebSphere to Tomcat
3. Migrating from on-premises managed servers to a private cloud solution

This was actually my second time tackling such a multi-faceted migration, but with significantly higher stakes—a much larger codebase undergoing active development to meet new legislative requirements.

Why Three Migrations at Once?

1. Hardware end-of-life: The existing hardware had reached EOL status with no spare parts available.
2. Cost efficiency: WebSphere licensing and support costs were substantial, while we primarily only utilized its transaction manager.
3. Technical debt: The outdated Spring versions were becoming a security liability.
4. Cloud flexibility: We needed the ability to scale resources up and down based on usage patterns.

Key Challenges

Knowledge Gaps and Testing Issues

Over the years, key developers had left the organization, taking with them their critical knowledge of specific system components. Our extensive automated test suite also presented challenges—nobody fully understood what scenarios many tests were actually verifying, and several tests were tightly coupled to WebSphere-specific infrastructure.

Transaction Management Complexity

The most technical challenge involved replacing WebSphere’s transaction manager. We chose Atomikos but encountered issues with transaction propagation. Especially the @Transactional(propagation = Propagation.REQUIRES_NEW) was not handled correctly. Somewhere in the whole Atomikos/Spring batch/Hibernate world this part was not working anymore. We eventually encapsulated problematic operations in stored procedures to maintain data integrity.

Balancing Migration with Active Development

Unlike my previous migration experience, this system was undergoing active development to meet new legislative requirements, requiring careful coordination with multiple development teams.

The Migration Approach

We developed a three-phase approach:

1. Clean Migration Path: Creating parallel build configurations with feature toggles
2. Transaction Management Overhaul: Mapping transaction patterns and extending Spring’s capabilities
3. Cloud Migration: Containerizing the application and enhancing monitoring

The Human Element

Looking back, I made a critical mistake by focusing too much on technical challenges and not enough on stakeholder management. While I did communicate with stakeholders, it wasn’t always at the right moments or delivered effectively.

This lesson was driven home just before our go-live date when we discovered critical issues during final testing. Despite the pressure to maintain the timeline, we recommended delaying the release.

In the end, the delay meeting wasn’t as difficult as I’d feared. The business stakeholders were clear: pushing forward and encountering major issues in production would have created far worse chaos than a planned delay.

Lessons Learned

1. Test, Test, Test: Invest heavily in comprehensive testing early.
2. Incremental Migration Wins: Break changes into small, reversible steps.
3. Balance Technical and Organizational Focus: Technical brilliance alone doesn’t guarantee success.
4. Don’t Catastrophize Difficult Decisions: Most organizations prefer a delayed success to an on-time failure.

Results

Despite the challenges, the legacy migration delivered significant benefits: reduced infrastructure costs, streamlined deployment, enhanced security, better monitoring, and simplified onboarding—all while maintaining system stability throughout the transition.

The key to our success was acknowledging the complexity upfront and investing in fundamentals—particularly testing and documentation—before diving into the technical migration. Finding the courage to delay when things weren’t right ultimately protected both the system’s integrity and our team’s credibility.