myquartz/tomcat-xslt repository overview

⁠The tomcat-libxslt container build

This contains building scripts for Apache Tomcat with LibXSLT for XML configuration mangling. Supported Tomcat versions:

1. Tomcat 8.5 with JDK 8, 11
2. Tomcat 9 with JDK 11, 17
3. Tomcat 10.0, 10.1 with JDK 11, 17, without or with CDI and CXF modules compiled.
4. AMD64 and ARM64/v8 platform support.

⁠Supported features

1. Context-based: the startup script will create the context-deployed "conf/Catalina/localhost/application.xml" file for application.war.
2. Global resource: the startup script will update conf/server.xml into for the resource.
3. HTTP/HTTPS Port changing
4. Data Source
5. Realm by Data Source and LDAP
6. Tomcat Cluster

For context-based deployment, an ENV named DEPLOY_CONTEXT has to be defined to indicate your application.war name. If not, ROOT.war assumed.

For more information, please go to GitHub page at: https://github.com/myquartz/tomcat-libxslt/tree/main⁠

⁠HTTP/HTTPS/AJP Ports

You can change the listening port of the tomcat instance by the following ENV variables:

1. TOMCAT_HTTP_PORT: the HTTP port - default to 8080 - changing to element in the server.xml.
2. TOMCAT_HTTPS_PORT: the HTTPS port - default to empty - changing to element in the server.xml (no keystore yet).
3. TOMCAT_AJP_PORT: the AJP port - default to 8009 - changing to element in the server.xml.
4. CONNECTOR_MAX_THREADS: maximum threads of the connector.

⁠Data Source

A context-based data source or a global-based data source will be added to context.xml or server.xml accordingly, based-on enviroment variables.

The following ENV variables to define a data source:

• DB_SOURCENAME (context-based) or GLOBAL_DB_SOURCENAME (global): the data source name to create, eg: jdbc/data_source
• DB_CLASS: the class name of JDBC Driver, eg: org.h2.Driver or com.mysql.cj.jdbc.Driver
• DB_URL: the JDBC URL for the data source, eg: jdbc:h2:mem:test or jdbc:mysql:server:port/dbname
• DB_USERNAME: the username for connection to the database.
• DB_PASSWORD or DB_PASSWORD_FILE: the password or the file contains the password for database connection
• DB_POOL_MAX: maximum connections of the pool - 50 by default
• DB_POOL_INIT: initial connections when starting the data source - 0 by default
• DB_IDLE_MAX: idle connections
• DB_VALIDATION_QUERY: the query for connection validation, empty by default.

When defining these parameters (bold name must have), the will be created/updated to context.xml or server.xml look like:

<Resource
  auth="Container" 
  type="javax.sql.DataSource" 
  factory="org.apache.tomcat.jdbc.pool.DataSourceFactory" 
  minIdle="0"
  name="${DB_SOURCENAME} or ${GLOBAL_DB_SOURCENAME}" driverClassName="${DB_CLASS}"
  url="${DB_URL}" username="${DB_USERNAME}" password="${DB_PASSWORD}"
  maxActive="${DB_POOL_MAX}" initialSize="${DB_POOL_INIT}" maxIdle="${DB_IDLE_MAX}"
  validationQuery="${DB_VALIDATION_QUERY}" />

⁠Data Source Realm

This Realms is for Servlet/Application authentication by a table hosting at the data source. If a context-based/global data source created, the realm will be set to context-based or global/context DB_SOURCENAME accordingly.

The following ENV variables to define the realm:

• REALM_USERTAB: the table name defines users' data.
• REALM_ROLETAB: the table name defines users' role data.
• REALM_USERCOL: the column name of username (default to username).
• REALM_CREDCOL: the column name of hassed password (default to hashpassword). More detail of hashed password is at https://tomcat.apache.org/tomcat-9.0-doc/config/credentialhandler.html⁠)
• REALM_ROLECOL: the column name of an user's role.
• ALL_ROLES_MODE: the value of attribute "allRolesMode", one of value 'strict' or 'authOnly' or 'strictAuthOnly'.
• REALM_ALGORITHM: the algorithm for hashing password, default to SHA-512, it can be SHA-1, SHA-256.. the hashpassword column is formatted by Tomcat value.
• REALM_INTERATIONS: the interation count for hashing password, it should be 1.
• REALM_SALT_LENGTH: the length of salt value.
• REALM_ENCODING: character encoding (eg UTF-8) while hashing.

When defining these parameters, the will be created/updated to context.xml or server.xml look like:

<Realm className="org.apache.catalina.realm.DataSourceRealm"
  dataSourceName="${DB_SOURCENAME} or ${GLOBAL_DB_SOURCENAME}"
  userTable="${REALM_USERTAB}" userNameCol="${REALM_USERCOL}" userCredCol="${REALM_CREDCOL}"
  userRoleTable="${REALM_ROLETAB}" roleNameCol="${REALM_ROLECOL}"
  allRolesMode="${ALL_ROLES_MODE}">
  <!-- if REALM_ALGORITHM and REALM_INTERATIONS defined -->
  <CredentialHandler className="org.apache.catalina.realm.MessageDigestCredentialHandler"
    algorithm="${REALM_ALGORITHM}" interations="${REALM_INTERATIONS}"
    saltLength="${REALM_SALT_LENGTH}" encoding="${REALM_ENCODING}"
  />
</Realm>

⁠Your own application

To build an image for the web application named booking.war in the container-based tomcat instance, your application lookup JNDI resource named "jdbc/ds" to access the MySQL Database. you can define a Dockerfile as:

FROM myquartz/tomcat-xslt:9-jdk11

#Download appropriate drivers from Maven
RUN curl -sSo /usr/local/tomcat/lib/mysql-connector-java-8.0.30.jar https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.30/mysql-connector-java-8.0.30.jar
#RUN curl -sSo /usr/local/tomcat/lib/postgresql-42.5.4.jar https://repo1.maven.org/maven2/org/postgresql/postgresql/42.5.4/postgresql-42.5.4.jar

ENV TOMCAT_HTTP_PORT=8088
EXPOSE 8088
 
ENV DEPLOY_CONTEXT=booking
ENV DB_SOURCENAME=jdbc/ds
ENV DB_CLASS=com.mysql.cj.jdbc.Driver
ENV DB_URL=jdbc:mysql://mysqldb:3306/dbname
ENV DB_USERNAME=db_username
ENV DB_PASSWORD=

COPY target/booking.war /usr/local/tomcat/webapps/booking.war

Build and run the image:

mvn package
docker build -t booking-app .
docker run -d -p 8088:8088 -e DB_URL=jdbc:mysql://your-db-server-ip:3306/dbname -e DB_USERNAME=you -e DB_PASSWORD=your-password booking-app

Now open http://localhost:8088/booking⁠ for demostration.