GeoWebCache

Why Java on Linux is such a mess

Java's closed source has created a lot of friction with the open source community. Consequently, distributions have generally been unable or unwilling to include Sun's JDK, and some developers have chosen do depend on alternative implementations that to this date do not mirror the original in performance or functionality. Therefore you must often pay close attention on Linux distributions to avoid interference by the wrong executable, especially if it is accidentally pulled in as a dependency.

Tomcat is generally clamped down too much by distributions and ships with some strange settings. The binaries that are distributed by the project are much easier to use. The downside is that you have to monitor security updates yourself, but distributions tend to lag Java issues by several months anyway.

My suggestions is to ignore what the distribution provides and install both Java and Tomcat separately. Provided you are comfortable with basic commands and user accounts you should be up and running in 15 minutes.

Installing Java

Go to http://java.sun.com , find the latest Standard Edition Java Development Kit for "Linux x64" (or "Linux" if you have a i586 system). At the time of writing it was "JDK 6 Update 14". You could also get the JRE, but it's just as well to pick up the JDK in case you want to run GeoServer 1.7.x. Download the .bin version, even if you are running an RPM based system. We do this because you may already have some version of Java installed, and this will interfere.

Open a command line, then go into /opt or create it if does not already exist. Then unpack the archive that you just downloaded (either prefix with 'sudo', or use 'su' first, to do it as root):

sh /path/to/jdk-6u14-linux-x64.bin

Agree to the terms, this will unpack the file into /opt

Installing Tomcat

Download the latest 6.x version from http://tomcat.apache.org/

Unpack it, as root, in /opt: 

cd /opt
tar xzvf /path/to/apache-tomcat-6.0.20.tar.gz

Correct the file permissions, replace <user> with the username that Tomcat will be running as 

cd /opt/apache-tomcat-6.0.20
chmod 755 bin/*
chown <user> -R logs temp webapps work

Setting up your environment

Often it is a good idea to have a dedicated user for running Tomcat, but that's a minor detail.

You need to set three environment variables as follows. If you use BASH as your shell, you can set them at the bottom of .bashrc or .bash_profile , which are files in your home directory. 

export PATH=/opt/jdk1.6.0_14_amd64/bin:$PATH
export JAVA_HOME=/opt/jdk1.6.0_14_amd64
export CATALINA_HOME=/opt/apache-tomcat-6.0.20

Note that for them to take effect you have to completely log out and log in again. To check, try the following commands: 

set |grep JAVA
set |grep HOME
java -version

Starting Tomcat

Change to the user that you run Tomcat as, for example sudo su -l <user>. Then start Tomcat using /opt/apache-tomcat-6.0.20/startup.sh

Point your browser to http://localhost:8080 and be greeted by the welcome page. See the documentation on how to add an administrative account.

That's it. You should of course subject this to load and do all sorts of testing, but in general you know have a stable setup that is likely to keep working for a long time even if the system receives large updates.

Installing GeoWebCache

The easiest way is to just load the WAR file through the admin interface. If you want more control, or replace the configuration files before starting, first switch to the user that Tomcat is running as. Create a directory in /opt/apache-tomcat-6.0.20/webapps, then unpack the WAR file (unzip geowebcache.war) inside this directory. Restarting Tomcat should load the servlet.

Stopping Tomcat

Tomcat can take a while to shut down, especially if there are waiting requests. Use /opt/apache-tomcat-6.0.20/shutdown.sh , verify that it's down by using ps -ef |grep java. If a client stalls it you can usually kill it without too much worry.

Additional points to look into

  • Install the Apache Portable Runtime
  • Optimize heap settings, use the -server runtime
  • Install JAI (Java Advanced Imaging)
  • Install ImageIO (Native library for Java)
  • Set up Maven to build GWC yourself