A Gotcha: Adobe ColdFusion 10, Apache Tomcat, J2EE Sessions

I’ve spent a bit of time over the past month or so playing with setting up a couple of my development systems to run both Railo and Adobe ColdFusion 10 concurrently on a stock install of Apache Tomcat 7. In the case of ACF10, my interest in running on stock Tomcat is based on a desire get away from the custom-built and now out-dated version of Tomcat which Adobe (unwisely, in my opinion) bundles with ACF10. This past week I bumped into a bit of a gotcha that took me quite a bit of time to track down and solve. In the hopes of helping others avoid this same problem and so that I don’t forget it, I’ll share what I ran into and how to solve it.

The symptoms I was seeing were that as soon as I enabled J2EE sessions in the CF administrator and then subsequently stopped Tomcat for any reason, Tomcat would no longer start cleanly, it was no longer bringing up the context running ACF, and because it was not starting cleanly it would also not shutdown cleanly. As weird as this seemed (and sounds, I realize), this was very repeatable. I had it down to something I could reproduce in under 5 minutes: set up a clean new Tomcat install, deploy ACF10 on it via a WAR file, sign into the CF admin, enable J2EE sessions, stop Tomcat… and it would no longer start. There was nothing in the ${CATALINA_BASE}/logs/catalina.out log file indicating what was wrong; it just looked like Tomcat would hang as it was starting. I determined I could install, deploy, and then start/stop Tomcat successfully as many times as I wanted and the problem would not show up until and unless I enabled J2EE sessions in the CF admin. It did not seem to be dependent on whether ACF10 was patched or the specific version of Tomcat.

At one point, I even dug around and figured out how to change the log level used by Catalina, in the hopes that a bit more detail might shed some light on the problem but the bump of one additional level of detail took the log entries on starting Tomcat from under 40 to over 15,000… and while the nature of the problem — in retrospect, of course — might well have been touched on in that blizzard of log entries, I couldn’t find anything even remotely resembling a needle in that sea of haystacks.

It seemed like something specifically related to turning on J2EE sessions in ACF10 was breaking Tomcat. Based on a suggestion from a co-worker, I removed write permissions for the user under which Tomcat was running from all folders under ${CATALINA_BASE} except the ./logs/ and ./webapps/ folders, in an attempt to see if I could determine where the breakage was occurring. On starting Tomcat, I noticed a complaint in the ${CATALINA_BASE}/logs/catalina.out log file about not being able to write to folder ${CATALINA_BASE}/work/Catalina/localhost/_. Looking in that folder, I found a file named SESSIONS.ser. Doing a bit of Googling, I came across a short blog post dealing with session persistence across Tomcat restarts.

I’m not going to pretend that I know why Tomcat would have session persistence enabled across restarts, or why I might want to persist sessions across restarts (I really can’t come up with a scenario where I would want that), or why enabling J2EE sessions in ACF10 would seem to break this persistence… but clearly it does. That file gets written on stopping Tomcat and is then read and removed when Tomcat next starts/restarts. To disable this persistence, the context(s) within Tomcat on which ACF10 is enabled need to include a Tomcat session manager component specifically configured to disable this persistence:

...
<Manager pathname="" />
...

This is touched upon in the Apache Tomcat docs here. That session manager component can occur in any of the supported locations where contexts are configured in Tomcat. Once I confirmed this to solve the problem, I took a quick peek at the context configuration for ACF10 when it is running against the Adobe-provided custom build of Tomcat 7.0.23, and — sure enough — it disables session persistence in precisely this same manner.

The one upside to all of the time I spent tracking this down is that I can now install Tomcat and deploy ACF on it in a matter of just a few minutes in a variety of ways, including multiple virtual hosts under a single Tomcat, multiple Tomcat installs running on different ports, and  a single Tomcat install with multiple instances via use of ${CATALINA_HOME} and ${CATALINA_BASE}. I’m kicking myself for not looking at deploying ACF on stock Tomcat three years ago when I learned of Adobe’s choice with ACF10 to use a non-stock Tomcat that they inexplicably have not updated.