To build a Docker image, you need to create a Dockerfile. A Dockerfile is a file that contains instructions on how to build the Docker image. By default, the file is named Dockerfile and this naming is used in the instructions below. To learn more about Docker, see https://docs.docker.com/get-started/.
Prerequisites
In addition to a Dockerfile, the following files are required to build the Docker image:
- <service_name>.war - a deployable archive of the desired web application, e.g., webapp.war, collaborator.war, or admin.war.
- logback.xml - the logging configuration file. To learn how to configure data logging, see Configuring data logging.
- webappplatform.properties - the file with Web Application Platform configuration properties
- you may also need additional files, like email or document export templates that need to be copied to the web container.
Note that running multiple Docker images without resource limitation can consume too much of the host machine’s memory and cause "out of memory" kills. For more information on how to set resource constraints for a Docker container, refer to https://docs.docker.com/config/containers/resource_constraints/.
Here is a sample Dockerfile that can be used to build the Docker image:
FROM tomcat:10.1.8-jre17-temurin-jammy
ARG TOMCAT_DIR=/usr/local/tomcat
ARG SET_ENV_FILE=/usr/local/tomcat/bin/setenv.sh
ARG USER_UID=5000
ARG USER_GID=${USER_UID}
COPY logback.xml ${TOMCAT_DIR}/shared/conf/
COPY webappplatform.properties ${TOMCAT_DIR}/shared/conf/
COPY <service_name>.war ${TOMCAT_DIR}/webapps/
RUN sed -i "s|shared\.loader=*$|shared\.loader=\"\${catalina.base}/shared/conf\"|" ${TOMCAT_DIR}/conf/catalina.properties && \
echo 'export JAVA_OPTS="$JAVA_OPTS ${WEBAPP_PROPERTIES}"' >> ${SET_ENV_FILE} && \
chmod o+x ${SET_ENV_FILE} && \
groupadd --gid ${USER_GID} tomcat && \
useradd -r --uid ${USER_UID} --gid ${USER_GID} -s /sbin/nologin -d ${TOMCAT_DIR} -c "Tomcat user" tomcat && \
chown -R tomcat:tomcat ${TOMCAT_DIR} && \
chown -R root:root ${TOMCAT_DIR}/bin/*.sh && \
rm -rf webapps.dist
USER tomcat
EXPOSE 8080
CMD ["catalina.sh", "run"]
Instructions in the Dockerfile may be written in several ways depending on your particular needs and preferences. The table below lists script statements you can use with descriptions and the indication of whether the script part is required or optional.
| Script statement | Required or optional | Description |
|---|---|---|
FROM tomcat:10.1.8-jre17-temurin-jammy | Required | In the FROM part where the base image needs to be specified, Tomcat should be selected as the base image and its version has to be compatible with the version of the web application code. |
| ARG TOMCAT_DIR=/usr/local/tomcat | Optional | An argument used as an intermediary variable to store the Tomcat directory location. The location may differ depending on a particular base image used in the FROM part. This argument is introduced for convenience since further instructions reference the Tomcat directory location multiple times. |
| ARG SET_ENV_FILE=/usr/local/tomcat/bin/setenv.sh | Optional | The path to the setenv.sh file which is used to set JAVA options. |
| ARG USER_UID=5000 | Required | The user ID that will be assigned to the Tomcat user (for Tomcat to be run as a Tomcat user and not a root). |
| ARG USER_GID=${USER_UID} | Required | An argument used to set a user group for the Tomcat user. |
COPY logback.xml ${TOMCAT_DIR}/shared/conf/ | Optional (recommended) | Since Web Application Platform uses logback as the logging framework, there should be its configuration file available in the classpath. This command copies the logging configuration into the folder that will be included in the classpath. Note that it is possible to use other names for the configuration file. In this case, the script should be updated to reference another file. It is possible to omit the configuration file but it is not recommended. |
COPY webappplatform.properties ${TOMCAT_DIR}/shared/conf/ | Optional | This command copies the properties file to the folder that is present in the classpath. If it is not copied, then an alternative solution must be used to reference the properties file. To learn about alternative options, see Passing properties to services. |
COPY <service_name>.war ${TOMCAT_DIR}/webapps/ | Required | This command copies the web application to the Tomcat deployment folder. Note that you can put multiple web applications in the same docker image. To do that, add a separate command for each .war file. |
RUN sed -i "s|shared\.loader=*$|shared\.loader=\"\${catalina.base}/shared/conf\"|" ${TOMCAT_DIR}/conf/catalina.properties && \ echo 'export JAVA_OPTS="$JAVA_OPTS ${WEBAPP_PROPERTIES}"' >> ${SET_ENV_FILE} && \ chmod o+x ${SET_ENV_FILE} && \ groupadd --gid ${USER_GID} tomcat && \ useradd -r --uid ${USER_UID} --gid ${USER_GID} -s /sbin/nologin -d ${TOMCAT_DIR} -c "Tomcat user" tomcat && \ chown -R tomcat:tomcat ${TOMCAT_DIR} && \ chown -R root:root ${TOMCAT_DIR}/bin/*.sh && \ rm -rf webapps.dist | Required if any additional files need to be in the classpath | This command updates the Tomcat configuration to include ${TOMCAT_DIR}/shared/conf in the classpath. In addition, it sets JAVA_OPTS and assigns permissions and a group to the Tomcat user. |
| USER tomcat | Required | Specify the user which will be used to start Tomcat. |
EXPOSE 8080 | Required | The value should correspond to the one that is used by Tomcat to deploy the web application. You can use port 8080 or 8443 if SSL is needed. |
CMD [“catalina.sh”, “run”] | Required | A command used to run the Tomcat server. |
Here is a sample command to build the Docker image:
docker build –t <image_name:version> .
The provided build command will work only if the Dockerfile script and all the files referenced in the script (in this case <service_name>.war, logback.xml, and webappplatform.properties) are stored in the current directory. To build Docker images using non-default file locations, consult the Docker documentation.
When a Docker image is successfully built, you can run the Docker container on port 8080 by executing the following command:
docker run -p 8080:8080 <image_name:version>