Getting Started With the TDS: Local Test Server Setup

What This Section Covers

This section covers basic installation and configuration of Tomcat, Java JDK and the TDS for a local test server:

Getting Started Context

No prior knowledge of Tomcat, Java, or the TDS needed.

Installing Java and Tomcat

System requirements

JDK installation help

Users of GCJ and OS-provided packages (linux) for Java and/or Tomcat may want to reference the THREDDS mailing list for installation help.

While there are different distributors of Java and servlet containers, Unidata develops, uses and tests the THREDDS Data Server using Oracle Java and the Apache Tomcat servlet container.

Installing Java

  1. Download current Java SE Developer Kit (JDK) from Oracle. Use the latest 1.7 version of the JDK.
  2. At the time of this workshop, that is version Java SE 7u72. We will be using the Linux x64-bit tar.gz file:

    jdk-7u72-linux-x64.tar.gz

  3. Install the JDK as per the Oracle installation instructions.
  4. Copy the binary tar.gz file into the installation directory (/opt/tds/ in this example):

    $ pwd
    /opt/tds
    
    $ cp Downloads/jdk-7u72-linux-x64.tar.gz . 
    
    $ ls -l
    drwxr-xr-x 2 tds staff      4096 Oct 21 08:35 Desktop
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Documents
    drwxr-xr-x 2 tds staff      4096 Oct 21 14:51 Downloads
    -rw-r--r-- 1 tds staff 142225987 Oct 21 15:17 jdk-7u72-linux-x64.tar.gz
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Music
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Pictures
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Public
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Templates
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Videos
    

    Unpack the archive file:

    $ tar xvfz jdk-7u72-linux-x64.tar.gz
    

    This will extract the JDK in the installation directory:

    $ ls -l
    drwxr-xr-x 2 tds staff      4096 Oct 21 08:35 Desktop
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Documents
    drwxr-xr-x 2 tds staff      4096 Oct 21 14:51 Downloads
    drwxr-xr-x 8 tds staff      4096 Sep 26 19:52 jdk1.7.0_72
    -rw-r--r-- 1 tds staff 142225987 Oct 21 15:17 jdk-7u72-linux-x64.tar.gz
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Music
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Pictures
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Public
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Templates
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Videos
    

    Troubleshooting

    Depending on your OS you may need install either the 32-bit or 64-bit version of the JDK.

Installing Tomcat

Tomcat on Windows

For more information about installing Tomcat on Windows OS, see the Tomcat setup guide for installation on different platforms.

  1. Download current version of the Tomcat 7 servlet container.
  2. At the time of this workshop, that is version 7.0.56. We will be using the binary tar.gz file:

    apache-tomcat-7.0.56.tar.gz

  3. Install Tomcat as per the Apache Tomcat installation instructions.
  4. Copy the binary tar.gz file into the installation directory (/opt/tds/ in this example):

    $ pwd
    /opt/tds
    
    $ cp Downloads/apache-tomcat-7.0.56.tar.gz  . 
    
    $ ls -l
    -rw-r--r-- 1 tds staff   8894241 Oct 21 15:22 apache-tomcat-7.0.56.tar.gz
    drwxr-xr-x 2 tds staff      4096 Oct 21 08:35 Desktop
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Documents
    drwxr-xr-x 2 tds staff      4096 Oct 21 14:51 Downloads
    drwxr-xr-x 8 tds staff      4096 Sep 26 19:52 jdk1.7.0_72
    -rw-r--r-- 1 tds staff 142225987 Oct 21 15:17 jdk-7u72-linux-x64.tar.gz
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Music
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Pictures
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Public
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Templates
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Videos
    
    

    Unpack the archive file:

    $ tar xvfz apache-tomcat-7.0.56.tar.gz
    

    This will create a Tomcat directory:

    $ ls -l
    drwxr-xr-x 9 tds staff      4096 Oct 21 15:23 apache-tomcat-7.0.56
    -rw-r--r-- 1 tds staff   8894241 Oct 21 15:22 apache-tomcat-7.0.56.tar.gz
    drwxr-xr-x 2 tds staff      4096 Oct 21 08:35 Desktop
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Documents
    drwxr-xr-x 2 tds staff      4096 Oct 21 14:51 Downloads
    drwxr-xr-x 8 tds staff      4096 Sep 26 19:52 jdk1.7.0_72
    -rw-r--r-- 1 tds staff 142225987 Oct 21 15:17 jdk-7u72-linux-x64.tar.gz
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Music
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Pictures
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Public
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Templates
    drwxr-xr-x 2 tds staff      4096 Oct  9 13:34 Videos
    

Tomcat Directory Structure: Quick Tour

Exploring the Tomcat directory structure

  1. Examine the Tomcat directory structure, aka ${tomcat_home}.
  2. Move into ${tomcat_home} and do a long listing:

    $ cd apache-tomcat-7.0.56
    
    $ ls -l
    drwxr-xr-x 2 tds staff  4096 Oct 21 15:23 bin
    drwxr-xr-x 3 tds staff  4096 Oct 21 15:27 conf
    drwxr-xr-x 2 tds staff  4096 Oct 21 15:23 lib
    -rw-r--r-- 1 tds staff 56812 Sep 26 03:15 LICENSE
    drwxr-xr-x 2 tds staff  4096 Oct 21 15:27 logs
    -rw-r--r-- 1 tds staff  1192 Sep 26 03:15 NOTICE
    -rw-r--r-- 1 tds staff  8963 Sep 26 03:15 RELEASE-NOTES
    -rw-r--r-- 1 tds staff 16204 Sep 26 03:15 RUNNING.txt
    drwxr-xr-x 2 tds staff  4096 Oct 21 15:23 temp
    drwxr-xr-x 7 tds staff  4096 Sep 26 03:13 webapps
    drwxr-xr-x 3 tds staff  4096 Oct 21 15:27 work
    
  3. Familiarize yourself with the following important directories.
  4. bin/

    • Contains startup.sh, shutdown.sh and other scripts/programs.
    • The *.sh files (for Unix systems) are functional duplicates of the *.bat files (for Windows systems).

    conf/

    • Server-wide Tomcat configuration.
    • You will modify server.xml and tomcat-users.xml to adjust logging, authentication and access control, enable cryptographic protocols (TSL, SSL, etc).
    • Web applications can override some server-wide settings in their own configuration files (more about that later).

    webapps/

    • Contains web applications directories and WAR files.
    • This is where we will be putting the TDS web application.
    • You will also be using the manager application that comes with Tomcat during this workshop.

    logs/

    • Tomcat log files are here by default.
    • This is one of the directories you will be looking for log files (the TDS logs elsewhere by default).
    • The log files should be your first stop for troubleshooting Tomcat and TDS issues. (Hint, hint.)
    • Logs files may contain useful information for assessing the security of your system.
    • You will become very familiar with the Tomcat-generated catalina.out, catalina.yyyy-mm-dd.log and localhost_access_log.yyyy-mm-dd.log files by the end of this workshop.

Running Tomcat

Starting & stopping Tomcat

  1. Tomcat isn't currently running so we need to start it up.
  2. Run the startup.sh script in the Tomcat bin/ directory:

    $ pwd
    /opt/tds/apache-tomcat-7.0.56
    
    $ bin/startup.sh
    Using CATALINA_BASE:   /opt/tds/apache-tomcat-7.0.56
    Using CATALINA_HOME:   /opt/tds/apache-tomcat-7.0.56
    Using CATALINA_TMPDIR: /opt/tds/apache-tomcat-7.0.56/temp
    Using JRE_HOME:        /usr
    Using CLASSPATH:       /opt/tds/apache-tomcat-7.0.56/bin/bootstrap.jar:/opt/tds/apache-tomcat-7.0.56/bin/tomcat-juli.jar
    Tomcat started.
    
  3. Verify Tomcat is running.
  4. Look and see if you have a Tomcat process running:

    $ ps -ef | grep tomcat
    tds       2983     1  1 14:40 pts/3    00:00:04 /usr/bin/java -Djava.util.logging.config.file=/opt/tds/apache-tomcat-7.0.56/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djava.endorsed.dirs=/opt/tds/apache-tomcat-7.0.56/endorsed -classpath /opt/tds/apache-tomcat-7.0.56/bin/bootstrap.jar:/opt/tds/apache-tomcat-7.0.56/bin/tomcat-juli.jar -Dcatalina.base=/opt/tds/apache-tomcat-7.0.56 -Dcatalina.home=/opt/tds/apache-tomcat-7.0.56 -Djava.io.tmpdir=/opt/tds/apache-tomcat-7.0.56/temp org.apache.catalina.startup.Bootstrap start
    tds       3436  1791  0 14:44 pts/3    00:00:00 grep tomcat
    

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

    Tomcat Default Home Page

  5. See if you can shutdown Tomcat.
  6. Run the shutdown.sh script in the Tomcat bin/ directory:

    $ bin/shutdown.sh
    Using CATALINA_BASE:   /opt/tds/apache-tomcat-7.0.56
    Using CATALINA_HOME:   /opt/tds/apache-tomcat-7.0.56
    Using CATALINA_TMPDIR: /opt/tds/apache-tomcat-7.0.56/temp
    Using JRE_HOME:        /usr
    Using CLASSPATH:       /opt/tds/apache-tomcat-7.0.56/bin/bootstrap.jar:/opt/tds/apache-tomcat-7.0.56/bin/tomcat-juli.jar
    
    $ ps -ef | grep tomcat
    tds       6391  1791  0 15:03 pts/3    00:00:00 grep tomcat
    

Which Java is Tomcat currently using? (Hint: what was sent to STDOUT when running the startup.sh and shutdown.sh?)

Troubleshooting

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

Setting $JAVA_HOME, $JAVA_OPTS and $CATALINA_BASE

Tomcat on Windows

If you're running Tomcat on an instance of Windows OS, you will want to create a setenv.bat file.

We are going to create a file called setenv.sh in the Tomcat bin/ directory to:

  1. Create the setenv.sh file.
  2. Using your favorite text editor (gedit, vi, emacs, etc.), create a new file called setenv.sh in the Tomcat bin/ directory:

    $ pwd
    /opt/tds/apache-tomcat-7.0.56
    
    $ cd bin
    $ vi setenv.sh
    

    Add the following information and save your setenv.sh file:

    #!/bin/sh
    #
    # ENVARS for Tomcat and TDS environment
    #
    JAVA_HOME="/opt/tds/jdk1.7.0_72"
    export JAVA_HOME
    
    JAVA_OPTS="-Xmx4096m -Xms512m -server -Djava.awt.headless=true -Dtds.content.root.path=/opt/tds/apache-tomcat-7.0.56/content -Djava.util.prefs.systemRoot=$CATALINA_BASE/content/thredds/javaUtilPrefs"
    export JAVA_OPTS
    
    CATALINA_BASE="/opt/tds/apache-tomcat-7.0.56"
    export CATALINA_BASE
    

    Settings

    Whenever possible, Unidata recommends -Xmx1500m for 32-bit systems, and-Xmx4096m (or more) for 64-bit systems.

    Depending on your operating system, you may want to further configure the JVM options to improve performance.

    The parameters we pass to $JAVA_OPTS:

    • -Xms is the initial and minimum allocated memory of the JVM (for performance).
    • -Xmx the maximum allocated memory of the JVM (for performance).
    • -server tells the Hostspot compiler to run the JVM in "server" mode (for performance).
    • -Djava.awt.headless=true is needed to prevent graphics rendering code from assuming a graphics console exists. Without this, the TDS Web Map Service (WMS) code will crash the server in some circumstances.
    • -Dtds.content.root.path=/opt/tds/apache-tomcat-7.0.56/content tells the TDS where to create a directory called content in which it will store/reference TDS configuration and log files.
    • Looking Ahead

      You will learn more about the TDS Web Map Service later on in this workshop.

      -Djava.util.prefs.systemRoot= $CATALINA_BASE/content/thredds/javaUtilPrefs allows the java.util.prefs of the TDS Web Map Service to write system preferences to a location that is writable by the Tomcat user.
    $ pwd
    /opt/tds/apache-tomcat-7.0.56/bin
    
    $ ls -l
    -rw-r--r-- 1 tds staff  28051 Sep 26 03:13 bootstrap.jar
    -rw-r--r-- 1 tds staff  13007 Sep 26 03:13 catalina.bat
    -rwxr-xr-x 1 tds staff  20779 Sep 26 03:13 catalina.sh
    -rw-r--r-- 1 tds staff   2121 Sep 26 03:15 catalina-tasks.xml
    -rw-r--r-- 1 tds staff  24283 Sep 26 03:13 commons-daemon.jar
    -rw-r--r-- 1 tds staff 204944 Sep 26 03:13 commons-daemon-native.tar.gz
    -rw-r--r-- 1 tds staff   2040 Sep 26 03:13 configtest.bat
    -rwxr-xr-x 1 tds staff   1922 Sep 26 03:13 configtest.sh
    -rwxr-xr-x 1 tds staff   7888 Sep 26 03:13 daemon.sh
    -rw-r--r-- 1 tds staff   2091 Sep 26 03:13 digest.bat
    -rwxr-xr-x 1 tds staff   1965 Sep 26 03:13 digest.sh
    -rw-r--r-- 1 tds staff   3430 Sep 26 03:13 setclasspath.bat
    -rwxr-xr-x 1 tds staff   3547 Sep 26 03:13 setclasspath.sh
    -rw-r--r-- 1 tds staff    390 Oct 22 15:30 setenv.sh
    -rw-r--r-- 1 tds staff   2020 Sep 26 03:13 shutdown.bat
    -rwxr-xr-x 1 tds staff   1902 Sep 26 03:13 shutdown.sh
    -rw-r--r-- 1 tds staff   2022 Sep 26 03:13 startup.bat
    -rwxr-xr-x 1 tds staff   1904 Sep 26 03:13 startup.sh
    -rw-r--r-- 1 tds staff  38195 Sep 26 03:13 tomcat-juli.jar
    -rw-r--r-- 1 tds staff 387417 Sep 26 03:13 tomcat-native.tar.gz
    -rw-r--r-- 1 tds staff   4021 Sep 26 03:13 tool-wrapper.bat
    -rwxr-xr-x 1 tds staff   5024 Sep 26 03:13 tool-wrapper.sh
    -rw-r--r-- 1 tds staff   2026 Sep 26 03:13 version.bat
    -rwxr-xr-x 1 tds staff   1908 Sep 26 03:13 version.sh
    
  3. Implement your changes by restarting Tomcat.
  4. Restart Tomcat and examine the output generated to the terminal window by the startup script:

    $ ./startup.sh
    Using CATALINA_BASE:   /opt/tds/apache-tomcat-7.0.56
    Using CATALINA_HOME:   /opt/tds/apache-tomcat-7.0.56
    Using CATALINA_TMPDIR: /opt/tds/apache-tomcat-7.0.56/temp
    Using JRE_HOME:        /opt/tds/jdk1.7.0_72
    Using CLASSPATH:       /opt/tds/apache-tomcat-7.0.56/bin/bootstrap.jar:/opt/tds/apache-tomcat-7.0.56/bin/tomcat-juli.jar
    Tomcat started.
    

    Did you notice any difference in the what is being reported to STDOUT during startup?

    Take a look at the running Tomcat process to see the new $JAVA_OPTS settings:

    $ ps -ef | grep tomcat
    tds       7242     1  2 15:33 pts/3    00:00:05 /opt/tds/jdk1.7.0_72/bin/java -Djava.util.logging.config.file=/opt/tds/apache-tomcat-7.0.56/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Xmx4096m -Xms512m -server -Djava.awt.headless=true -Dtds.content.root.path=/opt/tds/apache-tomcat-7.0.56/content -Djava.util.prefs.systemRoot=/opt/tds/apache-tomcat-7.0.56/content/thredds/javaUtilPrefs -Djava.endorsed.dirs=/opt/tds/apache-tomcat-7.0.56/endorsed -classpath /opt/tds/apache-tomcat-7.0.56/bin/bootstrap.jar:/opt/tds/apache-tomcat-7.0.56/bin/tomcat-juli.jar -Dcatalina.base=/opt/tds/apache-tomcat-7.0.56 -Dcatalina.home=/opt/tds/apache-tomcat-7.0.56 -Djava.io.tmpdir=/opt/tds/apache-tomcat-7.0.56/temp org.apache.catalina.startup.Bootstrap start
    tds       7291  1791  0 15:36 pts/3    00:00:00 grep tomcat
    

    Environment Variables

    For more information on the environment variable prerequisites used by Tomcat, consult ${tomcat_home}/bin/catalina.sh (or catalina.bat) file.

    What allows us to create the setenv.sh file and have its contents read? (Hint: have a look at the catalina.sh file in the Tomcat bin/ directory at lines 24 and 133).

    Troubleshooting

    • Do not forget include the 'm' in your -Xms and -Xmx settings.
    • You may have allocated too much memory for the JVM settings if Tomcat fails to start and you get the following error reported in the Tomcat log catalina.out:
    • Error occurred during initialization of VM
      Could not reserve enough space for object heap
      
    • Likewise, if there is an error with your JVM memory allocation syntax in the setenv.sh file, it will be reported to catalina.out:
    • Error occurred during initialization of VM
      Incompatible minimum and maximum heap sizes specified
      
    • If you intend to use WMS and see something like the following in reported in catalina.out:
    • May 25, 2014 6:28:22 PM java.util.prefs.FileSystemPreferences syncWorld
      WARNING: Couldn't flush system prefs: java.util.prefs.BackingStoreException: /etc/.java/.systemPrefs/org create failed.
      

      You will need to set the java.util.prefs.systemRoot system property in $JAVA_OPTS to a location that is writable by the user that Tomcat, e.g.:

      #!/bin/sh
      #
      # ENVARS for Tomcat and TDS environment
      #
      JAVA_HOME="/opt/tds/jdk1.7.0_72"
      export JAVA_HOME
      
      JAVA_OPTS="-Xmx4096m -Xms512m -server -Djava.awt.headless=true -Dtds.content.root.path=/opt/tds/apache-tomcat-7.0.56/content -Djava.util.prefs.systemRoot=$CATALINA_BASE/content/thredds/javaUtilPrefs"
      export JAVA_OPTS
      
      CATALINA_BASE="/opt/tds/apache-tomcat-7.0.56"
      export CATALINA_BASE
      

Tomcat Log Files

Tomcat logs/

  1. Look at the different types of log files being generated in the Tomcat logs/ directory.
  2. Move into the logs/ directory to see the type of information being logged:

    $ pwd
    /opt/tds/apache-tomcat-7.0.56/bin
    
    $ cd ../logs
    
    $ ls -l
    -rw-r--r-- 1 tds staff  7234 Oct 22 15:33 catalina.2014-10-22.log
    -rw-r--r-- 1 tds staff 11331 Oct 22 15:33 catalina.out
    -rw-r--r-- 1 tds staff     0 Oct 22 14:40 host-manager.2014-10-22.log
    -rw-r--r-- 1 tds staff  1122 Oct 22 15:33 localhost.2014-10-22.log
    -rw-r--r-- 1 tds staff     0 Oct 22 14:40 localhost_access_log.2014-10-22.txt
    -rw-r--r-- 1 tds staff     0 Oct 22 14:40 manager.2014-10-22.log
    

    Do you see a correspondence between some of the web applications in the Tomcat webapps/ directory and the naming of certain log files?

    Is there a difference in the information being logged to catalina.out versus catalina.yyyy-mm-dd.log?

    Are some log files more verbose than others?

  3. Examining catalina.out.
  4. Open another terminal window (hereafter referred to as terminal #2) and run the following command in the new terminal:

    $ tail -f /opt/tds/apache-tomcat-7.0.56/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?

Things to know about catalina.out

catalina.out

The Tomcat Users mailing list has seen a lot of traffic dedicated to catalina.out logging and rotation.

Tomcat (Server-Level) Configuration Files

About server.xml

Keep in mind

Tomcat's configuration files, including server.xml can be found in in the Tomcat conf/ directory.

Important elements in server.xml

  1. Examine the Elements in server.xml.
  2. Move into the Tomcat conf/ directory and examine the server.xml file:

    $ pwd
    /opt/tds/apache-tomcat-7.0.56/logs
    
    $ cd ../conf
    
    $ less server.xml
    

    Reference the table below to see how the server.xml elements relate to configuring TDS (mouse-over the element for a description):

    Tag Name Instances How it relates to the TDS
    <Server>Description: The Server element represents the entire Catalina servlet container as a whole. It is the single outermost element in server.xml 1...1 Not modified unless you want to change the port number Tomcat listens for a SHUTDOWN command. (Enabled by default.)
    <GlobalNamingResources>Description: The GlobalNamingResources element defines the global Java Naming and Directory Interface (JNDI) resources for the Server. 0...* Needed to contain the UserDatabase that corresponds to the UserDatabaseRealm used to authenticate users. (Enabled by default.)
    <Resource>Description: The Resource element represents a static resource from which classes will be loaded and static files will be served. 0...* Editable user database (tomcat-users.xml) used by UserDatabaseRealm to authenticate users. (UserDatabaseRealm Resource enabled by default.)
    <Service>Description: The Service element represents the combination of one or more Connector components that share a single Engine component for processing incoming requests. The top Tomcat service is named Catalina (hence the log file name of catalina.out). 1...* Not modified unless you wish to establish more than one service. (Catalina Service enabled by default.)
    <Connector>Description: The Connector element forward requests to the Engine using a specific protocol and returns the results to the requesting client. 1...* Used to establish HTTP and SSL connections. Also will communicate with an web server for proxying requests. (HTTP connector enabled by default on port 8080.)
    <Engine>Description: The Engine element represents the entire request processing machinery associated with a particular Catalina Service. 1...1 Not modified unless you specify a Host other than localhost. (Enabled by default.)
    <Realm>Description: The Realm element represents a "database" of usernames, passwords, and roles (groups) assigned to those users. 0...* The UserDatabaseRealm uses the UserDatabase configured in the global JNDI Resource. (UserDatabaseRealm enabled by default.)
    <Valve>Description: The Valve element represents a component that will be inserted into the request processing pipeline for the associated containing element. 0...* The RemoteAddrValve is used to filter access to the TDS based on IP address. (NOT enabled by default. You will need to add this if you want to use IP Filtering.)
    <Host>Description: The Host element represents a virtual host. 1...* Not modified unless you specify a Host other than localhost. (localhost enabled by default.)
    <Realm>Description: The Realm element represents a "database" of usernames, passwords, and roles (groups) assigned to those users. 0...* We use the MemoryRealm to configuring Tomcat to use digested passwords. (NOT enabled by default. You will need to add this if you want to use digested passwords.)
    <Valve>Description: The Valve element represents a component that will be inserted into the request processing pipeline for the associated containing element. 0...* We modify the AccessLogValve to customize the access logs generated by Tomcat. (Enabled by default.)

About tomcat-users.xml

Important elements in tomcat-users.xml

  1. Examine the Elements in tomcat-users.xml.
  2. Open the tomcat-users.xml file:

    $ pwd
    /opt/tds/apache-tomcat-7.0.56/conf
    
    $ less tomcat-users.xml
    

    Reference the table below to see how the tomcat-users.xml elements relate to configuring TDS (mouse-over the element for a description):

    Tag Name Instances How it relates to the TDS
    <tomcat-users>Description: The tomcat-users element represents the single outermost element in tomcat-users.xml 1...1 Not modified. (The only tag you get by default.)
    <role>Description: The role element defines one role or group a user can belong to. 1...* You will have at least two of these: one for the Tomcat manager application and one for the TDS. (You will need to add if you want to enable role-based authentication.)
    <user>Description: The user element represents one valid user. 1...* You will need to create an entry for each user who needs access to the Tomcat manager application and/or the restricted areas of the TDS. (You will need to add if you want to enable user authentication.)

Deploying the TDS

About WAR files

Downloading & deploying thredds.war

Upgrading the TDS

A maintenance checklist and contains helpful information about upgrading the TDS. New features and configuration changes made between TDS versions are listed for each release.

  1. Download the TDS WAR file from Unidata's web site.
  2. We will be using the current TDS 4.5.4 (snapshot) version for this workshop:

    thredds.war

  3. Deploy the TDS in Tomcat.
  4. Put thredds.war in the Tomcat webapps/ directory:

    pwd
    /opt/tds/apache-tomcat-7.0.56/conf
    
    $ cd ../webapps
    
    $ cp /opt/tds/Downloads/thredds.war .
    
    $ ls -l
    drwxr-xr-x 14 tds staff     4096 Oct 21 15:23 docs
    drwxr-xr-x  7 tds staff     4096 Oct 21 15:23 examples
    drwxr-xr-x  5 tds staff     4096 Oct 21 15:23 host-manager
    drwxr-xr-x  5 tds staff     4096 Oct 21 15:23 manager
    drwxr-xr-x  3 tds staff     4096 Oct 21 15:23 ROOT
    -rw-r--r--  1 tds staff 57156363 Oct 22 16:24 thredds.war
    
  5. Confirm the TDS has been deployed.
  6. If Tomcat is already running, wait a couple of seconds after placing the WAR file in the Tomcat webapps/ and then verify the thredds.war file was unpacked:

    $ ls -l
    drwxr-xr-x 14 tds staff     4096 Oct 21 15:23 docs
    drwxr-xr-x  7 tds staff     4096 Oct 21 15:23 examples
    drwxr-xr-x  5 tds staff     4096 Oct 21 15:23 host-manager
    drwxr-xr-x  5 tds staff     4096 Oct 21 15:23 manager
    drwxr-xr-x  3 tds staff     4096 Oct 21 15:23 ROOT
    drwxr-xr-x  8 tds staff     4096 Oct 22 16:24 thredds
    -rw-r--r--  1 tds staff 57156363 Oct 22 16:24 thredds.war
    

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

    THREDDS Distribution Catalog

  7. Confirm the creation of the TDS content/ directory.
  8. Move into ${tomcat_home} and do a long listing:

    $ pwd
    /opt/tds/apache-tomcat-7.0.56/webapps
    
    $ cd .. 
    
    $ ls -l
    drwxr-xr-x 2 tds staff  4096 Oct 22 15:39 bin
    drwxr-xr-x 3 tds staff  4096 Oct 21 15:27 conf
    drwxr-xr-x 3 tds staff  4096 Oct 22 16:24 content
    drwxr-xr-x 2 tds staff  4096 Oct 21 15:23 lib
    -rw-r--r-- 1 tds staff 56812 Sep 26 03:15 LICENSE
    drwxr-xr-x 2 tds staff  4096 Oct 22 14:40 logs
    -rw-r--r-- 1 tds staff  1192 Sep 26 03:15 NOTICE
    -rw-r--r-- 1 tds staff  8963 Sep 26 03:15 RELEASE-NOTES
    -rw-r--r-- 1 tds staff 16204 Sep 26 03:15 RUNNING.txt
    drwxr-xr-x 2 tds staff  4096 Oct 22 16:24 temp
    drwxr-xr-x 8 tds staff  4096 Oct 22 16:24 webapps
    drwxr-xr-x 3 tds staff  4096 Oct 21 15:27 work
    

    Troubleshooting

    • Any error in the TDS deployment will be reported in the catalina.out file of the Tomcat logs/ directory.
    • Be sure you have downloaded and deployed the correct version of the TDS (version 4.3.18 snapshot for this workshop). The TDS version number will appear in the blue bar at the bottom of TDS catalog pages.

Tomcat manager Application

About the manager application

More about manager

For more information about the Tomcat manager application, see the Tomcat Manager App HOW-TO documentation.

Accessing the Tomcat manager application

Changes to the manager application

The manager application URLs and roles has been re-structured. See the Tomcat Migration guide for more information.

Attempt to access the Tomcat manager application in your browser: http://localhost:8080/manager/html/. You will be prompted to login via BASIC authentication, which will end in failure since we do not yet have permission to access the manager application:

Manager app with 401 response code

Based on what we know about Tomcat configuration, which file in the Tomcat conf/ directory should we edit to grant ourselves access to the manager application?

Keep in mind

Changes to tomcat-users.xml do not take effect until Tomcat is restarted.

Granting access to the manager application

  1. Modify tomcat-users.xml to add role and user elements.
  2. Using your favorite editor, open ${tomcat_home}/conf/tomcat-users.xml:

    $ vi tomcat-users.xml
    

    Between the <tomcat-users> tags, add a role element and specify the rolename attribute as manager:

    <tomcat-users>
        <role rolename="manager-gui"/>
    </tomcat-users>
    

    Now add a new user by adding a user element. Create a username and password for the new user and specify manager-gui as one of the roles (in this example we are creating a user called 'admin' with a corresponding password of 'secret'):

    <tomcat-users>
        <role rolename="manager-gui"/>
        <user username="admin" password="secret" roles="manager-gui"/>   
    </tomcat-users>
    
  3. Restart Tomcat and log into the manager application.
  4. Thinking ahead

    To gain access to restricted parts of the TDS, you will perform the same steps you used to grant yourself access to the manager application.

    Attempt to access the manager application again (http://localhost:8080/manager/html/), this time logging in using the name and password specified in tomcat-users.xml:

    Tomcat manager application

    Voilà! You should have access to the manager application.

    Troubleshooting

    • Check the XML syntax in tomcat-users.xml to make sure it is well-formed and without error.
    • Did you restart Tomcat after you made your changes to tomcat-users.xml?
    • Any errors will be reported in the Tomcat logs/catalina.out file.

Deploying the TDS using the manager application

  1. Use the manager application to undeploy the TDS.
  2. Find the TDS in the list of web application on the Applications page. Stop and then Undeploy the TDS:

    Undeploy the TDS

    List the contents of the Tomcat webapps/ directory to verify that both thredds.war and the unpacked thredds/ directory have been removed:

    $ pwd
    /opt/tds/apache-tomcat-7.0.56/conf
    
    $ cd ../webapps
    
    $ ls -l
    drwxr-xr-x 14 tds staff 4096 Oct 21 15:23 docs
    drwxr-xr-x  7 tds staff 4096 Oct 21 15:23 examples
    drwxr-xr-x  5 tds staff 4096 Oct 21 15:23 host-manager
    drwxr-xr-x  5 tds staff 4096 Oct 21 15:23 manager
    drwxr-xr-x  3 tds staff 4096 Oct 21 15:23 ROOT
    
  3. Deploy the TDS using the manager application.
  4. Upload the TDS WAR file using the Deploy section of the manager application:

    Deploy the TDS

    Confirm the deployment went as planned by accessing the TDS using your browser: http://localhost:8080/thredds/

Next Steps: Where To Go From Here

You're not finished yet

TDS Monitoring & Debugging Tools

You will need to enable Enable encryption to access a couple of TDS monitoring and debugging tools.