Understanding application.cfc location, webroot, appBase, and docBase

dev support
7

Hahahahaha!!! Welcome to the club!!! And you know what? I think everyone, I mean literary “EVERYONE” needs to fall into the rabbit whole of the great question:

What’s the secret about “Tomcats appBase vs. docBase”?

It’s like Neo’s first jump in the “Jump Programm” in the SciFi-Film Matrix. Everybody fails it! As you can see, even Railos/Lucees (and Tomcat committer) very respected guru @isapir failed this one (see it here). More confusing is that he doesn’t (in my opinion) get an appropriate answer to his question there too. I’ll try to explain with my own words (and my own perspective). I would have wished to have such when I failed my “jump” with Railo :smiley:

As far as I understand, the attributes docBase and appBase have a historical context with Tomcat!

Tomcat was primary built as a Java-Engine to allow serving Java-Applications for the Web. So they created a global directory were you can throw all these Java-Applications into that directory as .war-files. That directory is defined with the appBase-attribute inside the <host ...>-directive in server.xml. It follows the convention that the name of the .war file is also the web path name for the application. The convention also defines that the web path served at “/” (without having any other characters for the path name) need the file to be named ROOT.war. So if you throw a Java-Web-Archive named “ROOT.war” into the directory for the appBase, Tomcat will deploy and serve that specific application at http://some.domain.com/.

So, when using a configuration in the server.xml:

// server.xml
<host name="some.domain.com" appBase="/opt/tomcat/webapps" ... >
...
</host>

and adding the following .war files to the appBase will follow a naming convention to serve with the paths as follows:

/opt/tomcat/webapps/ROOT.war serves => http://some.domain.com/
/opt/tomcat/webapps/administrator.war serves=> http://some.domain.com/administrator
/opt/tomcat/webapps/messaging.war serves=> http://some.domain.com/messaging

This means, appBase is a global directory location where Tomcat will deploy all those applications and serve them to the web by convention.

Note: the file types are not limited to .war, e.g. these can also be simple directories.

/opt/tomcat/webapps/ROOT.war (compressed Java Web Archive)
                      |-- some.jar
                      |-- somethin.jsp
                      |-- someOtherDirectory
                                |-- someelse.jar
                                |-- somethinelse.jsp


/opt/tomcat/webapps/ROOT/   (uncompressed as directory)
                      |-- some.jar
                      |-- somethin.jsp
                      |-- someOtherDirectory
                                |-- someelse.jar
                                |-- somethinelse.jsp

But what happens if you really need to break that convention? What would you need to do? That’s were the docBase in the Tomcats <context ...> directive comes into play. It allows you to serve such Java application by defining a web path name and reference it to a specific custom .war file (or directory).

(In older Tomcat versions) you would typically do that like so:

// server.xml
<host name= "some.domain.com" appBase="/opt/tomcat/webapps">
    <!-- serves at http://some.domain.com/ -->
    <Context path="/" docBase="/opt/wars/myownCustomRoot.war">
    ...
    </Context>

    <!-- serves at http://some.domain.com/administrator -->
    <context path="/administrator" docBase="/opt/wars/e259a62a-c516-4737-9eab-77ac6b6e2bf9.war">
    ...
    </context>

    <!-- serves at http://some.domain.com/messaging -->
    <Context path="/messaging" docBase="/opt/wars/ab4b7610-ad6e-4df8-a76e-db139d6c2d3a.war">
    ...
    </Context>
...
</host>

`If you understand that convention, you will also understand WHY the Lucee default application is ALWAYS installed with the /webapps/ROOT.

At some point (I think from Tomcat 8 upwards) the Apache Tomcat Team changed the configuration above. The above still works, but it’s not recommended anymore . Since Tomcat 8, you shouldn’t specify the docBase in the <context > directive within the body of the <host> directive anymore: Instead you should create an .xml configuration file following a very similar convention… like so:

For serving http://some.domain.com/:

// configuration file located at /opt/tomcat/conf/catalina/some.domain.com/ROOT.xml
<?xml version='1.0' encoding='utf-8'?>
<Context docBase="/opt/wars/myownCustomRoot.war">
  ...
</Context>

For serving http://some.domain.com/administrator

//  configuration file located at /opt/tomcat/conf/catalina/some.domain.com/administrator.xml
// to serve at http://some.domain.com/administrator
<?xml version='1.0' encoding='utf-8'?>
  <Context docBase="/opt/wars/e259a62a-c516-4737-9eab-77ac6b6e2bf9.war">
  ...
</Context>

For serving http://some.domain.com/messaging

//  configuration file located at /opt/tomcat/conf/catalina/some.domain.com/messaging.xml
// to serve at http://some.domain.com/messaging
<?xml version='1.0' encoding='utf-8'?>
<Context docBase="/opt/wars/ab4b7610-ad6e-4df8-a76e-db139d6c2d3a.war">
  ...
</Context>

Note that the “path” attribute now doesn’t exist in that <context>-directive, because it’s set by the file name (convention) of ROOT.xml, administrator.xml and messaging.xml file! Also, all the configuration that were formely in the body of the <context>-directive of the server.xml file are now set here too!
The confusion comes because nowadays we don’t use Tomcat like that anymore. We usually serve only one application served in one webroot. Everything else is inside that application.

The good thing is:
mod_cfml that is shipped with the Lucee Installer takes care of that all for you. It does all those settings automagically.

The bad thing:
If you need to do certain settings manually and set them up incorrectly, you might get into trouble. Especially if you set the docBase equally with the appBase, as it happened once to @ensemblebd as showed here.

As I said, everyone who is new to Tomcat is likely to fail the Matirx-Like Tomcat-Jump here :smiley: … and I felll also a lot like you!!!

A warm hugh and welcome!!!

2 Likes