Lucee Docker File breakdown: lucee/lucee51

LAS provides a series of official Docker images for the Lucee server running on Apache Tomcat. They’re production ready, and are used daily by teams to serve Lucee based solutions.

You can rely on these base images within your own project, or copy the approach as a starting point for building your own image from scratch. As the maintainers of the images, we thought it might be helpful to breakdown the reasoning behind the layers.

Dockerfile for Lucee 5.1

The simplest base image is a straight Debian / OpenJDK / Apache Tomcat stack with Lucee server installed. You can use the internal Tomcat Coyote HTTP server to serve pages or front-end the container with your own web server. We also have an NGINX/Lucee compound image you might find interesting.

FROM tomcat:8.0.38-jre8

MAINTAINER Daemonites <hello@daemon.com.au>

ENV LUCEE_JARS_URL http://release.lucee.org/rest/update/provider/loader/5.1.0.34
ENV LUCEE_JAVA_OPTS "-Xms256m -Xmx512m"

# Download core JAR, and delete it in one step to avoid committing the installer in a FS layer
RUN wget -nv $LUCEE_JARS_URL -O /root/lucee.jar && \
	mkdir -p /usr/local/tomcat/lucee && \
	cp /root/lucee.jar /usr/local/tomcat/lucee/lucee.jar && \
	rm -rf /root/lucee.jar

# Delete the default Tomcat webapps so they aren't deployed at startup
RUN rm -rf /usr/local/tomcat/webapps/*

# Set Tomcat config to load Lucee
COPY catalina.properties server.xml web.xml /usr/local/tomcat/conf/

# Custom setenv.sh to load Lucee
COPY setenv.sh /usr/local/tomcat/bin/
RUN chmod a+x /usr/local/tomcat/bin/setenv.sh

# Create Lucee configs
COPY lucee-server.xml /opt/lucee/server/lucee-server/context/lucee-server.xml
COPY lucee-web.xml.cfm /opt/lucee/web/lucee-web.xml.cfm

# Provide test page
RUN mkdir -p /var/www
COPY index.cfm /var/www/
ONBUILD RUN rm -rf /var/www/*

# lucee first time startup; explodes lucee and installs bundles/extensions
RUN /usr/local/tomcat/bin/catalina.sh start && \
    while [ ! -f "/opt/lucee/web/logs/application.log" ] ; do sleep 2; done && \
    /usr/local/tomcat/bin/catalina.sh stop

# Replace the Trusted SSL Certificates packaged with Lucee with those from Debian
#   ca-certificates package from the OS is the most recent authority
RUN cp -f /etc/ssl/certs/java/cacerts /opt/lucee/server/lucee-server/context/security/cacerts

Let’s break it all down.

Tomcat base image

FROM tomcat:8.0.38-jre8

Each Lucee Docker image is built on the latest v8.x official Tomcat Docker image at the time of release. While Lucee should run on any servlet container, we have standardised on Tomcat as our officially supported servlet engine for all installers.

We like using the base Tomcat image as it lets us leverage all the work done in that community to get a best practice Debian / OpenJDK Java / Tomcat stack in place.

Maintainer

MAINTAINER Daemonites <hello@daemon.com.au>

If you have any improvements for the image please contact us through the github project or via email.

Environment Variables

ENV LUCEE_JARS_URL http://release.lucee.org/rest/update/provider/loader/5.1.0.34
ENV LUCEE_JAVA_OPTS "-Xms256m -Xmx512m"

LUCEE_JARS_URL is used for convenience only; it is easier to update the URL to the latest lucee.jar release. You should not pass this in as a variable at run time.

LUCEE_JAVA_OPTS is referenced in the setenv.sh shell script used by Tomcat at start-up. You can pass in any string of Java options you need, and they will be applied within the setenv.sh. The default value of -Xms256m -Xmx512m is set in the setenv.sh as well but we put it here so folks are more aware of the ENV option.

Note, Lucee server itself responds to a whole range of specific environment variables for server configuration options. The ones noted here just relate to the Docker image.

Installing Lucee into Tomcat

# Download core JAR, and delete it in one step to avoid committing the installer in a FS layer
RUN wget -nv $LUCEE_JARS_URL -O /root/lucee.jar && \
	mkdir -p /usr/local/tomcat/lucee && \
	cp /root/lucee.jar /usr/local/tomcat/lucee/lucee.jar && \
	rm -rf /root/lucee.jar

We don’t use the standard Lucee linux installer as we rely on the official Tomcat Docker image. We install Lucee by copying the latest release lucee.jar into the right location.

# Delete the default Tomcat webapps so they aren't deployed at startup
RUN rm -rf /usr/local/tomcat/webapps/*

We remove all example Tomcat webapps from the installation; we don’t want potential attack vectors hanging about.

# Set Tomcat config to load Lucee
COPY catalina.properties server.xml web.xml /usr/local/tomcat/conf/

We copy a group of Lucee specific configs into place. You could override these in your project but that’s not common. You can see all the defaults we use here:

# Custom setenv.sh to load Lucee
COPY setenv.sh /usr/local/tomcat/bin/
RUN chmod a+x /usr/local/tomcat/bin/setenv.sh

The setenv.sh script mentioned earlier. It’s pretty standard with this exception:

# Use /dev/urandom for EGD (http://wiki.apache.org/tomcat/HowTo/FasterStartUp)
JAVA_OPTS="${LUCEE_JAVA_OPTS} -Djava.security.egd=file:/dev/./urandom";

We add the recommended entropy source for randomisation.

Configuration files

# Create Lucee configs
COPY lucee-server.xml /opt/lucee/server/lucee-server/context/lucee-server.xml
COPY lucee-web.xml.cfm /opt/lucee/web/lucee-web.xml.cfm

These are examples of the default server and web context configs for Lucee. To be honest we should probably just let Lucee auto-create these on initial start-up but they’re here just in case we need some Docker specific mods.

Build Test Page

# Provide test page
RUN mkdir -p /var/www
COPY index.cfm /var/www/
ONBUILD RUN rm -rf /var/www/*

We create a simple test page to assist in the build process; it helps to be able to see if the server is running properly. Note, the ONBUILD command deletes this page as soon as you use the image to build your own project.

Pre-Warm the Server

# lucee first time startup; explodes lucee and installs bundles/extensions
RUN /usr/local/tomcat/bin/catalina.sh start && \
	while [ ! -f "/opt/lucee/web/logs/application.log" ] ; do sleep 2; done && \
	/usr/local/tomcat/bin/catalina.sh stop

Lucee does a lot of stuff when it starts for the first time. It’s not something we want happening everytime we spin up a new container. This command is a bit of chicanery that starts up Lucee and shuts it down, effectively pre-warming the server.

Certs Refresh

# Replace the Trusted SSL Certificates packaged with Lucee with those from Debian
#   ca-certificates package from the OS is the most recent authority
RUN cp -f /etc/ssl/certs/java/cacerts /opt/lucee/server/lucee-server/context/security/cacerts

Certs can be a pain. We just make sure the latest base OS (currently Debian) certs are brought over for Lucee to use.

EXPOSE and CMD

We don’t EXPOSE any ports by default. Unfortunately, Tomcat exposes 8080 but we run Lucee on 8888 for historical reasons. You can’t UNEXPOSE at this time so exposing another port for a base image makes it awkward for automated configurations in orchestrated deployments. For now, no additional ports EXPOSED by default.

The process run is Tomcat, and that’s handled by the Tomcat base image so all good there.

lucee/lucee51 also acts as the base image for our popular Lucee/NGINX compound image.

https://labs.daemon.com.au/t/lucee-docker-file-breakdown-lucee-lucee51-nginx/291

This is the image we use most often as the base for our Lucee production environments.