How to Install Apache Tomcat 7 or 8 (on Windows, Mac OS X, Ubuntu) and Get Started with Java Servlet Programming

This installation and configuration guide is applicable to Tomcat 7 and 8, and possibly the earlier versions.
Take note that Tomcat 8 requires JDK 1.7. It will NOT work with JDK 1.6. If your JDK is below 1.7, upgrade it (See JDK How-To). You can check your JDK version via command "javac -version".

1.  Introduction

1.1  Web Application (Webapp)

A web application (or webapp), unlike standalone application, runs over the Internet. Examples of webapps are google, amazon, ebay, facebook and twitter.
A webapp is typically a 3-tier (or multi-tier) client-server database application run over the Internet as illustrated in the diagram below. It comprises five components:

1. HTTP Server: E.g., Apache HTTP Server, Apache Tomcat Server, Microsoft Internet Information Server (IIS), nginx, Google Web Server (GWS), and others.
2. HTTP Client (or Web Browser): E.g., Internet Explorer (MSIE), FireFox, Chrome, Safari, and others.
3. Database: E.g., Open-source MySQL, Apache Derby, mSQL, SQLite, PostgreSQL, OpenOffice's Base; Commercial Oracle, IBM DB2, SAP SyBase, MS SQL Server, MS Access; and others.
4. Client-Side Programs: could be written in HTML Form, JavaScript, VBScript, Flash, and others.
5. Server-Side Programs: could be written in Java Servlet/JSP, ASP, PHP, Perl, Python, CGI, and others. 

 

 

 The typical use-case is:

1. A user, via a web browser (HTTP client), issues a URL request to an HTTP server to start a webapp.
2. A client-side program (such as an HTML form) is loaded into client's browser.
3. The user fills up the query criteria in the form.
4. The client-side program sends the query parameters to a server-side program.
5. The server-side program receives the query parameters, queries the database and returns the query result to the client.
6. The client-side program displays the query result on the browser.
7. The process repeats.

1.2  Hypertext Transfer Protocol (HTTP)

• HTTP is an application layer protocol runs over TCP/IP. The IP provides support for routing and addressing (via an unique IP address for machines on the Internet); while TCP supports multiplexing via 64K ports from port number 0 to 65535. The default port number assigned to HTTP is TCP port 80.
• HTTP is an asynchronous request-response application-layer protocol. A client sends a request message to the server. The server then returns a response message to the client.
• HTTP is a pull protocol, a client pulls a page from the server (instead of server pushes pages to the clients).
• The syntax of the message is defined in the HTTP specification.

 

 

 

 

1.3  Apache Tomcat HTTP Server

 

Apache Tomcat is a Java-capable HTTP server, which could execute special Java programs known as Java Servlet and Java Server Pages (JSP). It is the official Reference Implementation (RI) for Java Servlets and JavaServer Pages (JSP) technologies. Tomcat is an open-source project, under the "Apache Software Foundation" (which also provides the most use, open-source, industrial-strength Apache HTTP Server). The mother site for Tomcat is http://tomcat.apache.org. Alternatively, you can find tomcat via the Apache mother site @ http://www.apache.org.
Tomcat was originally written by James Duncan Davison (then working in Sun), in 1998, based on an earlier Sun's server called Java Web Server (JWS). It began at version 3.0 after JSWDK 2.1 it replaced. Sun subsequently made Tomcat open-source and gave it to Apache.
The various Tomcat releases are:

1. Tomcat 3.x (1999): RI for Servlet 2.2 and JSP 1.1.
2. Tomcat 4.x (2001): RI for Servlet 2.3 and JSP 1.2.
3. Tomcat 5.x (2002): RI for Servlet 2.4 and JSP 2.0.
4. Tomcat 6.x (2006): RI for Servlet 2.5 and JSP 2.1.
5. Tomcat 7.x (2010): RI for Servlet 3.0, JSP 2.2 and EL 2.2.
6. Tomcat 8.x (2013): RI for Servlet 3.1, JSP 2.3, EL 3.0 and Java WebSocket 1.0.

Tomcat is an HTTP application runs over TCP/IP. In other words, the Tomcat server runs on a specific TCP port in a specific IP address. The default TCP port number for HTTP protocol is 80, which is used for the production HTTP server. For test HTTP server, you can choose any unused port number between 1024 and 65535.

2.  How to Install Tomcat 8 and Get Started with Java Servlet Programming

2.1  STEP 1: Download and Install Tomcat

For Windows

1. Goto http://tomcat.apache.org ⇒ Downloads ⇒ Tomcat 8.0 ⇒ "8.0.{xx}" (where {xx} is the latest upgrade number) ⇒ Binary Distributions ⇒ Core ⇒ "ZIP" package (e.g., "apache-tomcat-8.0.{xx}.zip", about 8 MB).
2. UNZIP into a directory of your choice. DO NOT unzip onto the Desktop (because its path is hard to locate). I suggest using "d:\myProject". Tomcat will be unzipped into directory "d:\myProject\apache-tomcat-8.0.{xx}". For ease of use, we shall shorten and rename this directory to "d:\myProject\tomcat". Take note of Your Tomcat Installed Directory. Hereafter, I shall refer to the Tomcat installed directory as <TOMCAT_HOME> (or <CATALINA_HOME> - "Catalina" is the codename for Tomcat 5 and above).

(Advanced) A better approach is to keep the original directory name, such as apache-tomcat-8.0.{xx}, but create a symlink called tomcat via command "mklink /D tomcat apache-tomcat-8.0.{xx}". Symlink is available in Windows Vista/7/8 only.

For Mac OS X

1. Goto http://tomcat.apache.org ⇒ Download ⇒ Tomcat 8.0 ⇒ "8.0.{xx}" (where {xx} denotes the latest upgrade number) ⇒ Binary distribution ⇒ Core ⇒ "tar.gz" package (e.g., "apache-tomcat-8.0.{xx}.tar.gz", about 8 MB).
2. To install Tomcat:
   1. Goto "~/Downloads", double-click the downloaded tarball (e.g., "apache-tomcat-8.0.{xx}.tar.gz") to expand it into a folder (e.g., "apache-tomcat-8.0.{xx}").
   2. Move the extracted folder (e.g., "apache-tomcat-8.0.{xx}") to "/Applications".
   3. Rename the folder to "tomcat", for ease of use. Take note of Your Tomcat Installed Directory. Hereafter, I shall refer to the Tomcat installed directory as <TOMCAT_HOME> (or <CATALINA_HOME> - "Catalina" is the codename for Tomcat 5 and above).

For Ubuntu
Read "How to Install Tomcat 8 on Ubuntu". You need to switch between these two articles.

For academic learning, I recommend "zip" (or "tar.gz") version, as you could simply delete the entire directory when Tomcat is no longer needed (without running any un-installer). You are free to move or rename the Tomcat's installed directory. You can install (unzip) multiple copies of Tomcat in the same machine. For production, it is easier to use the installer to properly configure the Tomcat.

Tomcat's Directories

Take a quick look at the Tomcat installed directory. It contains the following sub-directories:

• bin: contains the binaries; and startup script (startup.bat for Windows and startup.sh for Unixes and Mac OS X), shutdown script (shutdown.bat for Windows and shutdown.sh for Unix and Mac OS X), and other binaries and scripts.
• conf: contains the system-wide configuration files, such as server.xml, web.xml, context.xml, and tomcat-users.xml.
• lib: contains the Tomcat's system-wide JAR files, accessible by all webapps. You could also place external JAR file (such as MySQL JDBC Driver) here.
• logs: contains Tomcat's log files. You may need to check for error messages here.
• webapps: contains the webapps to be deployed. You can also place the WAR (Webapp Archive) file for deployment here.
• work: Tomcat's working directory used by JSP, for JSP-to-Servlet conversion.
• temp: Temporary files

2.2  STEP 2: Create an Environment Variable JAVA_HOME

(For Windows)

You need to create an environment variable called "JAVA_HOME" and set it to your JDK installed directory.

1. First, take note of your JDK installed directory. The default is "c:\Program Files\Java\jdk1.8.0_{xx}", where {xx} is the latest upgrade number. It is important to verify your JDK installed directory, via the "Computer", before you proceed further.
2. Start a CMD shell, and issue the command "set JAVA_HOME" to check if variable JAVA_HOME has been set:

   > set JAVA_HOME
   Environment variable JAVA_HOME not defined

   If JAVA_HOME is set, check if it is set to your JDK installed directory correctly. Otherwise, goto next step.
3. To set the environment variable JAVA_HOME in Windows 2000/XP/Vista/7/8: Push "Start" button ⇒ Control Panel ⇒ System ⇒ (Vista/7/8) Advanced system settings ⇒ Switch to "Advanced" tab ⇒ Environment Variables ⇒ System Variables ⇒ "New" (or "Edit" for modification) ⇒ In "Variable Name", enter "JAVA_HOME" ⇒ In "Variable Value", enter your JDK installed directory (e.g., "c:\Program Files\Java\jdk1.8.0_{xx}").
4. To verify, RE-START a CMD shell (need to refresh the environment) and issue:

   > set JAVA_HOME
   JAVA_HOME=c:\Program Files\Java\jdk1.8.0_{xx}   <== Verify that this is YOUR JDK installed directory

(For Mac OS X)
Skip this step. No need to do anything.

2.3  STEP 3: Configure Tomcat Server

The Tomcat configuration files are located in the "conf" sub-directory of your Tomcat installed directory, e.g. "d:\myProject\tomcat\conf" (for Windows) or "/Applications/tomcat" (for Mac OS X). There are 4 configuration XML files:

1. server.xml
2. web.xml
3. context.xml
4. tomcat-users.xml

Make a BACKUP of the configuration files before you proceed.

Step 3(a) "conf\server.xml" - Set the TCP Port Number

Use a programming text editor (e.g., NotePad++, TextPad for Windows; or gEdit, jEdit, TextEdit for Mac OS X) to open the configuration file "server.xml", under the "conf" sub-directory of Tomcat installed directory.
The default TCP port number configured in Tomcat is 8080, you may choose any number between 1024 and 65535, which is not used by an existing application. We shall choose 9999 in this article. (For production server, you should use port 80, which is pre-assigned to HTTP server as the default port number.)
Locate the following lines that define the HTTP connector, and change port="8080" to port="9999".

<!-- A "Connector" represents an endpoint by which requests are received
      and responses are returned. Documentation at :
      Java HTTP Connector: /docs/config/http.html (blocking & non-blocking)
      Java AJP  Connector: /docs/config/ajp.html
      APR (HTTP/AJP) Connector: /docs/apr.html
      Define a non-SSL HTTP/1.1 Connector on port 8080
-->
<Connector port="9999" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443" />

Step 3(b) "conf\web.xml" - Enabling Directory Listing

Again, use a programming text editor to open the configuration file "web.xml", under the "conf" sub-directory of Tomcat installed directory.

We shall enable directory listing by changing "listings" from "false" to "true" for the "default" servlet.

This is handy for test system, but not for production system for security reasons.

Locate the following lines that define the "default" servlet; and change the "listings" from "false" to "true".

<!-- The default servlet for all web applications, that serves static     -->
<!-- resources.  It processes all requests that are not mapped to other   -->
<!-- servlets with servlet mappings.                                      -->
<servlet>
  <servlet-name>default</servlet-name>
  <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
  <init-param>
    <param-name>debug</param-name>
    <param-value>0</param-value>
  </init-param>
  <init-param>
    <param-name>listings</param-name>
    <param-value>true</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
</servlet>

Step 3(c) "conf\context.xml" - Enabling Automatic Reload

We shall add the attribute reloadable="true" to the <Context> element to enable automatic reload after code changes. Again, this is handy for test system but not for production, due to the overhead of detecting changes.

Locate the <Context> start element, and change it to <Context reloadable="true">.

<Context reloadable="true">
   ......
   ......
</Context>

Step 3(d) (Optional) "conf\tomcat-users.xml"

Enable the Tomcat's manager by adding the highlighted lines, inside the <tomcat-users> elements:

<tomcat-users>
  <role rolename="manager-gui"/>
  <user username="manager" password="xxxx" roles="manager-gui"/>
</tomcat-users>

This enables the manager GUI app for managing Tomcat server.

2.4  STEP 4: Start Tomcat Server

The Tomcat's executable programs and scripts are kept in the "bin" sub-directory of the Tomcat installed directory, e.g., "d:\myProject\tomcat\bin" (for Windows) or "/Applications/tomcat/bin" (for Mac OS X).

Step 4(a) Start Server

For Windows

Launch a CMD shell. Set the current directory to "<TOMCAT_HOME>\bin", and run "startup.bat" as follows:

// Change the current directory to Tomcat's "bin"
// Assume that Tomcat is installed in "d:\myProject\tomcat"
> d:                           // Change the current drive
d:\> cd \myProject\tomcat\bin  // Change Directory to YOUR Tomcat's "bin" directory

// Start Tomcat Server
D:\myProject\tomcat\bin> startup

For Mac OS X

I assume that Tomcat is installed in "/Applications/tomcat". To start the Tomcat server, open a new "Terminal" and issue:

// Change current directory to Tomcat's binary directory
$ cd /Applications/tomcat/bin

// Start tomcat server
$ ./catalina.sh run

A new Tomcat console window appears. Study the messages on the console. Look out for the Tomcat's port number (double check that Tomcat is running on port 9999). Future error messages will be send to this console. System.out.println() issued by your Java servlets will also be sent to this console.

......
......
xxx xx, xxxx x:xx:xx xx org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["http-bio-9999"]
xxx xx, xxxx x:xx:xx xx org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["ajp-bio-8009"]
xxx xx, xxxx x:xx:xx xx org.apache.catalina.startup.Catalina start
INFO: Server startup in 2477 ms

Step 4(b) Start a Client to Access the Server

Start a browser (as HTTP client). Issue URL "http://localhost:9999" to access the Tomcat server's welcome page. The hostname "localhost" (with IP address of 127.0.0.1) is meant for local loop-back testing inside the same machine. For users on the other machines over the net, they have to use the server's IP address or DNS domain name or hostname in the format of "http://serverHostnameOrIPAddress:9999".
 

Try issuing URL http://localhost:9999/examples to view the servlet and JSP examples. Try running some of the servlet examples.
(Optional) Try issuing URL http://localhost:9999/manager/html to run the Tomcat Web Manager. Enter the username and password configured earlier in tomcat-users.xml.

REFERENCES & RESOURCES

1. Apache Tomcat mother site @ http://tomcat.apache.org.
2. Apache Tomcat Documentation @ "<TOMCAT_HOME>\webapps\docs".
3. "How to install MySQL and Get Started".
4. "Introduction to Java Database (JDBC) Programming".

 

 

 

 

 

 

 

 

 

 

 

 

Browse More Articles

Tweet

About MeNick22

Nikhil is a content marketing and SEO professional who enjoys the challenge of passion through blogging while creating awesome and useful content.