websphere-and-liberty

WebSphere and iberty Knowledge Base

This knowledge base provides a collection of links to information about how to migrate a WebSphere Application Server application to run on Liberty.

The knowledge base is managed and curated by Laura Cowen, Technical Content Strategist and Developer Advocate at IBM. Contributions and feedback are welcome from WebSphere users and subject matter experts.

For more info about the knowledge base aims and how to contribute, see the README.

To search for information, use your browser’s search in page feature (CTRL+F).

If there is something missing, or you have information that would answer a question on the knowledge base, please raise an issue.

Liberty overview

Why Liberty

Liberty architecture

Liberty operations

Deployment options:

Liberty application frameworks

Differences between Liberty and WebSphere

(LC: Ultimately, I think this would be more useful to be framed in terms of goals, as “I do it this way on WebSphere; how should I do it on Liberty?”, rather than highlighting the differences.)

Architectural differences

Operational differences

Application framework differences

(Provide links out to detailed instructions in later sections.)

Getting to know Liberty

While tWAS applications are largely compatible with running on Liberty, Liberty is not identical to tWAS. Before you start to migrate a tWAS application to run on Liberty, it is worth becoming familiar with writing and running apps on Liberty. WebSphere Liberty is built on Open Liberty; apart from a small number of additional capabilities in WebSphere Liberty, the WebSphere Liberty and Open Liberty runtimes are the same.

See Other resources for more help.

Planning a migration

Tools to help you migrate to Liberty

How to migrate to Liberty

How to migrate operations to Liberty

Topic Resources available (description, link, and type) Sources of info to create missing resources
Operations: Moving from Admin Console to Liberty admin center, MoRE, etc. (issue) Demystifying Liberty for WebSphere administrators: Myth #3 (article with embedded videos); Liberty Admin Center; WebSphere admin console; wsadmin scripting;
Operations: How to secure the server configuration on Liberty Security Configuration Hardening docs (docs)  
Operations: How to do centralised management in Liberty Demystifying Liberty for WebSphere administrators: Myth #2 (article with embedded videos)  
Operations: How to load-balance across Liberty servers Demystifying Liberty for WebSphere administrators: Myth #5 (article with embedded videos)  
Operations: How to manage plugin config of dynamic routing in Liberty Demystifying Liberty for WebSphere administrators: Myth #5 (article with embedded videos)  
Operations: Licences and entitlement to run Liberty Demystifying Liberty for WebSphere administrators: Myth #8 (article with embedded videos)  
Operations: Messaging engine compatibility between tWAS and Liberty    
Operations: How to script deployments on Liberty Demystifying Liberty for WebSphere administrators: Myth #4 (article with embedded videos)  
Operations: How to do HTTP session persistence on Liberty Demystifying Liberty for WebSphere administrators: Myth #6 (article with embedded videos)  
Operations: How to tune Liberty performance Threadpool tuning Liberty; Performance tuning Liberty; Faster responses with HTTP response compression on Liberty; Pre-populating database connections for better response times in the cloud; Common performance tuning; Some known migration issues mostly around performance(mostly tWAS to tWAS but some Java and Linux related points that would apply to going to Liberty on a newer Java);  
Operations: Liberty on z/OS Consider enabling SMF 120 records: HTTP requests may be monitored with SMF 120 subtype 11 records. These records are enabled by adding the zosRequestLogging-1.0 feature to the server configuration and enabling SMF to capture those records. Java batch jobs may be monitored with SMF 120 subtype 12 records. These records are enabled by adding the batchSMFLogging-1.0 feature to the server configuration and enabling SMF to capture those records. Consider WLM classification: zosWlm-1.0  
Enable hardware cryptography Java 8, Java 11, Java 17, or Java 21  
Operations: How to run older programming models on Liberty (issue)  
Operations: How to do high availability (HA) on Liberty Demystifying Liberty for WebSphere administrators: Myth #6 (article with embedded videos)  
Operations: How to move to Liberty without going to the cloud (issue)  
Operations: Can I use Liberty in exactly the same way as tWAS? (issue)  
Technical: Scaling, administration, clusters Demystifying Liberty for WebSphere administrators (article with embedded videos)  
How to optimize routing setup for HTTP routing (eg F5, NGINX, Apache mod_rewrite)? (issue)  
How to design continuous integration builds with Liberty’s Maven plugin? (issue)  
Issues to look out for, differences between WebSphere and Liberty and how to handle them (create post from Monica and Barbara’s presentation, issue)  
Managing Deployment Scripts without WAS ND Demystifying Liberty for WebSphere administrators: Myth #4 (article with embedded videos); Deployment best practices? (issue)  
Issues to look out for, differences between WebSphere and Liberty and how to handle them - Deploying Liberty on VM’s (Collectives or HTTP Proxy) Kevin’s lab (internal)  
Issues to look out for, differences between WebSphere and Liberty and how to handle them - How to configure Hardware Security Module (HSM) on z/OS on IBM Java on Liberty (issue)  
Hands-on demos/labs Tech Zone demos, VMs, presentations; Liberty to VMs; Liberty to OCP (internal, issue)  
How to migrate clusters, in particular session management and failover logic? (issue)  
How to update deployment pipelines for Liberty? (issue)  

How to migrate applications to run on Liberty

Tips: sequence and “how” for known cases What to do when, suggested sequence of steps

Topic Resources available (description, link, and type)
Issues to look out for, differences between WebSphere and Liberty and how to handle them - Transaction management [add resources here]
Transaction propagation between remote EJBs Transaction propagation on Liberty (article)
How to do EJB lookups Binding remote EJB names with Liberty (forum); Liberty Support for Custom JNDI Names for Enterprise Beans (OL blog; also available on the Red Hat Developer blog)
How to migrate hardcoded InitialContext or java:global lookups? See InitialContext and java:global lookups (issue)
How to migrate SOAP endpoints using JAX-RPC? Automating JAX-RPC source code migration (video)
How to migrate authentication using DatabaseServerLoginModule? (issue)
How to validate migrated Filenet connections? (issue)
How to migrate WebSphere SIBus JMS messaging? (issue)
How to migrate hardcoded InitialContext or java:global lookups? See InitialContext and java:global lookups (issue)
How to migrate legacy Spring and Hibernate frameworks that don’t support Java 17? Are there common pitfalls? (issue)
What are the differences in classloader locations between tWAS and Liberty? Rules for migrating WebSphere traditional application class loading configuration to Liberty (IBM Support) (covers classloader hierarchies for tWAS and Liberty, migration rules for classloading, classloading libraries, classloading config); Class loader configuration (OL docs)
What are the differences in WAR structure between tWAS and Liberty? (issue)
Does it matter if some apps use javax and others use jakarta? Is it necessary to migrate fully to Jakarta 10? (issue)
How to validate integrations after migration? (issue)
How to manage third-party dependencies (JARs) in Liberty? (issue)
How to transition existing dashboards and alerts from WebSphere and other inputs to Liberty’s JSON logging, MicroProfile Metrics, and OpenTelemetry? (issue)
How to migrate certificates from WebSphere to Liberty’s TLS setups for keyStore and SSL? (issue)
How to transition WARs/EARs to Liberty? (issue)
How to configure AD, LDAP, SPNEGO, SAML, OIDC on Liberty? (issue)
Any compatibility issues to watch for moving from Java 8 (Oracle or IBM) to Java 17 (OpenJDK distributions)? (issue)
How to automate JAX-RPC source code migration 20250109 CAB session - Automating JAX-RPC source code migration (video)
How to run Spring Boot apps on Liberty How to Containerize Your Spring Boot Application for Rapid Startup (DZone.com); Running a Spring Boot 3.x application WAR file on Liberty; all Spring Boot blog posts on openliberty.io; missing: “a complete demo/guide that connects our three flagship enterprise products (WebSphere, DB2, MQ) with a spring boot application using Liberty InstantOn to scale to zero on OpenShift and then also show how Semeru cloud compiler can be enabled with Liberty operators to reduce rampup time even more efficiently.”; Spring Boot performance (internal; issue)
Support for legacy versions of Spring and Struts Open Source Library Support announcement

Client case studies

(these should be organised/presented according to what they demo and/or by industry, etc so they’re easily retrieved)

Training

Other resources

| Topic | Resources available (description, link, and type)| | — | — | | OSS libraries |[add resources here] | | Documentation | Liberty docs (apply to Open Liberty and WebSphere Liberty; WebSphere Liberty docs (for features only available in WebSphere Liberty) | | What’s new in Liberty? | Open Liberty release blog posts; Quarterly webinars; Open Liberty LinkedIn page | | Online forums | WebSphere & Liberty TechXchange community; WebSphere & Liberty Customer Advisory Board (CAB) TechXchange community | | Videos | Laura’s backups of ExpertTV etc (internal); Grace’s video audit (internal) Videos cover topics listed on this whole page but all videos probably need updating. |

Suggested article/video ideas

Source formats

Each link is labelled to indicate its format:

This site is open source. Improve this page.