TDS Tutorial: Getting Started

Installing Java & Tomcat

System requirements

• Sun Java 1.5 or above, (we recommend the latest version of Java 1.6)
• Apache Tomcat 5.5 or above, (we recommend the latest version of Tomcat 6.0)

Note: while there are different distributors of Java and servlet containers, Unidata develops, uses and tests the THREDDS Data Server using Sun Java and the Apache Tomcat servlet container.

Installing Java

HOW TO INSTRUCTIONS

Installing the Sun JDK requires three steps:

1. Download Java from Sun
2. Install Java
3. Set the $JAVA_HOME environmental variable

1. Download current Java SE Developer Kit (JDK) from Sun.
• We will be using the Linux x64-bit, non-rpm, self-extracting file for this workshop:

jdk-6u10-linux-x64.bin

2. Install the JDK as per the Sun installation instructions.
• Copy the self-extracting file to the installation directory (our home directory is the installation directory in this example):

-bash-3.2$ cp jdk-6u10-linux-x64.bin ~
-bash-3.2$ cd 

• If needed, change the permissions on the file to be executable:

-bash-3.2$ ls -l jdk-6u10-linux-x64.bin
-rw-r--r--  1 thredds Unidata 72753411 2008-10-02 16:39 jdk-6u10-linux-x64.bin

-bash-3.2$ chmod 755 jdk-6u10-linux-x64.bin

-bash-3.2$ ls -l jdk-6u10-linux-x64.bin
-rwxr-xr-x 1 thredds Unidata 72753411 2008-10-02 16:39 jdk-6u10-linux-x64.bin

• Run self-extracting file and agree to the terms of the code license:

-bash-3.2$ ./jdk-6u10-linux-x64.bin

(If you are prompted to register your Java installation, ignore it.)

3. Set the $JAVA_HOME environment variable.

-bash-3.2$ export JAVA_HOME=/home/thredds/jdk1.6.0_10

-bash-3.2$ echo $JAVA_HOME
/home/thredds/jdk1.6.0_10

Troubleshooting:

• Make sure you have the needed permissions to perform the installation.
• Check to make sure the JDK self-extracting file has the correct permissions and is executable.
• Depending on your OS (e.g., Solaris), you may need install both the 32-bit and 64-bit self-extracting files.

Note: the latest version of the JDK 1.6 has already been installed on your workshop computer at /opt/jdk

Installing Tomcat

HOW TO INSTRUCTIONS

Installing Tomcat requires three steps:

1. Download Tomcat
2. Install Tomcat
3. Set the $TOMCAT_HOME environmental variable

1. Download current version of the Tomcat servlet container.
• We will be using the core binary tar.gz file for this workshop:

apache-tomcat-6.0.18.tar.gz

2. Install Tomcat as per the Apache Tomcat installation instructions.
• Copy the binary tar.gz file to the installation directory (our home directory is the installation directory in this example):

-bash-3.2$ cp apache-tomcat-6.0.18.tar.gz ~
-bash-3.2$ cd 

• Unpack the archive to create Tomcat directory:

-bash-3.2$ tar xvzf apache-tomcat-6.0.18.tar.gz

-bash-3.2$ ls -ld apache-tomcat*
drwxr-xr-x  9 thredds Unidata 4096 2008-10-17 16:00 apache-tomcat-6.0.18
-rw-r--r-- 1 thredds Unidata 6142197 2008-07-30 03:51 apache-tomcat-6.0.18.tar.gz

3. Set the $TOMCAT_HOME environment variable.

-bash-3.2$ export TOMCAT_HOME=/home/thredds/apache-tomcat-6.0.18

-bash-3.2$ echo $TOMCAT_HOME
/home/thredds/apache-tomcat-6.0.18

Troubleshooting:

• Make sure you have the needed permissions to perform the installation.

Note: Tomcat has already been installed on your workshop computer at /opt/apache-tomcat-6.0.18

Tomcat directory structure quick tour

Exploring $TOMCAT_HOME

Move into the new Tomcat directory and have a look at the directory structure:

-bash-3.2$ cd apache-tomcat-6.0.18/
-bash-3.2$ ls -l 
total 88
drwxr-xr-x 2 thredds Unidata  4096 2008-11-06 16:45 bin
drwxr-xr-x 2 thredds Unidata  4096 2008-11-06 16:52 conf
drwxr-xr-x 2 thredds Unidata  4096 2008-11-06 16:45 lib
drwxr-xr-x 2 thredds Unidata  4096 2008-11-06 16:47 logs
drwxr-xr-x 2 thredds Unidata  4096 2008-11-06 16:45 temp
drwxr-xr-x 7 thredds Unidata  4096 2008-07-21 18:01 webapps
drwxr-xr-x 3 thredds Unidata  4096 2008-11-06 16:47 work
-rw-r--r-- 1 thredds Unidata 37951 2008-07-21 18:01 LICENSE
-rw-r--r-- 1 thredds Unidata   556 2008-07-21 18:01 NOTICE
-rw-r--r-- 1 thredds Unidata  7317 2008-07-21 18:01 RELEASE-NOTES
-rw-r--r-- 1 thredds Unidata  6587 2008-07-21 18:01 RUNNING.txt

Noteworthy directories

bin/ - Startup, shutdown, and other scripts.

• The *.sh files (for Unix systems) are functional duplicates of the *.bat files (for Windows systems).
• We will be examining in further detail:
• startup.sh
• shutdown.sh

conf/ - Tomcat configuration files.

• Server-wide configuration including logging, authentication and access control, SSL, performance settings, etc.
• We will be examining in further detail:
• server.xml
• tomcat-users.xml

logs/ - Log files are here by default.

• The log files should be your first stop for troubleshooting Tomcat and TDS issues.
• Logs files may contain useful information for assessing the security of your system.
• We will be examining in further detail:
  • catalina.out
  • access.YYYY-MM-DD.log

webapps/ - Web applications directories and WAR files.

• This is where we will be putting the TDS web application.
• Other web applications we will be examining in further detail:
  • manager web application that comes with the Tomcat distribution.

Running Tomcat

Starting & Stopping Tomcat

• Move into the Tomcat bin/ directory and run the startup.sh script:

-bash-3.2$ cd /home/thredds/apache-tomcat-6.0.18/bin
-bash-3.2$ ./startup.sh

• Open a new browser window/tab and go to http://localhost:8080/ to verify Tomcat is running:



• Run the shutdown.sh script to shutdown Tomcat:

-bash-3.2$ ./shutdown.sh

Troubleshooting:

• Check the logs mostly recently generated in $TOMCAT_HOME/logs for clues about why Tomcat failed to start.
• Pay particular attention to what is being reported in Tomcat's main log file: $TOMCAT_HOME/logs/catalina.out.

Set the $JAVA_HOME, $JAVA_OPTS and $CATALINA_HOME environment variables

We are going to modify the startup.sh and shutdown.sh scripts in the Tomcat /bin directory to:

1. allow Tomcat to reference/find the location of $JAVA_HOME and $TOMCAT_HOME (aka $CATALINA_HOME) during startup and shutdown; and
2. increase the amount of memory allocated to the JVM to enhance performance by setting $JAVA_OPTS (-Xms is the initial allocated memory, -Xmx the maximum memory, and -server tells the Hostspot compiler to run the JVM in "server" mode).

• Using your text editor of choice (gedit, vi, emacs, nano, etc.), edit both the startup.sh and shutdown.sh scripts:

-bash-3.2$ vi startup.sh

• Add the following environmental variable declarations immediately after the comments section near the top of each file:

# -----------------------------------------------------------------------------
# Start Script for the CATALINA Server
#
# $Id: startup.sh 562770 2007-08-04 22:13:58Z markt $
# -----------------------------------------------------------------------------


JAVA_HOME="/home/thredds/jdk1.6.0_10"
export JAVA_HOME
JAVA_OPTS="-Xmx1024m -Xms512m -server"
export JAVA_OPTS
CATALINA_HOME="/home/thredds/apache-tomcat-6.0.18"
export CATALINA_HOME


# Better OS/400 detection: see Bugzilla 31132
os400=false
darwin=false
case "`uname`" in
CYGWIN*) cygwin=true;;
OS400*) os400=true;;
Darwin*) darwin=true;;
esac

• Why are we setting $JAVA_HOME and $CATALINA_HOME if we already have set in our environment?

Exercise 1. Install Java and Tomcat

1. Using the steps outlined in the above sections, install the JDK and Tomcat in /home/thredds

Deploying the TDS

HOW TO INSTRUCTIONS

Deploying the TDS requires two steps:

1. Download the TDS
2. Put thredds.war in the webapps/ directory

1. Download the TDS WAR file from Unidata's web site.

thredds.war

2. Put thredds.war in the Tomcat webapps/ directory.

-bash-3.2$ cp thredds.war /home/thredds/apache-tomcat-6.0.18/webapps
-bash-3.2$ cd /home/thredds/apache-tomcat-6.0.18/webapps

-bash-3.2$ ls -l
total 10284
drwxr-xr-x 11 thredds Unidata     4096 2008-11-06 16:45 docs
drwxr-xr-x  5 thredds Unidata     4096 2008-11-06 16:45 examples
drwxr-xr-x  5 thredds Unidata     4096 2008-11-06 16:45 host-manager
drwxr-xr-x  5 thredds Unidata     4096 2008-11-06 16:45 manager
drwxr-xr-x  3 thredds Unidata     4096 2008-11-06 16:45 ROOT
-rw-r--r--  1 thredds Unidata 10491917 2008-11-06 17:08 thredds.war

About WAR files:

• WAR is short for Web ARchive
• If configured Tomcat will automatically unpack the WAR distribution into directory of the same name upon deployment
• Note: the unpacked directory is overwritten each time a new WAR file is deployed.
• If there is an error in the deployment it will report in $TOMCAT_HOME/logs/catalina.out.
3. Confirm the TDS has been deployed.
• Start Tomcat and confirm the thredds.war file was unpacked in the webapps/ directory:

-bash-3.2$ cd /home/thredds/apache-tomcat-6.0.18
-bash-3.2$ bin/startup.sh

-bash-3.2$ ls -l webapps
total 10288
drwxr-xr-x 11 thredds Unidata     4096 2008-11-06 16:45 docs
drwxr-xr-x  5 thredds Unidata     4096 2008-11-06 16:45 examples
drwxr-xr-x  5 thredds Unidata     4096 2008-11-06 16:45 host-manager
drwxr-xr-x  5 thredds Unidata     4096 2008-11-06 16:45 manager
drwxr-xr-x  3 thredds Unidata     4096 2008-11-06 16:45 ROOT
drwxr-xr-x  7 thredds Unidata     4096 2008-11-06 17:15 thredds
-rw-r--r--  1 thredds Unidata 10491917 2008-11-06 17:08 thredds.war

• Go to http://localhost:8080/thredds/ in your browser to verify the TDS has been deployed:

Exercise 2. Deploy your own instance of the THREDDS Data Server

1. Deploy the TDS in your newly-installed Tomcat.
2. Once deployed, browse the test catalogs & datasets that come with the distribution.

Exercise 3. Implement a shortcut: use setenv.sh to declare $JAVA_HOME, $JAVA_OPTS and $CATALINA_HOME

1. Stop Tomcat and move into the Tomcat bin/ directory:

-bash-3.2$ cd /home/thredds/apache-tomcat-6.0.18/bin
-bash-3.2$ ./shutdown.sh

2. Using your favorite text editor, create a new file called setenv.sh:

-bash-3.2$ vi setenv.sh

3. Add the following $JAVA_HOME, $JAVA_OPTS and $CATALINA_HOME environment variable information to the new file:

#!/bin/sh
#
# ENVARS for Tomcat and TDS environment
#
JAVA_HOME="/home/thredds/jdk1.6.0_10"
export JAVA_HOME
JAVA_OPTS="-Xmx1024m -Xms512m -server"
export JAVA_OPTS
CATALINA_HOME="/home/thredds/apache-tomcat-6.0.18"
export CATALINA_HOME

4. Edit the Tomcat startup.sh and shutdown.sh scripts to remove $JAVA_HOME, $JAVA_OPTS and $CATALINA_HOME environment variable information you added previously.
5. Restart Tomcat and examine the output generated to the terminal window by the startup script:

-bash-3.2$ ./startup.sh
Using CATALINA_BASE:   /home/thredds/apache-tomcat-6.0.18
Using CATALINA_HOME:   /home/thredds/apache-tomcat-6.0.18
Using CATALINA_TMPDIR: /home/thredds/apache-tomcat-6.0.18/temp
Using JRE_HOME:       /home/thredds/jdk1.6.0_10

• Did you notice any difference in the output?
• Is this what you expected to see?
• What allows us to use this shortcut?   Hint: have a look at the $TOMCAT_HOME/bin/catalina.sh file:

-bash-3.2$ less catalina.sh

Exercise 4. Look at the log files

1. Look at the different types of log files being generated in $TOMCAT_HOME/logs.
• Move into $TOMCAT_HOME/logs and see the type of information that is being logged:

-bash-3.2$ cd /home/thredds/apache-tomcat-6.0.18/logs
-bash-3.2$ ls -l
total 28
-rw-r--r-- 1 thredds Unidata     0 2008-11-06 16:47 admin.2008-11-06.log
-rw-r--r-- 1 thredds Unidata 10050 2008-11-06 20:16 catalina.2008-11-06.log
-rw-r--r-- 1 thredds Unidata 10610 2008-11-06 20:16 catalina.out
-rw-r--r-- 1 thredds Unidata     0 2008-11-06 16:47 host-manager.2008-11-06.log
-rw-r--r-- 1 thredds Unidata  2760 2008-11-06 20:16 localhost.2008-11-06.log
-rw-r--r-- 1 thredds Unidata     0 2008-11-06 16:47 manager.2008-11-06.log

• Do you see a correspondence between some of the web applications in the $TOMCAT_HOME/webapps directory and the naming of certain log files?
• Is there a difference in information being logged to catalina.out verses catalina.2008-11-06.log?
• Are some log files more verbose than others?
2. Examine Tomcat's main log file: catalina.out
• Open another terminal window (hereafter refered to as terminal #2) and run the following command in the new terminal:

-bash-3.2$ tail -f /home/thredds/apache-tomcat-6.0.18/logs/catalina.out

• In your original terminal window, start/stop and start Tomcat and watch what is being logged to catalina.out in the terminal #2 window.
• Is it only errors messages being reported to catalina.out?
• What messages is the TDS logging to catalina.out?

Exercise 5. $TOMCAT_HOME

1. Move into $TOMCAT_HOME and list the directory contents.
• Do notice anything new?

This document is maintained by Unidata and was last updated on November 5, 2008. Send comments to THREDDS support.