Home

Peter Boughton edited this page Feb 22, 2015 · 3 revisions
Clone this wiki locally

Lucee on Jetty Wiki

Introduction

Lucee on Jetty is a project to provide a Lucee package that is easy to use and provides a fully functional & capable web server, with extensive documentation on how everything has been done, so it can be understood and adapted as needed.

Homepage: http://sorcerersisle.com/projects:lucee-on-jetty

This wiki documentation aims to be a compehensive guide, but you should also check out the readme files in each directory that give basic information and links to the relevant Jetty documentation. If anything in this wiki contradicts information in a readme file, the readme is more likely to be correct (and if you do find anything, please raise an issue so it can be corrected).

Other Documentation

This wiki covers topics relevant to Lucee on Jetty, and will generally provide links to pertinent pages in the respective docs for Jetty or Lucee that may cover a subject in more detail.

The documentation homepages for these are:

Jetty: http://www.eclipse.org/jetty/documentation/current/
Lucee: https://bitbucket.org/lucee/lucee/wiki/Home

A Note on Jetty Documentation

Jetty is very flexible software with multiple ways to achieve the same tasks, and diferent methods of configuration. This is due to the multitude of use cases Jetty has (including embedded within applications), and the abundance of choice can be reflected in its docs, with some pages containing multiple examples of different methods for doing the same thing, sometimes without it being clear which option is the best.

To confirm how Lucee on Jetty works, or for clarification of what something means or how to achieve something, feel free to raise an issue.

Starting the Server

Running Lucee on Jetty is as easy as unzipping and running a start-server script.

  • On Windows, double-click the start-server.bat file.
  • All other operating systems, execute start-server.sh instead.

Pressing Ctrl-C will shutdown the server.

Future releases will include a control script for easier start/stop/restart, along with the ability to check status and run as a background service/daemon.

Defaults

The HTTP server listens on port 8080 and the default context responds to localhost or 127.0.0.1

Browsing to http://localhost:8080 will run lucee-base/webapps/ROOT/index.cfm

The port can be changed in lucee-base/start.ini - changing it requires a Jetty restart.

The default context is configured in lucee-base/webapps/ROOT.xml - this file also allows virtual host aliases to be configured.

The default index.cfm contains links to Lucee Admins, which are available at http://localhost:8080/lucee/admin/server.cfm and http://localhost:8080/lucee/admin/web.cfm

Lucee non-default configuration

  • The lucee-server-directory parameter is set to use lucee-base/lucee-server instead of the lucee-base/lib/ext/lucee-server default.
  • The lucee-web-directory parameter is set to use lucee-base/webinfs/{web-context-label} instead of lucee-base/webapps/{context}/WEB-INF/lucee

File & Directory Structure

Excluding readme files, a Lucee on Jetty bundle looks like this:

lucee-on-jetty/
  jetty-home/                   Unmodified Jetty distribution.
  lucee-base/                   jetty-base configured for Lucee.
    etc/
      lucee-servlets.xml        Lucee servlet configuration.
      rewrite-rules.xml         Rewrite handler configuration.
    lib/
      ext/
        *.jar                   Lucee JAR files.
    logs/                       Jetty log files.
    lucee-server/               Lucee server context and patches.
    modules/
      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
  start-server.bat              Startup batch script (Windows).
  start-server.sh               Startup shell script.

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

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

The Lucee on Jetty start-server scripts work by going into the lucee-base directory, then calling jetty-home/start.jar to start Jetty using the config as per the lucee-base/start.ini file.

start.ini

This file is where you set which modules and configuration files to load on startup, and can override any default settings.

Jetty docs: Jetty Start Configuration Files

(If you have a large start.ini file, it can be split into multiple start.d/*.ini files, but this unnecessary for Lucee on Jetty.)

modules/lucee.mod

This file is a module definition for a Lucee module - it lists the other Jetty modules which Lucee depends on to run (ext for loading JARs, http for serving requests, jsp for servlet functionality).

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

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 lucee-base/log 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.

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 the overrideDescriptor, it activates the Lucee servlets for that context.

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

etc/rewrite-rules.xml

This file can be used to configure Jetty's Rewrite Handler. It comes with a single rule already defined, which enables .cfm/ URLs to work.

In addition to regex rewrites and redirects it also supports wildcards, plus the ability to set headers and cookies - as always, check the Jetty docs for more, but also take a look in jetty-home/demo-base/etc/demo-rewrite-rules.xml for some examples.

webapps/ROOT.xml

This file configures a webapp context named "ROOT", enables Lucee via the overrideDescriptor, 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 a new context can be created by saving a new XML file.

New contexts are picked up automatically by Jetty - the deploy module will check the webapps directory every minute - Check jetty-home/webapps/README.TXT for some basic info, or Hot Deployment 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.

Common Tasks

Change the port the server runs on

The HTTP server will run on the port specified by the jetty.port setting in the lucee-base/start.ini config file - changes to this file require a Jetty restarted to be picked up.

On Unix-based systems, for historical reasons, ports below 1024 require root permissions, so to listen on the default HTTP port 80, the Jetty documentation has various options at: Setting Port 80 Access for a Non-Root User.

Create a new site on a different domain

For each individual site you should create a new webapp context - there are a few ways to do this with Jetty, but the easiest is to open the lucee-base/webapps/ROOT.xml file, modify the resourceBase (webroot) and virtualHosts (domain aliases) as appropriate, and save it as a new XML file.

Point a new domain at an existing site

This is done by adding items to the virtualHost array in a webapp context. For example, the default ROOT.xml has this:

<Set name="virtualHosts">
    <Array type="String">
        <Item>localhost</Item>
        <Item>127.0.0.1</Item>
    </Array>
</Set>

But you might have a context set to:

<Set name="virtualHosts">
    <Array type="String">
        <Item>myluceesite.dev</Item>
        <Item>www.myluceesite.dev</Item>
    </Array>
</Set>

You can set wildcard subdomains, use punycode for non-ASCII domain names, and more: Configuring Virtual Hosts.

Upgrade Jetty

Upgrading Jetty is as simple as stopping the server, remove or rename the existing jetty-root directory, and put the new downloaded Jetty distribution in its place, then start the server again.

(Alternatively, instead of renaming the directories you can simply update the start-server script to point at the start.jar in the new Jetty directory.)

Upgrade Lucee

Lucee has its own upgrade functionality built-in - either via the Server Admin, or by placing an lco patch in the lucee-base/lucee-server/patches directory.

If it is necessary to do a full manual upgrade, you need to stop the server and replace the contents of lucee-base/lib/ext with a new Lucee JAR download. (You might be able to replace just lucee-base/lib/ext/lucee.jar file, or may need to replace ALL files in this directory.)

How do I do something not listed here?

Lucee on Jetty is an on-going project and this documentation is not yet complete.

To prioritise what gets added, please do request missing documentation via the GitHub issue tracker.