Picture of Brian Love wearing black against a dark wall in Portland, OR.

Brian Love

Lucee on Mac OS X Yosemite Quick Start

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

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

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:

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.