Installation using Tomcat as the application server

Prerequisites

Installing the Java Runtime Environment

You can download the Java Runtime Environment directly at http://java.sun.com/ or as a debian archive at http://www.debian-unofficial.org/index.html . If you're downloading the original package from Sun, this is the way how you may install it on your system:

  1. Download Java SE Runtime Environment (JRE) for Linux from http://java.sun.com/ (jre-6-linux-i586.bin was the latest version at the time when this guide was written).
  2. Install JRE in directory /opt .
    # cd /opt/
    # sh /tmp/jre-6-linux-i586.bin
    # ln -s jre1.6.0 jre
  3. Use Debian update-alternatives to include the Java binaries into the system path.
    # update-alternatives --install /usr/bin/java java /opt/jre/bin/java 200
  4. You may also include the following lines in /etc/profile:
    JAVA_HOME=/opt/jre
    export JAVA_HOME

Installing the Apache Tomcat Java Application Server

  1. Download Tomcat 5.5.x or greater from http://tomcat.apache.org/ (jakarta-tomcat-5.5.20.tar.gz was the latest version at the time when this guide was written).
  2. Unpack the archive in /opt and set symlink
    # cd /opt/
    # tar xfz /tmp/apache-tomcat-5.5.20.tar.gz
    # ln -s apache-tomcat-5.5.20 tomcat
  3. Set up user, group and permissions
    # adduser --system --group --home /opt/tomcat --no-create-home tomcat
    # chown tomcat.tomcat -R apache-tomcat-5.5.20
  4. Remove web applications you don't need from /opt/tomcat/webapps :
    # cd /opt/tomcat/webapps/
    # rm -rf balancer servlets-examples jsp-examples webdav tomcat-docs
  5. Create a symlink to catalina.sh which is used by the tomcat startup script below.
    $ ln -s /opt/tomcat/bin/catalina.sh /usr/bin/tomcat
  6. Edit /opt/tomcat/conf/server.xml and shorten it to:
    <Server port="8005" shutdown="SHUTDOWN">
        <Service name="Catalina">
            <Connector port="8080" />
            <Engine name="Catalina" defaultHost="localhost">
                <Host name="localhost" appBase="webapps" />
            </Engine>
        </Service>
    </Server>
  7. Installing an init-script /etc/init.d/tomcat for Apache Tomcat
    #! /bin/sh -e
    #
    # /etc/init.d/tomcat -- startup script for the Tomcat 5.5 servlet engine
    #
    # Written by Miquel van Smoorenburg <miquels@cistron.nl>.
    # Modified for Debian GNU/Linux by Ian Murdock <imurdock@gnu.ai.mit.edu>.
    # Modified for Tomcat by Stefan Gybas <sgybas@debian.org>.
    # Modified for Tomcat 5.5 by Oliver J. Siegmar <oliver@siegmar.org>.
    
    PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
    NAME=tomcat
    DESC="Tomcat 5.5 servlet engine"
    DAEMON=/usr/bin/$NAME
    CATALINA_HOME=/opt/$NAME
    
    # The following variables can be overwritten in /etc/default/tomcat5
    
    # Run Tomcat 5.5 as this user ID (default: tomcat5)
    # Set this to an empty string to prevent Tomcat from starting automatically
    TOMCAT5_USER=tomcat
    
    # The first existing directory is used for JAVA_HOME (if JAVA_HOME is not
    # defined in /etc/default/tomcat5)
    JAVA_DIRS="/opt/jre"
    
    # Arguments to pass to the Java virtual machine (JVM)
    CATALINA_OPTS="-Djavax.net.ssl.trustStore=/etc/tomcat/truststore.jks"
    
    # Use the Java security manager? (yes/no)
    TOMCAT5_SECURITY="no"
    
    # End of variables that can be overwritten in /etc/default/tomcat5
    
    # overwrite settings from default file
    if [ -f /etc/default/tomcat5 ]; then
            . /etc/default/tomcat5
    fi
    
    test -f $DAEMON || exit 0
    
    # Look for the right JVM to use
    for jdir in $JAVA_DIRS; do
            if [ -d "$jdir" -a -z "${JAVA_HOME}" ]; then
                    JAVA_HOME="$jdir"
            fi
    done
    export JAVA_HOME
    export CATALINA_OPTS
    
    # Define other required variables
    PIDFILE="/var/run/$NAME.pid"
    LOGDIR="$CATALINA_HOME/logs"
    WEBAPPDIR="$CATALINA_HOME/webapps"
    STARTUP_OPTS=""
    if [ "$TOMCAT5_SECURITY" = "yes" ]; then
            STARTUP_OPTS="-security"
    fi
    
    # CATALINA_PID for catalina.sh
    export CATALINA_PID="$PIDFILE"
    
    case "$1" in
      start)
            if [ -z "$TOMCAT5_USER" ]; then
                echo "Not starting $DESC as configured (TOMCAT5_USER is empty in"
                echo "/etc/default/tomcat5)."
                exit 0
            fi
            if [ -z "$JAVA_HOME" ]; then
                echo "Could not start $DESC because no Java Runtime Environment"
                echo "(JRE) was found. Please download and install JRE 5.0 or higher and set"
                echo "JAVA_HOME in /etc/default/tomcat5 to the JRE's installation directory."
                exit 0
            fi
    
            echo -n "Starting $DESC using Java from $JAVA_HOME: "
    
            # Remove dangling webapp symlinks
            for webapp in "$WEBAPPDIR"/*; do
                if [ "$webapp" != "$WEBAPPDIR/*" -a ! -e "$webapp" ]; then
                    echo "Removing obsolete webapp $webapp" >>"$LOGDIR/catalina.out"
                    rm "$webapp" >> "$LOGDIR/catalina.out" 2>&1 || true
                fi
            done
    
            # Symlink new webapps from /usr/share/java/webapps
            for webapp in /usr/share/java/webapps/*; do
                if [ -e "$webapp" -a ! -e "$WEBAPPDIR/`basename $webapp`" \
                            -a ! -e "$WEBAPPDIR/`basename $webapp .war`" ]; then
                    echo "Symlinking new webapp $webapp" >>"$LOGDIR/catalina.out"
                    ln -s "$webapp" "$WEBAPPDIR" || true
                fi
            done
    
            mkdir -p "$CATALINA_HOME/work/_temp"
            touch "$PIDFILE" "$LOGDIR/catalina.out" || true
            chown --dereference "$TOMCAT5_USER" "$PIDFILE" "$LOGDIR" \
                "$LOGDIR/catalina.out" "$CATALINA_HOME/work" \
                "$CATALINA_HOME/temp" || true
            if start-stop-daemon --test --start --pidfile "$PIDFILE" \
                    --user $TOMCAT5_USER --startas "$DAEMON" >/dev/null; then
                    # -p preserves the environment (for $JAVA_HOME etc.)
                    # -s is required because tomcat5's login shell is /bin/false
                    su -p -s /bin/sh $TOMCAT5_USER \
                            -c "\"$DAEMON\" start $STARTUP_OPTS" \
                            >>"$LOGDIR/catalina.out" 2>&1
                    echo "$NAME."
            else
                    echo "(already running)."
            fi
            ;;
      stop)
            echo -n "Stopping $DESC: "
            if start-stop-daemon --test --start --pidfile "$PIDFILE" \
                    --user $TOMCAT5_USER --startas "$DAEMON" >/dev/null; then
                    echo "(not running)."
            else
                    su -p $TOMCAT5_USER -c "\"$DAEMON\" stop" >/dev/null 2>&1 || true
                    # Fallback to kill the JVM process in case stopping did not work
                    sleep 1
                    start-stop-daemon --stop --oknodo --quiet --pidfile "$PIDFILE" \
                            --user "$TOMCAT5_USER"
                    rm -f "$PIDFILE"
                    echo "$NAME."
            fi
            ;;
      restart|force-reload)
            $0 stop
            sleep 1
            $0 start
            ;;
      *)
            echo "Usage: /etc/init.d/tomcat {start|stop|restart|force-reload}" >&2
            exit 1
            ;;
    esac
    
    exit 0
  8. Update the different rc.d to start automatically Tomcat with the default runlevels:
    # update-rc.d tomcat defaults
  9. Starting tomcat
    # /etc/init.d/tomcat start

Installing Japt-Proxy

  1. Download Japt-Proxy from http://sourceforge.net/project/showfiles.php?group_id=160609
  2. Unpack the archive
    # cd /tmp
    # tar xfz japt-proxy-1.4-bin.tar.gz
  3. Configure the proxy
    # cp /tmp/japt-proxy-1.4/japt-proxy.conf.xml /opt/tomcat/common/classes

    Now edit /opt/tomcat/common/classes/japt-proxy.conf.xml to your neeeds. See Configuration section for details.

  4. Set up the cache directory
    # mkdir -m 0750 /var/cache/japt-proxy
    # chown tomcat /var/cache/japt-proxy
  5. Install the proxy
    # cp /tmp/japt-proxy-1.4/japt-proxy-1.4.war /opt/tomcat/webapps/japt-proxy.war

Using Japt-proxy

  1. Adjust /etc/apt/sources.list and edit the entries to use Japt-Proxy
    1. Example for Debian 4.0 (Etch):
      deb http://localhost:8080/japt-proxy/debian etch main contrib
      deb http://localhost:8080/japt-proxy/debian-security etch/updates main contrib
    2. Example for Debian Lenny:
      deb http://localhost:8080/japt-proxy/debian lenny main contrib
      deb http://localhost:8080/japt-proxy/debian-security lenny/updates main contrib
  2. Now, that everything is set up you can use apt-get as usual
    # apt-get update
    # apt-get upgrade

    ...everything is now downloaded by the proxy. You can do a tail -f /opt/tomcat/logs/japt-proxy.log to see what the proxy is doing.