How to Configure Tomcat root context

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

  1. Define a ROOT.xml context file in conf/Catalina/localhost
  2. 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.

About these ads

58 Comments

  1. 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!

  2. 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.

  3. 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.

  4. 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).

  5. 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.

  6. Anders said,

    September 16, 2008 at 6:16 am

    Joe, thanks a lot for the solution in comment 3! Works for me now.

  7. 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.

  8. 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.

  9. Paul Rivers said,

    December 1, 2009 at 5:27 pm

    Hi,

    I just wanted to say that this post (and comment #3) was really, really helpful for me. I kept struggling with the “recommendation” to not put the context tag in server.xml, but I couldn’t get it to work – this cleared it up for me that it wasn’t possible.

    Since I just run my own local server, and never change the context element once I get it set up, there’s no reason for me to not put it in server.xml (putting it in a separate file outside the webapp just make it more difficult to get running when I move it to a newer machine).

    Thanks! :-)

  10. Andrei Prodan said,

    February 26, 2010 at 8:23 am

    I’ve also found that it’s imperative to remove/rename the default webapps/ROOT if it exists, or Tomcat 5.5 will silently ignore the configured mount and mount it’s own ROOT application.

  11. George said,

    February 27, 2010 at 9:47 am

    Very helpful posting and comments. thanks.

  12. Matt B said,

    March 3, 2010 at 6:15 am

    Comment #7/8 will result in the web application being run directly from the .war file instead of having the .war file expanded to the filesystem. I’m not sure what the performance implications are of this, if any, but it is worth noting.

  13. redsonic said,

    April 11, 2010 at 7:08 pm

    Hi,

    It’s a BAD to run directly from the war file (not expanded).

    I have made a configuration as JOE said (see post3) and it works good. The problem is that when I upload a new version of myApp.war to tomcat webapps , then stop start, I can no more hit my application with http://www.mysite.com but instead I hit tomcat manager application.

    A seconde stop/start of tomcat6 resolve the problem. Anyone have this problem ?

  14. redsonic said,

    April 11, 2010 at 7:11 pm

    sorry for my so bad english, this is because of my frustration about tomcat ^^

  15. redsonic said,

    April 11, 2010 at 7:13 pm

    and I have created a thread here :

    http://www.coderanch.com/t/490708/Tomcat/stop-start-twice-have-my#2208385

  16. vero said,

    April 29, 2010 at 5:14 pm

    Hola a todos tengo un severo problema trabajo con un servidor linux y precisamente hoy comenzo con errores e impedia el acceso a algunos servicios pero gradualmente comenzo a cambiar su configuracion hasta impedir el acceso a todo!! los puertos estan cerrados, el proveedor da por solucion solo el formatear, e insiste en que la configuracion fue hecha porel administrador pero no es verdad ahora cuando quiero entrar al servidor me dice que no se reconoce el usuario ni siquieraa root alguien me puede ayudar a revivir el servidor?

    Les agradeceria su pronta respuesta!!

    Gracias!!!

  17. Zeeshan Khan said,

    September 1, 2010 at 9:02 pm

    Thanks for the solution

  18. anton said,

    February 15, 2011 at 4:57 am

    I am happy to hear, that somebody else also does not know, why the they wanted to implement this in this way – everybody suggest different complicated solutions, but nobody says if there is a single reason not to allow to solve this in a simpler way. I have already spent about 3 day fighting with this sh*t – the whole inet is full of pain of people who have been struggling with one and the same problem for years.

    Still, it seems that the perfect solution for this problem does not exist.

    1. I do not want to rename my application to ROOT. It could be ok, if that was only one row in maven build script, which would rename only output war file. But this is not the case – I will have to change the project name from something self-explaining and following my project naming conventions to ugly ROOT. Even this could be ok, but I even will not be able to work with multiple ROOT projects in same netbeans instance.

    2. The suggested solution with ROOT.xml though works, also gives a bad feeling of being a crutch and solving a task with a mechanism which is not intended to be used to solve this task. Even worse – except the bad feeling, it also brings a physical limitation – it is not recommended for docBase attribute to point to the dir inside webapps directory, so I am losing autodeployment functionality without having any good reasons for that. And also having 2 different folders for webapps in the same tomcat installation is also just ugly way of doing things.

  19. anton said,

    February 15, 2011 at 7:23 am

    Ok, after all I have found my peace with this issue, also some points in the message above are not correct.

    First, using ROOT.war is ok. While I was fighting with this problem trying to avoid using ROOT.war, I had 2 main reasons in my mind:
    1. I did not want to rename my project and any source or build files in IDE (netbeans).
    2. I did want to see tomcat being flexible enough to have multiple roots for different hosts inside single tomcat installation without having to point webappname postfix in url – access webapps just by server1.com, server2.com, sub.server2.com etc, not server1.com/app1, server2.com/app2, sub.server2.com/app3.
    3. Follow tomcat application deployment basic guidelines and use any of its standard features for all cases – at least using autodeployment feature for war files was important for me.

    So, I have been trying to find a solution which would fit to all 3 requirements, but one wrong concept in my mind did not allow me to see it. That wrong concept was that all web application should be deployed in single tomcat/webapps directory.

    So, I was wrong (see details here: http://tomcat.apache.org/tomcat-6.0-doc/virtual-hosting-howto.html) – tomcat can and should have multiple deployment directories with multiple webapps inside. Each deployment directory would be attached to single virtual host and would have all features which default webapps dir had. So, once I stopped thinking of “webapps” as of global web application storage which might be shared between server1.com and server2.com, everything stepped on their places and I don’t want to rename ROOT webapplication folder anymore.

    So, answers for 3 reasons listed above:
    >1. Do not want to rename project in IDE.
    Not sure if that is possible with eclipse/netbeans non-maven project, but with maven pom.xml (which have very nice integration to netbeans gui), this is not needed:


    ROOT

    Just change finalName tag value to ROOT – this would allow to produce deployable ROOT.war file with webapplication contents, no need to change artifactId, project display name or project folder name – only output war file is affected.

    >2. Handle multiple roots for different hosts – the link is provided above, with Virtual Hosts used property things would look like the following:

    tomcat/server1/ROOT – would contain default webapp for server1.com
    tomcat/server1/another-app1 – would contain secondary webapp which would be available only from server1.com

    tomcat/server2/ROOT – would contain default webapp for server2.com
    tomcat/server2/another-app2 – would contain secondary webapp which would be available only from server2.com

    tomcat/sub.server2/ROOT – would contain default webapp for sub.server2.com
    tomcat/sub.server2/another-app3 – would contain secondary webapp which would be available only from sub.server3.com

    etc. server1.com, server2.com and sub.server2.com should not try to share any webapplications – with the above directory organization, micromanagement inside webapps directory is just not needed.

    > 3. Follow tomcat application deployment basic guidelines… autodeploy war files etc.

    With above config, each dir for each virtual host:
    tomcat/server1
    tomcat/server2
    tomcat/sub.server2

    should behave exactly in the same way as “webapps” directory behaves (actually, I did not test it, but I’m sure this is true).

    So, now I feel comfortable with my own ROOT.war, with tomcat and with the way it currently behaves, though I hated it few hours ago. Hope this clarifications would help to someone, who will try to deploy his webapp as ROOT, but will not want to rename his project.

  20. chriso said,

    April 29, 2011 at 7:34 am

    What a great thread. Comment #10 is also VERY important. That was biting me. I just renamed my ROOT webapp to “REALROOT”.

  21. Keith said,

    February 16, 2012 at 12:58 pm

    Great thread Ben, thanks. I’ve been googling for ages. Much appreciated.
    So the short answer is that if you delete the existing ‘webapps/ROOT’ directory, and then make a new directory in ‘webapps’ with the exact name ‘ROOT’, and insert a very basic index.html file (or an index.jsp file) then browsing to localhost:8080 or whatever your domain name and port is, tomcat will serve up that index.html file.

    It’s so frustrating that it’s undocumented. That should be one of the first things on the tomcat getting started page. It’s such a basic need to get tomcat to serve pages to the main domain page. I was thinking that the URL associations had to be done using annotations in servlets, but since I was using JSP pages I was googling for how to insert annotations in jsp pages to get it to work…
    Another reason why it was hard to find this page is that most people don’t use tomcat to serve web content to the main domain page, they use the apache http server and link it to tomcat. But most of the people here, including myself, are using tomcat with no apache http server by the sounds of it.
    Thanks for your article, saved me hours.
    Keith

  22. April 19, 2012 at 9:41 pm

    IMPORTANT: This wordpress article with comments contains every information you need to know to change your default ROOT application to your own, without having to change your projectname. So read carefully all the previous comments and the article itself! Even if option 1. from the article itself does not work. (at least, in my case)

    Thank you joe, your comment was useful in my situation. I have been struggling with this problem as well. I did NOT want to rename my project to ROOT, but still be able to get to the application without using a /applicationName after the domainname/ip.

    I found out it did not really matter what you put in the path attributes and ROOT.xml in the conf directories etc. Only the server.xml in conf is important to solve this. It was very important for me to realize that.

    So the solution for me was to use this code inside server.xml:

    (Host name=”localhost” docBase=”/var/www/vhosts/domain.com/httpdocs” appBase=”/var/www/vhosts/domain.com/httpdocs” unpackWARs=”false” autoDeploy=”false”)
    (Context path=”” debug=”0″ docBase=”/var/www/vhosts/domain.com/httpdocs/MyProjectName”)(/Context)

    I can also use WARs, but I did not want to use that since I want to be able to only upload a specific part of my classes and other files. The WAR file itself is too big to upload for me, so now I can upload only those files I changed.

    My actual project is in httpdocs/MyProjectName, but I can access it in the url just by using my domain. Exactly as I wanted. It was very hard to find this out using google, lots of results, but lots of dead ends as well…

  23. Viorel Vesa said,

    July 3, 2012 at 9:40 pm

    If you apply the solution from comment 22, tomcat will instantiate MyProjectName app twice !!!
    Am I right ?

  24. July 28, 2012 at 7:44 am

    [...] kludge way is to just put your app into ROOT. Yuck. Well, its possible and easy. I found the hint here, in one of the comments.. Thanks [...]

  25. directory said,

    December 27, 2012 at 8:48 am

    Thank you for being our coach on this issue. We
    enjoyed your own article greatly and most of all enjoyed
    reading the way in which you handled the issues I regarded as
    being controversial. You are always rather kind to readers really like me and assist me to in
    my living. Thank you.

  26. Ofelia said,

    January 12, 2013 at 11:42 am

    Thanks for your post. My spouse and i have usually
    seen that almost all people are eager to lose weight because they
    wish to show up slim plus attractive. Nonetheless, they do not always realize
    that there are many benefits for losing weight additionally.
    Doctors claim that over weight people have problems
    with a variety of disorders that can be instantly attributed to
    their own excess weight. Thankfully that people who are overweight and also
    suffering from diverse diseases can help to eliminate the
    severity of the illnesses simply by losing
    weight. You are able to see a progressive but noticeable improvement in health while even a
    minor amount of fat loss is attained.

  27. visit here said,

    January 15, 2013 at 1:40 am

    This design is steller! You most certainly know how to keep a reader entertained.
    Between your wit and your videos, I was almost moved to
    start my own blog (well, almost…HaHa!) Excellent job.
    I really enjoyed what you had to say, and more than that, how you presented it.

    Too cool!

  28. January 17, 2013 at 8:01 am

    Just desire to say your article is as astonishing. The clarity in your post is simply nice and i could
    assume you’re an expert on this subject. Well with your permission allow me to grab your RSS feed to keep updated with forthcoming post. Thanks a million and please keep up the rewarding work.

  29. Taylor said,

    January 19, 2013 at 4:58 pm

    It’s wonderful that you are getting thoughts from this piece of writing as well as from our argument made at this place.

  30. seo cardiff said,

    January 26, 2013 at 8:02 am

    Bravo – Say it like it is!

  31. Enid said,

    February 10, 2013 at 1:50 am

    you’re actually a just right webmaster. The web site loading velocity is amazing. It sort of feels that you are doing any distinctive trick. Furthermore, The contents are masterwork. you’ve done a fantastic task in this subject!

  32. February 12, 2013 at 2:00 am

    This article will assist the internet users for setting up
    new weblog or even a weblog from start to end.

  33. New Post said,

    February 15, 2013 at 4:45 am

    I do not comment routinely on peoples sites, generally
    simply because the content is awful and I’m not there long enough to care…. however, this webpage actually made me stop in my tracks. The information is awesome, and I do mean awesome. Great work and I’ve bookmarked the website and will return later, eager for more.

  34. March 4, 2013 at 12:13 am

    Hi, its pleasant paragraph regarding media print, we all know media is a wonderful source of facts.

  35. March 5, 2013 at 6:23 pm

    I don’t even understand how I ended up here, but I assumed this put up used to be good. I don’t know
    who you might be but certainly you’re going to a famous blogger in case you are not already. Cheers!

  36. March 13, 2013 at 1:08 am

    Hello There. I found your blog using msn. This is a really
    well written article. I’ll make sure to bookmark it and return to read extra of your useful info. Thanks for the post. I’ll definitely return.

  37. March 13, 2013 at 5:08 am

    If some one needs to be updated with most up-to-date
    technologies after that he must be visit this
    web page and be up to date everyday.

  38. More hints said,

    March 23, 2013 at 3:12 pm

    I love your blog.. very nice colors & theme. Did you make this website yourself
    or did you hire someone to do it for you? Plz reply
    as I’m looking to construct my own blog and would like to know where u got this from. many thanks

  39. March 27, 2013 at 2:22 am

    It’s very straightforward to find out any topic on net as compared to textbooks, as I found this paragraph at this website.

  40. March 28, 2013 at 10:40 am

    My developer is trying to persuade me to move to
    .net from PHP. I have always disliked the idea because of the
    costs. But he’s tryiong none the less. I’ve been using WordPress on numerous websites for about a year
    and am nervous about switching to another platform.
    I have heard great things about blogengine.net. Is there a way I can import all my wordpress posts into it?

    Any help would be really appreciated!

  41. 10ztalk.com said,

    April 4, 2013 at 10:46 pm

    If you wish for to take a great deal from this article then
    you have to apply such techniques to your won website.

  42. April 15, 2013 at 4:33 am

    In rder to c rrect ur nt stinal functi n nd burn fat,
    increase their metabolism, and helps carry oxygenated blood around the hoodithin body by adding it to any
    diet. The fiber helps to regulate blood sugar levels will improve.
    There is a way to sustain themselves to this day.
    His hoodithin was unbelievable. Non-prescription pills like Metabolife and Herbalife supplement
    for the loss in weight. Without planning your meals in smaller bites.
    These shakes come in packages of 6 at Walmart.

  43. May 28, 2013 at 12:01 pm

    You are so awesome! I don’t believe I’ve read through anything like that
    before. So nice to discover somebody with a few original thoughts on this subject.

    Seriously.. thank you for starting this up. This website is something that’s needed on the web, someone with a bit of originality!

  44. June 2, 2013 at 10:54 am

    I seldom leave remarks, however i did some searching and wound
    up here How to Configure Tomcat root context | My Digital Neuron.

    And I actually do have a couple of questions for
    you if it’s allright. Could it be just me or does it seem like some of the remarks come across as if they are left by brain dead people? :-P And, if you are writing at additional online social sites, I would like to keep up with everything new you have to post. Would you list of all of your public sites like your linkedin profile, Facebook page or twitter feed?

  45. June 7, 2013 at 4:30 pm

    And commission rates have kind of been where they have been
    independently screened for Pv Cell Fabrication energy RE purchase.
    The wind blows when the wind blows regularly. In a study published Feb.
    Our risk management for the fourth quarter for the fourth quarter which is approximately 91% of our stated operating capacity.
    And then we’ll really see the impact in Sep, Dec.

  46. Janine said,

    June 22, 2013 at 11:49 am

    consumers give contemporary features such as, digital controls, removable brewing models, programmed timers, revolving force,
    plates control, automatic cup lifts for variable models,
    and additionally built in grinders. What is the
    best consume of coffee with no the appropriate coffee maker?
    whenever you take the effort to choose out the finest top quality of
    coffee beans, find the favorite roast, and additionally find the most perfect blends,
    you really need to discover the coffee maker that will .

  47. June 22, 2013 at 1:03 pm

    donne vous un Aviateur d’Interdiction de Ray bon marché si votre do pas a déjà l’un, ou peut-être parfait votre très propre la collection avec tout neuf conceptions l’aviateur d’interdiction de rayon 2013 avec.
    bon marché Les lunettes d’Interdiction de Ray qui a contrasté avec son aîné avec ceci simple toutefois l’idée révolutionnaire, which was à exchange
    les branches et métallique structures. fait pas va de le
    style, de plus à the shape fl le rétablissement de rétablissement par le créateur de
    chaque un des solaire toutefois jamais notice le exact même achievements.

  48. June 23, 2013 at 5:16 pm

    Once your team is actually adept as part of appealing to
    potential customers, no firm can stop your after achieving soaring income.
    While you definitely will remain aware and also follow new trends
    and options about webpage, it definitely will automatically bring a significant change in your internet site.
    Careful analysis of your very own existing company information can unearth helpful information to benefit you as part of defining
    your very own competitive advantages. Losing the trained team affiliate can impact the effectiveness of your entire strategy and
    also cost you greatly in missed opportunities.
    Your very own job is actually to stop justifying precisely why
    your sales are flat or down and also find a method to
    get individuals those to buy after your.

  49. July 1, 2013 at 8:56 am

    Thanks for sharing your info. I really appreciate your efforts and I am waiting
    for your next post thanks once again.

  50. July 14, 2013 at 5:46 am

    We stumbled over here coming from a different web page and thought I may
    as well check things out. I like what I see so now i’m following you. Look forward to looking over your web page yet again.

  51. August 7, 2013 at 10:51 pm

    Another benefit to Water Damage Repair software is what’s holding your medical practice will flourish and grow. Water Damage Repair systems bring several advantages to a practice and are being used world wide to smoothen out work processes. The job can, at times, be very stressful as well. Timely submission of claimsWater Damage Repair providers should be well versed with the procedure codes as it is important to any clinical set up for it to function professionally and cover the basic expenses occurred, per patient. What about outsourcing If you have not updated your diagnosis codes.

  52. jockey said,

    August 18, 2013 at 8:50 am

    Initial and foremost, it’s essential to know the kind of equipment that will give the best lead to mixing music. Having being awoke out of a sound sleep he got up out of his bed and went into the kitchen where the puppy was and starting hollering at it to be quite. He neatly managed to place the Suburban, Queens County and the Yonkers Handicap and maintained a presence by finishing third in the Jockey Club Gold Cup and the Whitney Handicap.

  53. September 20, 2013 at 2:10 am

    Let me take this opportunity to say just how much I benefit from viewing this blog site.

    It never fails to make me think.

  54. January 17, 2014 at 12:40 am

    Why visitors still make use of to read news papers when in this technological globe all is accessible on net?

  55. Bryon said,

    February 14, 2014 at 12:34 pm

    The form-based interface is slightly cluttered, but everything that you need to publish is available, from existing categories and tags to the functionality to create new ones. Following the code above you can now also round the header’s corners:.

  56. stellarseo said,

    April 10, 2014 at 11:25 am

    I’m really enjoying the design and layout of your blog. It’s a very easy on the eyes which makes it much more enjoyable for
    me to come here and visit more often. Did you hire out a developer
    to create your theme? Superb work!

  57. September 22, 2014 at 7:42 am

    Hi there, the whole thing is going sound here and
    ofcourse every one is sharing data, that’s really excellent, keep up writing.

  58. September 22, 2014 at 8:59 am

    Hey! I know this is somewhat off topic but I was wondering
    if you knew where I could get a captcha
    plugin for my comment form? I’m using the same blog platform as yours
    and I’m having trouble finding one? Thanks a lot!


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: