Tomcat has a horrible gotcha around the seemingly simple task of deploying a web-app to the so called “root context”, ie at <hostname>/<webapp>.
Either
- Define a ROOT.xml context file in conf/Catalina/localhost
- Name your webapp WAR “ROOT.war” or containing folder “ROOT”
(Note: I mean, literally, it must be named “ROOT”. Case sensitive)
Note that advice given in Tomcat docs and elsewhere on setting the context in <webapp>/META-INF/context.xml can be misleading: you cannot deploy to root context simply by using this setting.
Cause
The path attribute, which configures deployment to root context, is ignored outside conf/server.xml. See the docs for path attribute, especially 2nd paragraph. I think this was introduced with Tomcat 5.5.
Why is this poor design?
Well, it seems to run misdirect the “Convention over Configuration” principle that has proven so powerful in recent years. While inferring the context from the filename is a convention, the principle states that configuration should be optional and when present override the convention. In Tomcat’s case, the configuration (ie a “path” attribute) is silently ignored when specified.
The impact is that you must change your War filename or deployment folder, with resultant impacts on build processes & tools, just to vary its deployment URL – a form of inappropriate coupling. Even though there is a setting defined that would allow the artefact name and deployent URL to be decoupled.
I dont know what they were thinking…
Update: Is Glassfish v2 a better alternative?
July to October 2008, I trialed using Glassfish v2 instead of Tomcat, to run 3 small-medium Java webapps. Glassfish was pretty good, but I am now going back to Tomcat, as it seems the better overall option.
While I found the Glassfish Admin user-interface very convenient, the app-server proved slow and memory hungry compared with Tomcat. I also had problems getting virtual hosting to work properly under Glassfish.
I think the situation could change with Glassfish 3, currently in beta, as it is much more modular and can run webapps in a much more lightweight configuration.
RSS Feed 
Justin said,
August 16, 2008 at 5:14 am
Your posting is very timely. I’m fighting with this right now. I don’t have any answers… just letting you know that you are not alone in your frustration!
Joe said,
August 26, 2008 at 1:43 am
It doesn’t appear to have changed in Tomcat 5.5. The only way I found to change the path for the root context is to put a line like this:
inside the element in my server.xml. Putting the same line in conf/Catalina/localhost/myapp.xml instead has no effect.
Joe said,
August 26, 2008 at 1:45 am
Hmm. Looks like the XML was stripped out of my post. I’ll try again. Put a line like this:
< Context path=”" debug=”0″ docBase=”myapp” >
inside the < Host > element in server.xml.
benhutchison said,
August 26, 2008 at 2:51 pm
Joe,
When I said:
1. Define a ROOT.xml context file in conf/Catalina/localhost
2. Name your webapp WAR “ROOT.war” or containing folder “ROOT”
I literally meant you must call the Xml/War file “ROOT”. myapp etc will not work. Also, note this behavior is by design and started with 5.5 (I think).
Anders said,
September 16, 2008 at 6:01 am
Spent a couple of hours on this now… Any ideas why this was changed from Tomcat 5? To me it worked like a charm in the old version but in 5.5 it is really frustrating.
Anders said,
September 16, 2008 at 6:16 am
Joe, thanks a lot for the solution in comment 3! Works for me now.
jon said,
June 16, 2009 at 4:32 pm
Another way is to create a file containing the single line:
(it doesn’t have to be a war file) and name it ROOT.xml.
Put that file in the directory
$CATALINA_HOME/conf/[enginename]/[hostname]/
That way you don’t have to modify the server.xml file and so it will work without a restart. The empty path is not needed, the name ROOT.xml is what does it.
jon said,
June 16, 2009 at 4:34 pm
Grrr, wordpress ate my file contents.
The file ROOT.xml should contain the line
( Context docBase=”/my-path/applicationName.war ” /)
Where ( is less than and ) is greater than.