Establishing Customizable Tomcat Configuration

Deploying to Apache Tomcat often requires making changes to default configuration. These changes are often environment specific. Also, when upgrading a Tomcat to new version you need to be sure that all your custom changes have not been lost and were applied to new configuration. To deal with all that stuff Tomcat via separation of the configuration. This post contains step-by-step instruction will help you to establish custom tomcat configuration.

1. Installing tomcat

You download Tomcat distribution binary and extract it to some folder. I put it to ~/java/apache-tomcat-7.0.52. It is desirable to create a symlink to it. It would allow to switch to another version of tomcat without changing your scripts

bash

1ln -s ~/java/apache-tomcat-7.0.52 ~/java/tomcat

As alternative, you may install a tomcat from packages.

2. Create a folder to keep your custom configuration

Create a folder where you custom configuration will be located.
bash
```
1mkdir -p ~/java/custom-tomcat/{bin,conf,logs,work,webapps,temp}
```
Copy default server.xml, tomcat-users.xml configuration file to custom location. If you already have a customized server.xml then put it there
bash
```
1cp -v ~/java/tomcat/conf/server.xml ~/java/tomcat/conf/tomcat-users.xml ~/java/custom-tomcat/conf/[](null)
```
Set system property $CATALINA_BASE referring to base directory for resolving dynamic portions of a Catalina installation.
bash
```
1export CATALINA_BASE=~/java/custom-tomcat
```

Now you can start the Tomcat and see that it uses your custom configuration folder:

```
$ ./catalina.sh run
Using CATALINA_BASE:   /Users/maestro/java/custom-tomcat
Using CATALINA_HOME:   /Users/maestro/java/tomcat
Using CATALINA_TMPDIR: /Users/maestro/java/custom-tomcat/temp
...
```

3. Tomcat runtime parameters customization

To specify JVM options to be used when tomcat server is run, create a bash script $CATALINA_BASE/bin/setenv.sh. It will keep environment variables referred in catalina.sh script to keep your customizations separate.

Define $CATALINA_OPTS inside setenv.sh. Include here and not in JAVA_OPTS all options, that should only be used by Tomcat itself, not by the stop process, the version command etc. Examples are heap size, GC logging, JMX ports etc.

Example setenv.sh:

bash

 1echo "Setting parameters from $CATALINA_BASE/bin/setenv.sh"
 2echo "_______________________________________________"
 3
 4# discourage address map swapping by setting Xms and Xmx to the same value
 5# http://confluence.atlassian.com/display/DOC/Garbage+Collector+Performance+Issues
 6export CATALINA_OPTS="$CATALINA_OPTS -Xms1024m"
 7export CATALINA_OPTS="$CATALINA_OPTS -Xmx1025m"
 8
 9# Increase maximum perm size for web base applications to 4x the default amount
10# http://wiki.apache.org/tomcat/FAQ/Memory
11export CATALINA_OPTS="$CATALINA_OPTS -XX:MaxPermSize=256m"
12
13# Oracle Java as default, uses the serial garbage collector on the
14# Full Tenured heap. The Young space is collected in parallel, but the
15# Tenured is not. This means that at a time of load if a full collection
16# event occurs, since the event is a 'stop-the-world' serial event then
17# all application threads other than the garbage collector thread are
18# taken off the CPU. This can have severe consequences if requests continue
19# to accrue during these 'outage' periods. (specifically webservices, webapps)
20# [Also enables adaptive sizing automatically]
21export CATALINA_OPTS="$CATALINA_OPTS -XX:+UseParallelGC"
22
23# The hotspot server JVM has specific code-path optimizations
24# which yield an approximate 10% gain over the client version.
25export CATALINA_OPTS="$CATALINA_OPTS -server"
26
27# Disable remote (distributed) garbage collection by Java clients
28# and remove ability for applications to call explicit GC collection
29export CATALINA_OPTS="$CATALINA_OPTS -XX:+DisableExplicitGC"
30
31# Check for application specific parameters at startup
32if [ -r "$CATALINA_BASE/bin/appenv.sh" ]; then
33  . "$CATALINA_BASE/bin/appenv.sh"
34fi
35
36echo "Using CATALINA_OPTS:"
37for arg in $CATALINA_OPTS
38do
39    echo ">> " $arg
40done
41echo ""
42
43echo "Using JAVA_OPTS:"
44for arg in $JAVA_OPTS
45do
46    echo ">> " $arg
47done
48
49echo "_______________________________________________"
50echo ""

4. Migrate logging to Logback

Tomcat is configured to use Apache Commons Logging API by default. If you are using slf4j in your application and familiar with Logback, then it is reasonable to migrate your tomcat configuration to logback too. You may find details here

1. Installing tomcat

2. Create a folder to keep your custom configuration

3. Tomcat runtime parameters customization

4. Migrate logging to Logback

Links