mkoellges/tomcat repository overview

⁠Versions

The Docker containers are stored in the M|Docker Registry (M|DR) mkoellges/tomcat:[VERSION]. The following versions related to the appropriate Java Version are offered by us:

The Apache Tomcat is installed on an Ubuntu:18.04 inside the container. In the following documentation we talk about the Apache Tomcat.

⁠Basics

This container contains a version of Apache Tomcat. The Structure of the tomcat container is

/opt/                               # Base directory
     application/                   # All application related files are stored here
          appconfig/                # configuration yml files that define subsystems like datasources, logging adapters etc. 
          java/                     # Application Archives (warfiles or jarfiles) that needs to be deployed
     data/                          # static files
     tomcat/                        # application server software (Apache Tomcat install directory)

In this Documentation the following variables are used:

TOMCAT_HOME=/opt/tomcat
TOMCAT_CONFIG_DIR=${TOMCAT_BASE_DIR}/conf

WORKING_DIR=${TOMCAT_BASE_DIR}

APPLICATION_STAGE_DIR=/opt/application/java
YML_STAGE_DIR=/opt/application/appconfig

The Tomcat Docker image runs on base on Docker image mkoellges/ubuntu:java[RELEASE] - means, that the Tomcat is running on top of Ubuntu Linux and a supported OpenJDK release.

In this Tomcat instance, the following Database drivers are already installed:

- Oracle RDBMS
- Postgres
- MySQL

After the tomcat instance is up and running, you can access the admin console URL it using http://[HOSTNAME]:8080/manager .

Username: admin Password: default is "change_me1", but you can use your own by changing the ENV Parameter "PASSWORD"

To store static files that are referenced in your application use the directory.

/opt/data

This directory can be accessed inside of your application using the Webresource location /mydata - use this location inside your application to consume the static files.

⁠Run the container

This way starts the container in a method, that all JVM parameters can be passed on command line call for the docker run.

docker run -d \
       --env JVM_PARAM=" -Xms2048m -Xmx2048m" \
       --env CONFIG_TYPE="standalone" \
       --env PASSWORD="change_me1" \
       --name [MY_NAME] \
       -p 8080:8080 \
      registry.metroscales.io/[YOURPROJECTNAME]/[YOURIMAGENAME]:[YOUR_VERSION_TAG]

The environment parameter JVM_PARAM can include all JVM parameters and options needed. The environment parameter PASSWORD defines the password of the Web Admin Console.

⁠1. Copy the application archive (war or jar)

To ensure that your container contains your software, copy the application archive (.jar or .war) to the container directory ${APPLICATION_STAGE_DIR} mentioned above. When it is part in this directory it will be deployed on start of the container. You do not need to do anything - simply copy the file.

If you have more than one application that needs to be deployed - copy all your application archives in this directory. If you have to deploy them in an order, name them with a prefix like '01-application1.war', '02-application2.jar' etc. Then the order of the numbers will be taken care and the archives will be deployed on container start in this order.

Here some special cases:

⁠1.1 Want to create subfolders in your context root for an application?

If a sub context root is wanted, so that the application will be accessible via a different context root as the warfare name is, simply create a subfolder in $APPLICATION_STAGE_DIR and copy the warfile in this folder. Then create a deployment descriptor file with the full context root path - use the # as "/" substitution for the filename. Example:

Create a Dockerfile like this:

FROM mkoellges/tomcat:9.0
 
MAINTAINER [email protected]
 
CMD mkdir /opt/application/java/start
COPY apptest.war /opt/application/java/start/apptest.war
COPY ./images/Metro_logo_neu.jpg /opt/data/metro.jpg
COPY apptest#start.xml /opt/tomcat/conf/Catalina/localhost

Deployment descriptor file (in this example "apptest#start.xml":

<?xml version='1.0' encoding='utf-8'?>
<Context docBase="/opt/application/java/start/apptest.war" />

Run the container and the application will be accessible via URL http://localhost:8080/apptest/start⁠.

This can be used for exploded application deployment too.

⁠1.2 Exploded Deployments

If you want to deploy an application in exploded way (unarchived directory copy) simply create a directory with the name of the application in ${APPLICATION_STAGE_DIR} folder and create a deployment descriptor xml file that points to this directory. Copy this deployment descriptor file to the directory ${TOMCAT_HOME}/conf/Catalina/localhost. Here an example for a Dockerfile using exploded deployments:

First create the deployment descriptor file:

<?xml version='1.0' encoding='utf-8'?>
<Context docBase="/opt/application/java/myapp" />

Now create the Dockerfile:

FROM mkoellges/tomcat:9.0

MAINTAINER [email protected]

CMD mkdir /opt/application/java/myapp
COPY [MYAPPFOLDER]/. /opt/application/java/myapp/
COPY myapp-deployment-descriptor.xml /opt/tomcat/conf/Catalina/localhost/myapp-deployment-descriptor.xml

⁠2. Create a data-source definition file

Define the values in a yml file on the machine you are working with a name of the file of your choice. Inside of the container, the filename must be data-source.yml and it must be placed in the directoy ${YML_STAGE_DIR} mentioned above. To be able to stage your application, do not copy the data-source.yml file into the container - mount it to this ${YML_STAGE_DIR}/data-source.yml at runtime of your container.

Example of a data-source.yml file:

DSName:
  dbtype: "[DBType]"      # required
  maxTotal: "300"
  maxIdle: "30" 
  maxWaitMillis: "10000" 
  initialSize: "20"
  username: "USERNAME"   # required
  password: "PASSWORD"   # required
  url: "URL depending on DBType"

It is possible to define more than one database using aditionally yml sections. All parameters of JDBC configuragion for Apache Tomcat can be used. Check the original documentation of Apache Tomcat here: hhttps://tomcat.apache.org/tomcat-8.0-doc/jdbc-pool.html#Attributes.

The following databases are supported, their drivers are already installed and they use the following urls:

MySql    :  jdbc:mysql://[IP Address or Nodename]:[Port]/[DBName]
Postgres :  jdbc:postgresql://[IP Address or Nodename]:[Port]/[DBName]
Oracle   :  jdbc:oracle:thin:@[IP Address or Nodename]:[Port]:[SID or ServiceName]

The connection configuration parameters are not required. If none of the following parametes is set in the yml file, the default values below are used:

maxTotal="300"
maxIdle="30"
initialSize="10"
maxWaitMillis="10000"

Minimalist example:

metroGroup:
   type: javax.sql.DataSource
   url: jdbc:postgresql://10.96.146.242:5432/mydatabase
   username: myuser
   password: mypassword

⁠Check if the container is running from an external loadbalancer (F5)

If the container shall be used behind a F5 Loadbalancer (Big-IP), the probing of the connectivity between loadbalancer and Application server can be done using the URI "/check.html". This will return a small html file with the content "Ich bin die MidTier CONTAINERNAME" where CONTAINERNAME is the "hostname" of the running, just started container.

⁠Example to create a container running an application

As you see, it is quite simple to deploy an application. Create a Dockerfile like this

FROM mkoellges/tomcat:9.0

COPY apptest.war /opt/application/java/
COPY metro.jpg /opt/data/metro.jpg

Now build the application docker image like

docker build -t registry.metroscales.io/[YOURPROJECTNAME]/[YOURIMAGENAME]:[YOUR_VERSION_TAG]  .

After the application container is build, start the container on cmdline:

docker run -d --rm -p 8080:8080 -e JVM_PARAM="-Xms2048m -Xmx2048m" -e PASSWORD=mysecretpassword -v $PWD/appconfig/data-source.yml:/opt/application/appconfig/data-source.yml registry.metroscales.io/[YOURPROJECTNAME]/[YOURIMAGENAME]:[YOUR_VERSION_TAG]

Alternatively you can use a docker-compose. For this, create a file called docker-compose.yml with the following content:

version: '3'

services:

  appserver:
    image: registry.metroscales.io/[YOURPROJECTNAME]/[YOURIMAGENAME]:[YOUR_VERSION_TAG]
    ports:
      - 0.0.0.0:8080:8080
    restart: always
    volumes:
      - ./data-source.yml:/opt/application/appconfig/data-source.yml
    environment:
      - JVM_PARAM=-Xms2048m -Xmx2048m
      - PASSWORD=mysecretpassword

Now switch to the directory where this file is created in and simply run

docker-compose up -d

Now your application is up and running and can be accessed using the URL http://[HOSTNAME]:8080/[CONTEXTROOT] . The Admin console WebUI can be accessed using the URL http://[HOSTNAME]:8080/manager .

⁠Customize a running container and create a new one of it

When you started your container, you can change settings inside of it using the WebUI or connecting to it via "docker exec -it". Test you changes in your running container and if everything works as expected, you can create a new image of it with the command

docker commit -a [MAINTAINER] [CONTAINERID] registry.metroscales.io/[PROJECTNAME]/[REPOSITORY]:[TAG]

# example of it

docker commit -a [email protected] db9820233935 mkoellges/apptest-mk-test-1:1.0

Now you have persisted your changes in a new container and you can push this image into the Docker registry to be used on different nodes.