In this blog post I will show you how to easily setup Lucee in Tomcat. Lucee is a Java Servlet and therefore needs to run inside a Java Servlet Container; Tomcat is the most popular Servlet Container in the market.

You can watch the video, or just read the blog post. Either way, you'll be up and running in no time. 

We will take the following steps:

1. Download the Tomcat distribution ZIP file and the Lucee distribution JAR file
2. Create a CATALINA_HOME directory by extracting the Tomcat archive locally
3. Create a CATALINA_BASE directory using the makebase utility
4. Configure Lucee in the CATALINA_BASE directory
5. Launch Tomcat to test the installation

This setup is cross-platform, and will work similarly on Windows, Linux, or Mac, with minor changes in the batch/shell scripts, and file paths. The only requirement is that you have Java installed, and you can test that easily by opening a command prompt or terminal window, and running the command:

java -version

If you get the Java version information then you're all set. If you get an error, then install Java and ensure that it is added to the PATH.

The first thing to do is to download the Tomcat distribution from the Tomcat website [1]. For this example let's use the current stable version which is 9.0.11. The second file that we need to download is the Lucee JAR file from the Lucee download site [2]. We'll use the latest available Snapshot Lucee JAR at the time of this post, version 5.3.1.51.

The two most important settings for Tomcat are the environment variables CATALINA_HOME and CATALINA_BASE. CATALINA_HOME should point to the folder that contains the files from the Tomcat download.

By default, CATALINA_BASE points to the same directory as CATALINA_HOME, but specifying a separate directory allows us to override the config settings of CATALINA_HOME. That makes it easy to run multiple configurations side by side, or update the Tomcat binaries without worrying about the configuration settings, so we will use different values for the two variables.

Installing Tomcat in this configuration is super simple. Extract the contents of the downloaded archive to the target local directory. That directory will be our "CATALINA_HOME".; let's go ahead and extract the contents to a directory named "tomcat", effectively setting our CATALINA_HOME at "tomcat/apache-tomcat-9.0.11".

New versions of Tomcat come with a handy utility called "makebase". We will call makebase and pass the target directory name, "lucee/lucee-8080".

:: on Windows
<CATALINA_HOME>\bin\makebase.bat lucee\lucee-8080

or

## on Linux
<CATALINA_HOME>/bin/makebase.sh lucee/lucee-8080

That instance will listen on port 8080, which is the default Tomcat port. That way we will be able to easily add other instances that will listen on different ports.  The directory structure for CATALINA_BASE is similar to the one in CATALINA_HOME. All of our configuration changes will be made in the CATALINA_BASE directory. This will also allow us to easily upgrade Tomcat in CATALINA_HOME in the future without worrying about losing the configuration settings of our application.

Now we can set up Lucee.  Let's copy the lucee.jar file to the <CATALINA_BASE>/lib directory.

Next we will open <CATALINA_BASE>/webapps and create a default site. The default site goes into a directory named "ROOT", and inside that we will create a directory named "WEB-INF", and in it a file named web.xml. These names are CaSe sensitive so be sure to have the directory names in all UPPERCASE and the file name in lowercase. 

Next, let's copy the Lucee configurations [3] into the web.xml file. The settings in <SITE>/WEB-INF/web.xml will override the settings in <CATALINA_BASE>/conf/web.xml.

The last thing to do is to add a small startup script which will set the values for the CATALINA_HOME and CATALINA_BASE environment variables, and launch Tomcat by calling the <CATALINA_HOME>/bin/catalina script (.sh or .bat depending on your platform), passing the "run" command, e.g.

:: on Windows
call %CATALINA_HOME%/bin/catalina.bat run

or

## on Linux
exec ${CATALINA_HOME}/bin/catalina.sh run

Our configuration is now complete. You can confirm it by adding a small CFML script, launch Tomcat, and point a web browser to http://localhost:8080/.

We hope that this tutorial has been useful to you. Let us know if you have any questions in the comments below. 

[1] http://tomcat.apache.org/

[2] https://download.lucee.org/

[3] https://gist.github.com/isapir/e00d7174251c88529c2dfc5e898fb8dc