Brian Love
Angular + TypeScript Developer in Denver, CO

Lucee on Mac OS X Yosemite Quick Start

Reading time ~3 minutes

After the news of Railo being forked to a new project called lucee I wanted to check it out. I could have started with the express installation, but I wanted to deploy the WAR to my Tomcat 8 installation.

Quick Start:

  • Install Tomcat 8 via Homebrew
  • Configure Tomcat Manager app
  • Download Lucee WAR
  • Redeploy Lucee as ROOT web application
  • Set credentials for Lucee Server and Web Admins

Install Tomcat 8

The first step is to install Tomcat 8. If you already have Tomcat installed just skip to the next section on downloading the Lucee WAR file.

To install Tomcat I will be using Homebrew. First, let’s be sure homebrew is up-to-date, then let’s install Tomcat.

$ brew update
$ brew install tomcat

In my instance Tomcat was installed to the following path: /usr/local/Cellar/tomcat/8.0.20. To verify that your installation of Tomcat was successful, run the following command:

$ catalina version

You should get something similar to this as output:

Using CATALINA_BASE: /usr/local/Cellar/tomcat/8.0.20/libexec Using CATALINA_HOME: /usr/local/Cellar/tomcat/8.0.20/libexec Using CATALINA_TMPDIR: /usr/local/Cellar/tomcat/8.0.20/libexec/temp Using JRE_HOME: /Library/Java/JavaVirtualMachines/jdk1.7.0_55.jdk/Contents/Home Using CLASSPATH: /usr/local/Cellar/tomcat/8.0.20/libexec/bin/bootstrap.jar:/usr/local/Cellar/tomcat/8.0.20/libexec/bin/tomcat-juli.jar Server version: Apache Tomcat/8.0.20

Now, start up Tomcat using the command below. Once Tomcat has started you can go to the Tomcat start page. By default Tomcat is bound to port 8080. So, go to http://localhost:8080 in your browser to see the Tomcat start page.

Tomcat8 start page

Configure Tomcat Admin

The next step is to configure the Tomcat admin user account so that we can access the Tomcat Manager application. We will need to modify the tomcat-users.xml file. The file is located in our installation folder, then in the libexec/conf folder. The full path to my tomcat-users.xml file is: /usr/local/Cellar/tomcat/8.0.20/libexec/conf.

<role rolename="manager-gui"/>
<role rolename="admin-gui"/>
<user username="admin" password="Pa$$w0rd" roles="manager-gui,admin-gui"/>

After updating the tomcat-users.xml file we need to restart the tomcat server before we can log into the manager app. Simple tell catalina to stop and then start:

$ catalina stop
$ catalina start

Now I can fire up the manager app: http://localhost:8080/manager

Download Lucee WAR

  • Go to the Lucee project downloads
  • Download the latest version’s .war file
  • Place this file in your Tomcat’s webapp folder

My webapp folder is located at: /usr/local/Cellar/tomcat/8.0.20/libexec/webapps/, so here is the command that I used to copy the WAR to my webapps folder.

$ cp ~/Downloads/lucee-4.5.1.000.war /usr/local/Cellar/tomcat/8.0.20/libexec/webapps/

Once the .war file has been copied to the webapps directory, Tomcat will automatically deploy the application for us. After a couple of seconds you should see a folder in your webapps directory that matches the war file name. As I am deploying lucee-4.5.1.000.war, the folder created in my webapps directory is called lucee-4.5.1.000. If we want, we can now visit the Lucee start page at: http://localhost:8080/lucee-4.5.1.000/. But, you will probably notice that the images are not pulling up. This is because Lucee expects to run as the ROOT web application in your container (Tomcat).

Redeploy Lucee as ROOT application

Now that we have deployed Lucee to our Tomcat servlet container, let’s update our configuration so that Lucee is the ROOT application. To do this, we need to define the ROOT context. There are a couple of ways to do this. Here is what I decided to do:

  • Log into the Tomcat manager, and clicked on Undeploy for the ROOT ( / ) application and for the Lucee ( /lucee-4.5.1.000 ) app that we just installed.
  • Copy the Lucee war file outside of the webapps folder and extract the war file into this new location.
  • Created a ROOT.xml context file and set the path attribute to point to our application directory.
  • Restarted Tomcat.

First, let’s copy the Lucee war file to a new apps directory, and then extract it out.

$ cd /usr/local/Cellar/tomcat/8.0.20/libexec/
$ mkdir apps
$ cd apps
$ mkdir lucee-4.5.1.000
$ cp ~/Downloads/lucee-4.5.1.000.war /usr/local/Cellar/tomcat/8.0.20/libexec/apps/lucee-4.5.1.000
$ cd lucee-4.5.1.000
$ jar -xf lucee-4.5.1.000
$ rm lucee-4.5.1.000.war

Next, the ROOT.xml file should be placed in your $CATALINA_BASE/conf/[enginename]/[hostname]/ directory. In my case the enginename is Catalina and the hostname is localhost.

$ touch /usr/local/Cellar/tomcat/8.0.20/libexec/conf/Catalina/localhost/ROOT.xml

The ROOT.xml file should contain the following:

<?xml version="1.0" encoding="UTF-8"?>
<Context docBase="/usr/local/Cellar/tomcat/8.0.20/libexec/apps/lucee-4.5.1.000" reloadable="true"/>

After restarting Tomcat we can load up Lucee as the ROOT application: http://localhost:8080/. We should see a start page that looks like the screen shot below. Notice that the images are now correctly being displayed.

Lucee start page

Lucee Server and Web Admin

The last step is to set the credentials for accessing our Lucee server and web administration sites. To do this, simply load up the server and web admin sites and enter your new credentials.

  • Server Admin: http://localhost:8080/lucee/admin/server.cfm
  • Web Admin: http://localhost:8080/lucee/admin/web.cfm

Brian Love

Hi, I'm Brian. I am interested in TypeScript, Angular and Node.js. I'm married to my best friend Bonnie, I live in Denver and I ski (a lot).