These notes for configurating Tomcat are geared toward a developers experience as opposed to running tomcat as service. The primary difference is the emphasis on direct user control over the running tomcat instance.

Prequisites

  • Make sure you've followed the JavaConfig instructions to ensure that an appropriate version of Java is installed.
  • Open YAST Software Management and switch to the "Search" filter in Software Management, and search on tomcat. You should select the tomcat55-webapps and tomcat55-admin-webapps packages. (Note: it will be tomcat5 on openSUSE 10.2)
  • Click "Install" and accept all the recommended dependancies.

Tomcat Configuration

A basic script to create a tomcat instance in your home directory follows. This gives you full privileges over the tomcat install and the ability start and stop with ordinary user (non-root) privileges. These instructions assume you are on a late model openSUSE install (>10.1).

Now follow all the command sets to complete the configuration. 

#
# Initialize context for Tomcat and openSUSE version
#
if [ -d /etc/tomcat5 ]
then
  version=5
  tcconfdir=/etc/tomcat5/base
else
  version=55
  tcconfdir=/etc/tomcat55
fi
#
# create the personal tomcat instance workspace
#
cd
mkdir tomcat
cd tomcat 
mkdir conf logs temp webapps work
cd webapps
tar -C /srv/www/tomcat$version/base/webapps/ -cf - \
  jsp-examples ROOT servlets-examples tomcat-docs webdav | \
  tar -xf -
#
# configure the personal tomcat instance workspace
#
cd ../conf
cp $tcconfdir/server-minimal.xml server.xml
cp $tcconfdir/web.xml .
cat > ~/bin/tc5 << EOF
#!/bin/bash

#
# A start/stop control script for the personal tomcat instance
#

# set up runtime environment. see catalina.sh for more options
export JAVA_HOME=/usr/lib/jvm/java
export CATALINA_BASE=$HOME/tomcat
export CATALINA_HOME=/usr/share/tomcat$version
export CATALINA_PID=\$CATALINA_BASE/logs/tomcat.pid

# use $HOME as proc cwd
cd $HOME

\$CATALINA_HOME/bin/catalina.sh \$1
EOF
chmod +x ~/bin/tc5

You can then start and stop tomcat with tc5 start and tc5 stop.

Installing the Tomcat manager and system administrator web applications requires extra steps. These webapps were installed as part of the prerequisits above, but they are restricted to access by tomcat in the default install. We will just copy them from the system install, but need to be a privileged user to read them.

This is done as a security measure to prevent ordinary users, who might have access to this host running a server instance of Tomcat, from discovering anything about the administrator services. Our copying of these directories will perserve the permissions but change the ownership to our user account, therefore, other users won't be able to discover attributes of our personal Tomcat's administrative interfaces through the back door of a local account.

The first step is to create a tarball of the system installation of the admin webapps and the related configuration files: 

su -c "tar --dereference -C /srv/www/tomcat$version/base -cf /tmp/tc-server.tar server"

su -c "tar -C $tcconfdir -cf /tmp/tc-server-config.tar Catalina"

Next we install the files into our personal tomcat instance 

cd ~/tomcat
tar -xf /tmp/tc-server.tar
cd conf
tar -xf /tmp/tc-server-config.tar

Once these files have been installed, the tar archives are no longer needed and can be removed: 

su -c "rm /tmp/tc-server.tar /tmp/tc-server-config.tar"

Because we are running out of a different $CATALINA_BASE, we need to update the server configuration files to point at this location: 

cd ~/tomcat/conf/Catalina/localhost
for file in *
do 
  sed -e '/docBase/s/catalina.home/catalina.base/' $file > $file.new
  mv $file.new $file
done
rm -f balancer.xml # remove config if it exists

The configuration file balancer.xml is part of the Tomcat5 install by default but is not needed because our development platform won't be using load balancing. To learn more about load balancing and get a sense for why we don't need it on the dev platform see the load balancing howto.

Note: the patch scripts originally listed for this step were problematic because they didn't work effectively across tomcat versions, since the config files have a different structure. The sed command makes for a better heuristic substitution.

You'll need to create a user list for tomcat to control access to the administrative applications: 

cd ~/tomcat/conf
cat > tomcat-users.xml << EOF
<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="tomcat"/>
  <role rolename="role1"/>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="tomcat" password="tomcat" roles="tomcat"/>
  <user username="role1" password="tomcat" roles="role1"/>
  <user username="both" password="tomcat" roles="tomcat,role1"/>
  <user username="admin" password="hard2Guess" roles="manager,admin"/>
</tomcat-users>
EOF

The user admin with the manager and admin privileges is the account to use for access to the administrative applications.

Note: if you are plan to build Java web applications, you Should will need to have $CATALINA_BASE and $CATALINA_HOME active during the build. You can choose to add these permanently to your shell configuration or simply source the tc5 file at build time with source $HOME/bin/tc5 (you can safely ignored the help message generated by catalina.sh as a result).

References