Tomcat - First Steps

(Free Web Tutorial)

by Michael Thomas

Tomcat Home Page

In this tutorial you will install Tomcat, test the install, install your first web app and view the Tomcat documentation.
Note: On the "Tomcat Home Page", you can download the whole site (all content, tutorials & examples) !!!

This tutorial covers: Apache Tomcat 6.0.32 (as of 03/20/2011)

Prerequisites

• Tomcat 6.0 requires JRE 5.0 or higher.
  (For help on obtaining Java's JRE/JDK we have a "Java First Steps" tutorial on the home page of "Free Web Tutorials on Java & Web Technologies" )
• This tutorial has been tested in the following environment:
  Date: 03/20/2011,
  OS: Win 7,
  JDK: jdk1.6.0_21
  
  (Older Tutorial - Date: 05/25/08, OS: Win XPro, JDK: jdk1.6.0_03)

Objectives

• Install Tomcat
• Test your install
• Install your first web app
• View Tomcat's docs.

Version Notes:

• Tomcat 3.x - implements the Servlet 2.2 and JSP 1.1 specifications, requires Java 1.1 (or higher).
• Tomcat 4.x - implements the Servlet 2.3 and JSP 1.2 specifications, requires Java 1.3 (or higher).
• Tomcat 5.x - implements the Servlet 2.4 and JSP 2.0 specifications, requires Java 1.4 (or higher).
• Tomcat 6.x - implements the Servlet 2.5 and JSP 2.1 specifications, requires Java 1.5 (or higher).
  • Version 6.0.32 (check on 03/20/2011)
• Tomcat 7.x - implements the Servlet 3.0 and JSP 2.2 specifications, requires Java 1.6 (or higher).
  • Version 7.0.10, Mar 5 2011

Installation Notes for Win XP

• apache-tomcat-6.0.32.exe - download this file from the Tomcat home page:
  http://tomcat.apache.org/
  • On the left side of the screen under "Download" click "Tomcat 6.x"
  • Sometimes the beta versions are listed first.  Find the first version that doesn't have "-beta" at the end.
  • Find the section "Binary Distributions" section
  • Download notes:
    I suggest saving them to your local and then later installing (RUN). 
    To download the file, right click on the link and choose "Save as Target" to save to your local (do not click "Run" after the download. Click "Close").
  • Download the following files. 
    • Find the sub-section "Core" links.
      • Determine what file to download.  Here are some helpful notes:
        • Option: 32-bit/64-bit Windows Service Installer - This is the one we will use for this tutorial.
        • Option: Zip file download - if you prefer just the zip files this will help you choose between 32bit & 64bit.  Then if you want a Windows Service you will have to create one by hand.
          • Windows XP Pro - 32 bit OS.
          • Windows 7 - 64 bit OS
      • "32-bit/64-bit Windows Service Installer" (~6.8 meg) - this version is designed to be started as a windows service.
        (ex file: apache-tomcat-6.0.29.exe)
        • Versions since this Tutorial:
          • Win Service Installer - apache-tomcat-6.0.32.exe - as of 03/10/2011 check of web site.
          • Win Service Installer - apache-tomcat-7.0.10.exe - as of 03/10/2011 check of web site.
• Upgrade WARNING:  If an older version of Tomcat is installed then uninstall the current Tomcat version first.
  (Note: I have not tried running more than one Tomcat Web App Server on one computer.)
  • Uninstall Tomcat so you can update the version.
    • I suggest that you Stop the Tomcat service first.
      (Ex: Start, Settings, Control Panel, Administrative Tools, Services. Right click on "Apache Tomcat" then click "Stop".)
    • Make a backup copy of the current Tomcat x.x directory.
      (IE: C:\Program Files\Apache Software Foundation\Tomcat 5.5 or C:\Tomcat\Tomcat6.0 )
    • Uninstall Tomcat – Programs, "Apache Tomcat x.x.x", "Uninstall Apache Tomcat x.x.x"
      (Other option:  Control Panel, Add or Remove Programs, then find "Apache Tomcat x.x.x").
      • Next you will be prompted with:
        Remove all files in your Tomcat 5.5 directory? (If you have anything you created that you want to keep, click No)
      • Click "No" - so that you keep all of your work files.  Warning: "Yes" will delete all of them!
      • You should see "Completed".  Click "Close".
• Install Tomcat Core
  • Run the .exe file you downloaded.  (Note: You can run it from any location.)
  • On the Welcome screen click "Next"
  • On the License Agreement screen click "I Agree"
  • Choose Components Screen
    • If not checked, check "Start Menu Items", "Documentation" & "Manager".
    • Optional Items I would also check:
      Check - Host Manager - tomcat host manager administrative web application.
      Check - Examples - install the Servlet and JSP examples web application.
      • You can always delete them later.
        C:\Tomcat\Tomcat6.0\webapps\examples
        C:\Tomcat\Tomcat6.0\webapps\host-manager
        C:\Tomcat\Tomcat6.0\webapps\docs
      • Keep these:
        C:\Tomcat\Tomcat6.0\webapps\manager
        C:\Tomcat\Tomcat6.0\webapps\ROOT
    • Click Next.
  • Configuration
    • HTTP1.1 Connector Port: 8080  (use the default)
      • Note: To change after install: C:\Tomcat\Tomcat6.0\conf\server.xml
        <Connector port="8080" protocol="HTTP/1.1"
        connectionTimeout="20000"
        redirectPort="8443" />
    • Tomcat Administrator Login (option) - WARNING - make sure you enter a user & password or you will not be able to do admin functions unless you modify the XML file: C:\Tomcat\Tomcat6.0\conf\tomcat-users.xml.
      • User Name & Password: admin/admin
        • User Name: admin (commonly used)
        • Password: admin (commonly used for local development only)
      • Roles: admin-gui,manager-gui (default)
      • To change later: (tomcat-users.xml)
        C:\Tomcat\Tomcat6.0\conf\tomcat-users.xml
        Example:
        <tomcat-users>
            <user name="admin" password="admin" roles="admin-gui,manager-gui" />
        </tomcat-users>
  • Java Virtual Machine - install should find the directory.
    • My Default Ex: C:\Program Files\Java\jre6 (Warning: Could use but don't use!)
      (Note: If you have a 64bit OS you need to specify a 64bit JRE or 64bit JDK.)
    • Use the JDK.  Point to the location where your JDK is installed.
      My Ex: C:\java\jdk1.6.0_21
    • Notes: How to change later!
      • Win 7:
        Control Panel, (click "View by:" in upper right corner and select "Small Icons"), System, Advanced System Settings, Environment Variables, System Variables:  ex: JAVA_HOME, C:\java\jdk1.6.0_21
      • Win XP: (need to add....)
  • Choose Install Location Screen
    • Change to: C:\Tomcat\Tomcat6.0 (Notice - no spaces!)
      The default is: C:\Program Files\Apache Software Foundation\Tomcat 6.0
      Note: Because of the spaces in the directory names I suggest using a install location.  It may save you headaches down the road.
    • To change later see the section at the bottom about "Windows Registry"
  • Click "Install"
  • "Completing the Apache Tomcat Setup Wizard" - leave the defaults checked
    • Checked - Run Apache Tomcat
    • Checked - Show Readme
  • Click "Finish"
  • Notes:
    • Release notes are located at:
      C:\Tomcat\Tomcat6.0\webapps\ROOT\RELEASE-NOTES.txt
• Windows Services - Q&A
  I suggest that you get familiar with Starting and Stopping the "Apache Tomcat" service.
  • Services Panel
    Q: How do I get to the "Services" panel?
    A: Win 7: Control Panel, System & Security, Administrative Tools, double click "Services"
    A: Win XP: Control Panel, Administrative Tools, Services
  • Startup Type
    Q: How do I make "Apache Tomcat" automatically startup when the server or PC is rebooted?
    A: Go to the "Services" panel. Right click on "Apache Tomcat", Properties. Startup Type = "Automatic"|
    (Note:  On my development computer, I prefer to leave mine on "Manual" and manually start it.)
  • Start Tomcat
    Q: How do I Start the Tomcat Service?
    A: Go to the "Services" panel. Right click on "Apache Tomcat", click "Start"
  • Stop Tomcat
    Q: How do I Stop the Tomcat Service?
    A: Go to the "Services" panel. Right click on "Apache Tomcat", click "Stop"

Test your Install

• Open up a Browser
• Test the "Tomcat" installation
• Go to:  http://localhost:8080 - If this page doesn't come up you need to revisit the install.  If you still have problems I've seen some Firewalls cause issues.
  Other URL alternatives that may work:
  • http://<your computer name>:8080
  • http://127.0.0.1:8080
• Test your admin account & Password
  • On the left side, under the section called "Administration", click on "Status".
    User name: admin
    Password: <enter your password>
    (If you get the "Server Status" page then you entered the correct user/password.)
• Test the "Tomcat Manager" link
  • Click on "Tomcat Manager"
  • Since you have already authenticated as an "admin" you shouldn't be prompted for a password unless you close your browser.
  • You should see a list of Web Apps.
• Test the webapps that were installed in the installation:
  • http://localhost:8080/docs - Tomcat documentation.
  • Optional Admin Web Apps:
    • http://localhost:8080/manager/html - admin authentication - Tomcat Manager
    • http://localhost:8080/manager/status - admin authentication - Server Status
    • http://localhost:8080/host-manager/html - admin authentication - Tomcat Virtual Host Manager
  • Example Applications  (if you installed them)
    • http://localhost:8080/examples - JSP & Servlet examples
• Server's Web Root
  • Physical file: $CATALINA_HOME/webapps/ROOT/index.html
    URL: http://localhost:8080/index.html

Install a Hello World Web Application

• Hello World Web Application - mytomcat-helloworld.zip
  • Install "mytomcat-helloworld.war"
    • Download this file:  mytomcat-helloworld-war.zip
      (Note: If you downloaded this tutorial to your local you have this file already!)
    • Unzip the file.  There is one file in it called:
      mytomcat-helloworld.war
    • Copy the mytomcat-helloworld.war file to your Tomcat Webapps directory.
      (ex: C:\Tomcat\Tomcat6.0\webapps )
    • Tomcat monitors the "webapps" directory and will extract the .war file's files and start the web application.  If you desire you can go to "Tomcat Manager" and see the new application. 
      You can also look at the new directory and files using Win Explorer at:
      C:\Tomcat\Tomcat6.0\webapps\mytomcat-helloworld
      • Note: If for some reason Tomcat doesn't auto install the .war file then Stop/Start Tomcat.
        If you are updating a WAR file you need to remove the WAR file and remove the directory.  If the directory is not there and Tomcat sees a .war file in the webapps directory it will deploy the WAR file.
  • Test the new Web Application:
    • Go to: http://localhost:8080/mytomcat-helloworld

Install Tomcat's Sample Web Application

• Go to: http://localhost:8080/docs/
• Click the link: "3. First web application"
• Click "Example App" under contents on the left side of the screen.
• Click on the link "here" to download their "Sample Application". (Download link: http://localhost:8080/docs/appdev/sample/sample.war )
  Save to this location: C:\Tomcat\Tomcat6.0\webapps
• Give the Tomcat container a minute and it will automatically extract the WAR file and create a Web Application called "Sample".
• Test your install: http://localhost:8080/sample
  Click on the JSP test link.
  Click on the Servlet test link.

View the "Tomcat Documentation"

• http://localhost:8080 , click "Tomcat Documentation" under Documentation.
  • Click "3) First webapp" - "Application Developers Guide"
    Note:  When you have time, go through all of the items in the "Table Of Contents" expecially the "Example Application".

Finished

• You are finished.

Other notes

• Tomcat
  • Tomcat 5.5\conf\server.xml - Has the web server configuration information like: Port #, etc...
  • Tomcat 5.5\conf\tomcat-users.xml - The tomcat users & passwords including the administrator you created.
• Tomcat Log files
  • C:\Program Files\Apache Software Foundation\Tomcat 5.5\logs
• Terminology
  • WAR - Web ARchive - this contains all of the files in a Web Application.  You can rename the .war file to a .zip file and see the list of files.  You can also use the Java command found in the "bin" directory : jar -xvf sample.war
• Windows Service Info - The standard install will setup the windows service.  Here is additional info if needed.
  • How to Create a Windows Service for Tomcat
    • (under construction - add steps to create a windows service)
    • Prior to Tomcat 6: The safest way to manually install the service is to use the provided service.bat script in the bin directory - if it exists :-).
      Ex: Goto a DOS prompt and CD to the bin directory:
      C:\...>service.bat install
  • Windows Service Properties
    • Tomcat 6
      Name: Apache Tomcat
      Description: Apache Tomcat 6.0.16 Server - http://tomcat.apache.org/
      Path to executable: "C:\Program Files\Apache Software Foundation\Tomcat 6.0\bin\tomcat6.exe" //RS//Tomcat6
    • Tomcat 5
      Name: Apache Tomcat
      Description: Apache Tomcat 6.0.16 Server - http://tomcat.apache.org/
      Path to executable:
      "C:\Program Files\tomcat-5.5.26\bin\tomcat5.exe" //RS//Tomcat5
• Windows Registry (cmd: regedit.exe)
  • Tomcat 6
    • HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Tomcat\6.0
      • Install Path - windows service uses this value!
  • Tomcat 5
    HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Procrun 2.0\Tomcat5

Installation Issue

Tomcat 5.5.26

• Startup.bat error:
  The JAVA_HOME environment variable is not defined correctly
  This environment variable is needed to run this program
  NB: JAVA_HOME should point to a JDK not a JRE
  • Step 1: You must install a Java JDK and not just the JRE.
  • Step 2: Edit the file: <tomcat directory>\bin\setclasspath.bat
    I suggest that you remove the first line. At a minimum it needs to point to a JDK and not a JRE.
    ex remove the line: set JAVA_HOME="E:\Java\jdk1.6.0_20"
  • Step 3: System Environment Variable
    (Ex: Windows Server 2003 R2)
    • Start, Control Panel, System, Advanced, Environment Variables and create/edit a variable called "JAVA_HOME"
      Variable name: JAVA_HOME
      Variable value: "C:\Java\jdk1.6.0_20"  (Note: Go ahead and use the quotes anyway!)
      (Warning: DO NOT use "Program Files" because there has been issues with the "if" command in the batch files with spaces.)
• Windows Service error:
  • Tomcat Resource:
    http://tomcat.apache.org/tomcat-5.5-doc/windows-service-howto.html
  • Tomcat 5 service will not start up (saw with: Tomcat 5.5.26 & Windows Server 2003 R2)
    • Tomcat Logs: (<tomcat dir>\logs) - Several files are created in the Tomcat log directory when the "Apache Tomcat: service is started.
      
      admin.2010-04-27.log
      host-manager.2010-04-27.log
      jakarta_service_20100427.log
      manager.2010-04-27.log
      stderr_20100427.log
      stdout_20100427.log
      catalina.2010-04-27.log
      localhost.2010-04-27.log
    • Error that displays:
      • Window Title: Services
        Error: Windows could not start the Apache Tomcat on Local Computer. For more information, review the System Event log.  If this is a non-Microsoft service, contact the service vendor, and refer to service-specific error code 0
      • Error in System Event log - The Apache Tomcat service terminated with service-specific error 0 (0x0).
        For more information, see Help and Support Center at http://go.microsoft.com/fwlink/events.asp.
      • Tomcat Logs
        <tomcat dir>/logs/jakarta_service_<YYYYMMDD>.log
        [2010-04-26 15:34:36] [986 prunsrv.c] [error] Failed creating java "E:\Java\jdk1.6.0_20"\jre\bin\server\jvm.dll
        [2010-04-26 15:34:36] [1260 prunsrv.c] [error] ServiceStart returned 1
        [2010-04-26 15:34:36] [info] Run service finished.
        [2010-04-26 15:34:36] [info] Procrun finished.
      • Solution: Remove any quotes in the Registry entry.
        HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Procrun 2.0\Tomcat5\Parameters\Java\Jvm
        Caused Error: "E:\Java\jdk1.6.0_20"\jre\bin\server\jvm.dll
        Fixed Error: E:\Java\jdk1.6.0_20\jre\bin\server\jvm.dll
      • Note: It has been my experience to NOT install Java into the default directory of "C:\Program Files\..." because the quotes needed to access the files may cause issues.  Above is an example of that!  So don't use quotes ("") in the JAVA_HOME system variable etc...
        
        System Variable: JAVA_HOME - don't use quotes (" ")
        Variable name: JAVA_HOME
        Variable value: E:\Java\jdk1.6.0_20
      • Other info
        • The following didn't work for me and this file doesn't need to be in the <tomcat>\bin directory for my Tomcat5 service to startup.  I'm including this information because it was so prevalent at forums.
          Copy msvcr711.dll from  <java>\bin directory to <tomcat>\bin directory
    • Debugging "startup.bat"
      • To debug run the "startup.bat" and make sure it starts Tomcat without any errors.
        A DOS window will stay open with the following words at the end:
        - Server startup in 641 ms
      • If the above doesn't happen then use the "echo" and "pause" to debug and figure out what is happening.
    • Start tomcat5.exe in debug mode (see errors at the console).
      • Copy "tomcat5.exe" to another name like "tomcat5_debug.exe".  You can run this from a DOS prompt and see any errors.
        Ex: C:\tomcat-5.5.26\bin\tomcat5_debug.exe //TS//Tomcat5
        (Note: //TS - option to run from a console.)
        If startup is complete you will see as the last 2 lines something like:
        Apr 27, 2010 11:32:37 AM org.apache.catalina.startup.Catalina start
        INFO: Server startup in 937 ms