File & Directory Structure

The key files and directories in a Lucee on Jetty bundle resemble the following:

lucee-on-jetty/
  jetty-home/                             Unmodified Jetty distribution.
  lucee-base/                             jetty-base configured for Lucee.
    logs/                                 Jetty log files.
    lucee-server/                         Lucee server context and patches.
      deploy/                             Lucee extension (lex) files.
    modules/
      lucee/                              Lucee module files.
        etc/
          lucee-servlets.xml              Lucee servlet configuration.
          rewrite-rules.xml               Rewrite handler configuration.
          lucee-webapp-common.xml         Common Jetty context configuration.
          lucee-global-webapp-common.xml  Applies common Jetty configuration to all contexts.
        lib/
          lucee*.jar                      Lucee jar file.
      lucee.mod                           Lucee module definition.
    resources/
      jetty-logging.properties            Jetty logging configuration
    webapps/
      ROOT/                               Default context's webroot.
        index.cfm
      ROOT.xml                            Default context configuration.
    webinfs/                              Lucee context configuration and log files.
    start.ini                             Jetty module enabling and configuration.
  README.TXT
  docs.pdf                                Lucee on Jetty offline documentation
  start-server.bat                        Startup batch script (Windows).
  start-server.sh                         Startup shell script.

jetty-home/

This is where Jetty itself is contained - the files in this directory are unmodified. Refer to Jetty documentation to understand the contents of this directory.

You can upgrade Jetty by renaming this directory and placing a new jetty-home (or jetty-distribution) in its place. (this will probably just work without issue, but as with all upgrades, performing a verified backup before doing it is recommended.)

lucee-base/

Jetty has the concept of jetty-home and jetty-base, allowing a Jetty distribution (jetty-home) to be used without modification by creating one or more jetty-base locations to extend or override the jetty-home settings without needing to change the jetty-home files.

The best place to understand this is the Jetty documentation: Managing Jetty Base and Jetty Home

Since this concept is still relatively new, some Jetty documentation may still refer to jetty-home (or rather, ${jetty.home}) in situations where the equivalent jetty-base location would now be the recommended location.

To help reduce confusion, Lucee on Jetty uses the name lucee-base for this directory, but if you prefer you can rename it to jetty-base - or indeed any name you like. (There is a single reference to lucee-base in each of the start-server scripts that should be updated to match the renamed directory, but otherwise nothing else is affected by what it is called.)

The start-server scripts work by going into the lucee-base directory, then calling ../jetty-home/start.jar from Java to start Jetty with configuration read from the start.ini file.

start.ini

This file is how Jetty is instructed which modules and configuration files to load on startup, and can override any default settings.

Jetty docs: Jetty Start Configuration Files

The minimum modules required to run a Lucee-enabled Jetty server are lucee, deploy and http - you may add/remove whatever other modules are useful to you.

logs/

This directory is where Jetty will place log files, including stderr and stdout, when the console-capture module is enabled.

For details on Jetty logging, see the Jetty documentation: http://www.eclipse.org/jetty/documentation/current/configuring-logging.html

Lucee log files are located within a web context's configuration directory, that is, within lucee-base/webinfs/{web-context-label}/logs

lucee-server/

This lucee-server directory is where Lucee stores the configuration for the Lucee Server and the patches when Lucee is updated - by default this directory is found in lib/ext/lucee-server (alongside the Lucee JARs), but this bundle has been configured for a more convenient location.

The context directory contains the lucee-server.xml config file for the Lucee Server Admin, along with other global/server-level files.

The patches directory will contain one or more X.X.X.xxx.lco files - the latest patch in this directory is the version Lucee will run.

A manual upgrade can be performed by copying a newer .lco file to this directory and restarting Lucee.

lucee-server/deploy/

The deploy directory is where Lucee looks for LEX extension files - when it finds them it will enable that module and remove the file from this directory.

See Lucee documentation for more details on extension deployment.

modules/

Jetty uses modules to group dependencies, libraries, and configuration so that a single module can be enabled without needing to manually enable all the others that it uses, and to verify that relevant files exist.

You may add your own modules to this directory, they will take effect if enabled in start.ini file. Jetty's built-in modules reside in jetty-home/modules/

You can read more about modules in the Jetty documentation: http://www.eclipse.org/jetty/documentation/current/startup-modules.html

modules/lucee.mod

The module definition file for the Lucee module - it lists the other Jetty modules which Lucee depends on to run (http for serving requests, jsp for servlet functionality).

It also references the main lucee.jar to verify it exists at the expected location.

Finally, it references the configuration files that instruct Jetty to handle CFML requests appropriately.

modules/lucee/

The modules/lucee directory contains supporting files for the Lucee Jetty module, and the jar file for Lucee.

modules/lucee/lib

This directory contains the Lucee jar file. You may place other JARs in this directory to have them loaded by Jetty and available to Lucee.

modules/lucee/etc/rewrite-rules.xml

This file uses Jetty's Rewrite Handler in order to allow .cfm/path_info URLs to work.

Jetty rewriting supports regex rewrites and redirects, as well as wildcards, plus the ability to set headers and cookies - see documentation at the above Jetty link for further information.

Since v0.7, Lucee on Jetty uses the Jetty rewrite jar but does not enable the Jetty rewrite module itself - you can do that manually if you wish to use it.

modules/lucee/etc/lucee-global-webapp-common.xml

This file uses Jetty's GlobalWebappConfigBinding to apply lucee-webapp-common.xml to all context config files.

It is enabled via an entry in the module definition file.

modules/lucee/etc/lucee-webapp-common.xml

This file contains Jetty configuration common to all contexts. Currently this involves only the overrideDescriptor required to apply lucee-servlets.xml and enable the Lucee servlets.

It is applied by the lucee-global-webapp-common.xml file described above.

modules/lucee/etc/lucee-servlets.xml

This file is a partial web.xml file which configures the Lucee servlets for a webapp context. On its own it doesn't do anything, but when included into a context's XML config file, via overrideDescriptor, it activates the Lucee servlets for that context.

(Previous versions of Lucee of Jetty required manually including the overrideDescriptor XML directly in the context's config file. This is no longer necessary, it is included automatically via the lucee-global-webapp-common.xml config.)

There are two Lucee servlets, the main CFMLServlet which handles CFML requests, and a RESTServlet for handling Lucee's RESTful web service functionality.

This file is also where you can define default "welcome" files that are used if a directory is requested - by default it contains index.cfm but it also inherits from the defaults in jetty-home/etc/webdefault.xml which includes index.html, index.htm and index.jsp

resources/

The resources directory is where Jetty's console-capture module looks for logging configuration, in the form of either jetty-logging.properties or logging.properties files.

You can read more about logging in the Jetty documentation: http://eclipse.org/jetty/documentation/current/configuring-logging.html

resources/jetty-logging.properties

This file configures the logging for Jetty - it has a single line to enable the StdErrLog class, which results in stderr and stdout being redirected to a log file in the logs directory.

For more advanced configuration, the Jetty documentation has a Jetty Logging chapter which also explains how to setup request logging and how to interface with different logging frameworks.

webapps/

This webapps directory is where Jetty WebApp Contexts are located.

There is one context by default - ROOT.xml - which listens on localhost and has its resourceBase (webroot) set to the lucee-base/webapps/ROOT directory.

Jetty's documentation for this is available online: http://www.eclipse.org/jetty/documentation/current/configuring-deployment.html

webapps/ROOT.xml

This file configures a webapp context named "ROOT", sets the webroot (resourceBase) to webapps/ROOT/ and specifies that it responds to localhost or 127.0.0.1

The resourceBase and virtualHosts can be re-configured as desired, or additional contexts can be created by saving new XML files.

New contexts are picked up automatically by Jetty - by default the deploy module will check the webapps directory every minute - this can be disabled with jetty.deploy.scanInterval=0 in start.ini, so that contexts are only looked for when the server is started. See the Hot Deployment documentation for more.

Multiple contexts can run from the same host by using a contextPath. Further details at Setting a Context Path.

Virtual Hosts can be fully qualified, use wildcards, IP addresses, connectors, and non-ascii domains via PunyCode. You can also tell Jetty to respond to any hostname that resolves to the machine by removing the virtualHosts section. Further information is at Configuring Virtual Hosts.

webinfs/

The webinfs directory contains the configuration for web contexts which Lucee has been enabled for - by default this would be found in a WEB-INF/lucee directory in each context's webroot (resourceBase), but this bundle has been configured to place them here instead. (Configuration is done via the CFMLServlet lucee-web-directory parameter in the etc/lucee-servlets.xml file.)

Each Jetty context that Lucee is enabled for will have its own directory, named as the web-context-label - this defaults to a unique hash but can be changed in Lucee Server Admin.

Unfortunately, Lucee does not allow web-context-label to be defined directly in the webapp context configuration, and the label is stored against the hash value. Since the value of the hash is derived simply by hashing the ServletContext, any time the context changes (e.g. due to an upgrade), the resulting hash will change, causing a new webinf directory to be created (whether a label is defined or not), and resetting any per-context configuration.