Common Tasks

Change the port the server runs on

The HTTP server will run on the port specified by the jetty.http.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.

Enable HTTPS requests

To enable HTTPS with Jetty, you need to:

create a lucee-base/etc/keystore file containing SSL certificate data.
create lucee-base/etc/jetty-ssl-context.xml containing KeyStorePath and KeyStorePassword configuration.
optionally, override the default port with jetty.ssl.port=443 in start.ini file.
enable the functionality via the https module.
optionally, enable the ssl-reload module to avoid the need to restart when etc/keystore is updated.

A walkthrough for doing this with Let's Encrypt certificates is available at: https://www.sorcerers-tower.net/articles/configuring-jetty-for-https-with-letsencrypt

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-home 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 modules/lucee/lib with a new Lucee JAR download.

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 issue tracker, or via email.