Preparation: Updates and Upgrades

	apt-get update

	apt-get upgrade

 These commands update your apt system with what is available in the repositories, and upgrade any packages already installed to which upgrades are available. This seems like a good thing to do on a regular basis, or at least before any software installations.

Install Sun's Java 6 JDK

You could skip this step and jump down to Installing Tomcat 6.x, but the trouble is that the tomcat6 package by default installs an Open-Source JDK instead of that published by Sun Microsystems. This is all fine and good for Tomcat, but GeoServer does not work with the OpenJDK. Since we'll be wanting to use GeoServer on the machine, we need to install Sun's JDK. Fortunately, it's as easy as anything:

	apt-get install sun-java6-jdk

* Note (7/28/2010) -- Ubuntu 10 encourages you to use the OpenJDK by not allowing you to easily install the Sun JDK. See http://www.clickonf5.org/linux/how-install-sun-java-ubuntu-1004-lts/7777 for instructions on how to install the Sun JDK under these circumstances.

Installing Tomcat 6.x

	apt-get install tomcat6

It's just that easy. I also installed the admin package which gives us the tomcat manager and host-manager.

	apt-get install tomcat6-admin

You may also want to install the documentation.

	apt-get install tomcat6-docs

Starting and Stopping Tomcat

Use the following commands to start, stop and restart Tomcat

	/etc/init.d/tomcat6 start

	/etc/init.d/tomcat6 stop

	/etc/init.d/tomcat6 restart

These commands should be run with root privileges. The script you're running contains a command specifying the user that should end up running Tomcat itself. This user is called "tomcat6", is unprivileged, and was created when you installed the Tomcat package.

Configuring Tomcat 6.x

First, we need to define an admin user who can access the admin webapps that we installed. Open the file /etc/tomcat6/tomcat-users.xml and add the bold line:

<tomcat-users>
<!--
  <role rolename="tomcat"/>
  <role rolename="role1"/>
  <user username="tomcat" password="tomcat" roles="tomcat"/>
  <user username="both" password="tomcat" roles="tomcat,role1"/>
  <user username="role1" password="tomcat" roles="role1"/>
-->
  <user username="AdminUserName" password="AdminUserPassword" roles="admin,manager"/>
</tomcat-users>

At this point, restart Tomcat using the commands listed above. You can check that it is working by pointing your web browser to http://<Elastic IP Address>:8080. You should see a simple "It Works!" page. You can also point your browser to http://<Elastic IP Address>:8080/manager/html, enter the AdminUserName and AdminUserPassword that you used in the /etc/tomcat6/tomcat-users.xml file.

The next thing to configure is logging. We would like log files to be placed on the Elastic Data-store so that they can be read in the event that the instance crashes and burns. For our purposes, Tomcat logs will reside in /mnt/data-store/tomcat/logs. First we will adjust the paths to the log files in /etc/tomcat6/logging.properties. 

Change:

1catalina.org.apache.juli.FileHandler.level = FINE
1catalina.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
1catalina.org.apache.juli.FileHandler.prefix = catalina.

2localhost.org.apache.juli.FileHandler.level = FINE
2localhost.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
2localhost.org.apache.juli.FileHandler.prefix = localhost.

to:

1catalina.org.apache.juli.FileHandler.level = FINE
1catalina.org.apache.juli.FileHandler.directory = /mnt/data-store/tomcat/logs
1catalina.org.apache.juli.FileHandler.prefix = catalina.

2localhost.org.apache.juli.FileHandler.level = FINE
2localhost.org.apache.juli.FileHandler.directory = /mnt/data-store/tomcat/logs
2localhost.org.apache.juli.FileHandler.prefix = localhost.

Then lets add the directories, and set permissions appropriately. I copied the permission and ownership from the default log location.

mkdir /mnt/data-store/tomcat
mkdir /mnt/data-store/tomcat/logs
chown tomcat6:adm /mnt/data-store/tomcat/logs
chmod 0750 /mnt/data-store/tomcat/logs

There also seems to be a problem with the /etc/tomcat6/policy.d/catalina.policy file that prevents any logs from being written. This file specifies what permissions the .jar file that actually does the logging has. Out-of-the-box the way this file is written prevents log files from being written anywhere. We need to fix it, and make sure that it has read/write permissions to the directory where we want the logs to be. The bold lines below are things that had to be changed or added:

// These permissions apply to the logging API
grant codeBase "file:${catalina.home}/bin/tomcat-juli.jar" {
        permission java.util.PropertyPermission "java.util.logging.config.class", "read";
        permission java.util.PropertyPermission "java.util.logging.config.file", "read";
	permission java.lang.RuntimePermission "shutdownHooks";
        permission java.io.FilePermission "${catalina.base}${file.separator}conf${file.separator}logging.properties", "read";
	permission java.util.PropertyPermission "catalina.base", "read";
        permission java.util.logging.LoggingPermission "control";
	permission java.io.FilePermission "/mnt/data-store/tomcat/logs", "read, write";
        permission java.io.FilePermission "/mnt/data-store/tomcat/logs/*", "read, write";
        permission java.lang.RuntimePermission "getClassLoader";
	permission java.lang.RuntimePermission "setContextClassLoader";
        // To enable per context logging configuration, permit read access to the appropriate file.
        // Be sure that the logging configuration is secure before enabling such access
        // eg for the examples web application:
        // permission java.io.FilePermission "${catalina.base}${file.separator}webapps${file.separator}examples${file.separator}WEB-INF${file.separator}classes${file.separator}logging.properties", "read";
};

Adjusting Java Memory Allocation

In order for servlets like GeoNetwork and GeoServer to run smoothly, you'll often need to make some adjustments to the memory allocation of the java instance that runs Tomcat. You can do this in a whole bunch of different places, since "Starting Up Tomcat" really means running a whole string of scripts. I made the adjustment by editing /etc/default/tomcat6.

Uncomment and edit the following line by adding what I've put in bold:

JAVA_OPTS="-Djava.awt.headless=true -Xms256M -Xmx1024M -XX:MaxPermSize=256m -XX:PermSize=128m"