Install Lucee Using a Jar

This article provides instructions for how to install and run Lucee in Tomcat, while also allowing you to run other non-Lucee applications in the same application server.

The following assumptions are made about the environment in which you will be running your Lucee application. These steps may work with other operating systems or versions of the software, but I have not personally tested them.

• Tomcat 8.5
• Java 8
• Lucee 5.3.6.61
• Debian 9

1. Download the Lucee jar file from their downloads page.

   wget https://cdn.lucee.org/lucee-5.3.6.61.jar -O lucee.jar
   

2. Place the jar in the lib folder of your Tomcat installation.

   mv lucee.jar /var/lib/tomcat8/lib/
   

3. If you plan to have more than one website, you’ll need to edit the server.xml file. The majority of the xml file has been omitted for brevity.

   ...
   <Engine name="Catalina" defaultHost="localhost">
       <Realm className="org.apache.catalina.realm.LockOutRealm">
           <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
               resourceName="UserDatabase"/>
       </Realm>
   
       <!-- Handles all requests that don't match the name or aliases defined below -->
       <Host name="localhost"  appBase="webapps" unpackWARs="true" autoDeploy="true">
           <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
               prefix="localhost_access_log" suffix=".txt"
               pattern="%h %l %u %t &quot;%r&quot; %s %b" />
   
       </Host>
       <Host name="example.com"  appBase="webapps" unpackWARs="true" autoDeploy="true">
           <!-- 
               If you want to be able to access the website or lucee admin page
               you can add the hostname of your server as an alias
           -->
           <Alias>lucee-prod1.example.com</Alias>
           <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
               prefix="example_com_access_log" suffix=".txt"
               pattern="%h %l %u %t &quot;%r&quot; %s %b" />
   
       </Host>
   </Engine>
   ...
   

4. Create the directory for your website, along with the WEB-INF folder, and create the web.xml file.

   mkdir -p /var/lib/tomcat8/webapps/example.com/WEB-INF
   touch /var/lib/tomcat8/webapps/example.com/WEB-INF/web.xml
   

5. Add the following web.xml file to let Tomcat know that your application runs using one of the Lucee servlets.

   <?xml version="1.0" encoding="UTF-8"?>
   <!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at
       http://www.apache.org/licenses/LICENSE-2.0
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
   -->
   <web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
                       https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
   version="5.0"
   metadata-complete="true">
   
       <display-name>Welcome to Lucee</display-name>
       <description>
           Welcome to Lucee
       </description>
   
       <!-- ===================================================================== -->
       <!-- Lucee CFML Servlet - this is the main Lucee servlet                   -->
       <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <servlet id="Lucee">
           <description>Lucee CFML Engine</description>
           <servlet-name>CFMLServlet</servlet-name>    
           <servlet-class>lucee.loader.servlet.CFMLServlet</servlet-class>
           <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
           <!-- to specify the location of the Lucee Server config and libraries,   -->
           <!-- uncomment the init-param below.  make sure that the param-value     -->
           <!-- points to a valid folder, and that the process that runs Lucee has  -->
           <!-- write permissions to that folder.  leave commented for defaults.    -->
           <!--
           <init-param>
               <param-name>lucee-server-root</param-name>
               <param-value>/var/Lucee/config/server/</param-value>
               <description>Lucee Server configuration directory (for Server-wide configurations, settings, and libraries)</description>
           </init-param>
           !-->
           <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
           <!-- to specify the location of the Web Contexts' config and libraries,  -->
           <!-- uncomment the init-param below.  make sure that the param-value     -->
           <!-- points to a valid folder, and that the process that runs Lucee has  -->
           <!-- write permissions to that folder.  the {web-context-label} can be   -->
           <!-- set in Lucee Server Admin homepage.  leave commented for defaults.  -->
           <!--
           <init-param>
               <param-name>lucee-web-directory</param-name>
               <param-value>/var/Lucee/config/web/{web-context-label}/</param-value> 
               <description>Lucee Web Directory (for Website-specific configurations, settings, and libraries)</description>
           </init-param>
           !-->
           <load-on-startup>1</load-on-startup>
       </servlet>
       <servlet-mapping>
           <servlet-name>CFMLServlet</servlet-name>
           <url-pattern>*.cfc</url-pattern>
           <url-pattern>*.cfm</url-pattern>
           <url-pattern>*.cfml</url-pattern>   
           <url-pattern>/index.cfc/*</url-pattern>
           <url-pattern>/index.cfm/*</url-pattern>
           <url-pattern>/index.cfml/*</url-pattern>
           <!-- url-pattern>*.cfm/*</url-pattern !-->
           <!-- url-pattern>*.cfml/*</url-pattern !-->
           <!-- url-pattern>*.cfc/*</url-pattern !-->
           <!-- url-pattern>*.htm</url-pattern !-->
           <!-- url-pattern>*.jsp</url-pattern !-->
       </servlet-mapping>
   </web-app>
   

   For REST based services, add the following.

   <!-- ===================================================================== -->
   <!-- Lucee REST Servlet - handles Lucee's RESTful web services             -->
   <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
   <servlet id="RESTServlet">
       <description>Lucee Servlet for RESTful services</description>
       <servlet-name>RESTServlet</servlet-name>    
       <servlet-class>lucee.loader.servlet.RestServlet</servlet-class>
       <load-on-startup>2</load-on-startup>
   </servlet>  
   <servlet-mapping>
       <servlet-name>RESTServlet</servlet-name>
       <url-pattern>/rest/*</url-pattern>
   </servlet-mapping>
   

6. Once your website is configured, restart Tomcat to begin serving your Lucee website.

   systemctl restart tomcat8