Deploying to WebSphere should not feel like a rite of passage. It is just a server with knobs. The trick is knowing which ones to turn before the pager goes off. If you are shipping on WebSphere Application Server, base or ND, this is a field guide from the trenches. It is written with the mood of this week where Oracle is courting BEA and every hallway conversation ends in a server comparison. Keep reading. You can win on WebSphere without losing your weekend.
Problem framing
The most common pain I see is not code. It is deployment friction. WebSphere has many places to click and more places to forget to click. You install an app and get a clean green status, then the browser says 404 and the log whispers nothing helpful. Or the app works on one node and not the other. Or it works until load hits and class conflicts wake up.
When you strip it down, most failed pushes fall into three buckets. Wrong mappings and virtual host. Wrong resources like JDBC or JMS. Wrong classloader setup. Fix those and life gets better. The rest is repeatable buttons.
Three case walkthrough
Case one, first push of a simple WAR to a single server
This is the common starting point. One WAR, WebSphere base, one box. You do not need wizardry, just a checklist.
– In the admin console pick Applications, Install new application. Choose Fast Path for the panels. Set the context root you want. Keep it simple, like slash app.
– Map modules to servers. Pick your app server, not the node or the cell. Then map modules to a virtual host. Most shops use default_host. If your URL is fronted by IBM HTTP Server with a plugin, make sure the host and port in the plugin match the alias on the virtual host. A 404 with SRVE messages often means this mapping is off.
– Save, then click Synchronize if you see the yellow triangle. Start the app.
Gotchas in this case live in two places. First, session config. If you changed cookie names or paths in your app, match them in WebSphere or leave defaults. Second, classloader order. If your WAR brings its own logging jar or XML parser and it fights the one under WebSphere, set the application classloader to parent last on the application. That setting lives under the app, class loading and update detection. It saves hours of mystery errors.
Test with a direct port to skip the web server while you sort it out. Then flip back to the plugin once happy.
Case two, a full EAR to ND with cluster, JDBC and JMS
Now we are in WebSphere ND land with a Deployment Manager, a cluster, and an EAR that has EJBs and a web module. The path is similar but there are more wires to connect.
– Before you install the app, create your JDBC provider at the right scope. Server scope if you are testing. Cluster scope if the app runs on the cluster. Add the datasource, set the JNDI name, add a JAAS J2C auth alias if the database needs a user. Test connection from the console.
– For messaging, decide if you are on SIBus or old school MQ. On 6 dot 1, activation specs are the preferred route for MDBs, though many teams still use listener ports. Pick one, not both. Create connection factories and destinations with clear JNDI names.
– Install the EAR to the cluster, not to individual servers. Map modules to the cluster members. Map resource references. This is the step many skip. Under References, map your app refs like jdbc or jms to the actual JNDI resources you created. If you forget this, the app starts and throws NameNotFound when it first touches a queue or a pool.
– Map security roles to users or groups that exist in your realm. If global security is on with LTPA, make sure your admin understands the user registry backing it. File based users are fine in dev. LDAP in prod needs a test group ahead of time.
– Set session replication for the web module if you need to survive a node bounce. Memory to memory works well for small sessions. For big state, use database persistence and keep the objects serializable. Then review HTTP plugin routing so both nodes receive traffic.
A quick word on Java levels. Plenty of teams are on IBM JDK 5 right now and WebSphere 6 dot 1 speaks J2EE 1 dot 4, not full Java EE 5. Keep the app compiled for that target and avoid code that expects newer annotations to be present in the container.
Case three, a near zero downtime update without breaking sessions
Prod patch time. You have a small change and a busy site. The goal is a rolling update and happy sessions.
– Turn on session replication if it is not already on. Keep your session small so replication does not choke under load.
– Take one cluster member out of the IBM HTTP Server plugin by lowering its weight or stopping it in the plugin routing table, then stop the app instance on that member. Update the app on that server. Start the app, verify health, then restore traffic to it.
– Repeat for the next member. If you have three or more members, you can always keep the majority up.
WebSphere ND also has application edition features that help with staged rollout. If your team prefers clicks, the simple traffic drain step above is enough. If you prefer scripts with wsadmin in Jython, capture these steps once and reuse every release.
Watch logs for messages about session affinity and replication. If the plugin routes a user to the other node and their cart goes empty, you missed a step in session persistence or used a non serializable object in session.
Objections and replies
WebSphere has too many screens compared to Tomcat. True, the console is not small. The upside is central control for clusters, security, and resources. Once you have a script for install and a script for rollback, deploys feel just as quick. Save one known good cell config and you can stamp a fresh environment in minutes instead of clicking for hours.
Scripting with wsadmin is scary. Pick Jython and keep a tiny library of helpers. Start with install app, map modules, map refs, start app, stop app, and list versions. Test those against a dev cell. Put the scripts in source control next to the build. Next week they will be boring, which is the goal.
Classpath fights are constant. Most of them are self inflicted. Do not ship your own XML parser inside the app unless you must. If you must, set parent last at the module or app level and be explicit. Use shared libraries for jars you want across modules. Keep sun dot star calls out of your code. And match the IBM JDK level in local dev to what runs in prod to avoid surprises.
JMS never starts on both nodes. On newer stacks prefer activation specs to listener ports and keep all JMS config at the cluster scope. If you use listener ports, ensure the MDB activation properties match the listener name and that only one of the two systems is active at a time for a given destination unless it is designed for that pattern.
Action oriented close
Print this and keep it near your console. It turns fire drills into routine work.
- Map modules and virtual hosts. If you see 404, check the mapping and the plugin first.
- Create resources before install. JDBC provider, datasource, J2C alias, JMS connection factories and destinations, all at the right scope.
- Map references. Under References, wire the app refs to the actual JNDI names.
- Set classloader order. Use parent last when your app must override container jars.
- Turn on session replication if you need resilience, and keep session light.
- Script installs with wsadmin in Jython. One script for install, one for update, one for rollback.
- Sync nodes after any change in ND. Do not trust green status until you see synchronized across the cell.
- Test direct against the app server port, then behind the web server plugin.
Monday morning plan. Build a tiny WAR that prints its version. Deploy it to dev with your chosen steps. Flip classloader to parent last and back and watch what changes. Add a datasource and map a reference to it. Then remove it and confirm the app fails in the way you expect. Repeat the whole thing on a cluster with rolling update. Capture each step in a script. By the end of the day, your team will have a repeatable path and a safety net.
WebSphere will not get simpler by wishing. But with the right defaults, a few bolded settings, and muscle memory on the console, it becomes a steady platform. Ship often. Script the boring parts. And keep your classloader honest.