Install Apache Tomcat 8

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

This practical can be completed in a 3-hour session.

Skip to: Starting & Stopping Tomcat

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:

• HTTP Server: E.g., Apache HTTP Server, Apache Tomcat Server, Microsoft Internet Information Server (IIS), nginx, Google Web Server (GWS), and others.
• HTTP Client (or Web Browser): E.g., Internet Explorer (MSIE), FireFox, Chrome, Safari, and others.
• 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.
• Client-Side Programs: could be written in HTML Form, JavaScript, VBScript, Flash, and others.
• 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. The HTTP server returns an HTML form (client-side program), which is loaded into the client’s browser.
3. The user fills up the query criteria inside the form and submits 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 based on these parameters, and returns the query result to the client-side program.
6. The client-side program displays the query result on the browser.
7. The process repeats for the next request.

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. In other words, 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)”. 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 & 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 from 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

NOTE: At the time of writing, Tomcat 9 is at the alpha stage, not stable release. We shall install Tomcat 8.5.11.

For Windows

1. Goto http://tomcat.apache.org ⇒ Under “Tomcat 8.5.{xx} Released” (where {xx} is the latest upgrade number) ⇒ Downloads ⇒ Under “8.5.{xx}” ⇒ Binary Distributions ⇒ Core ⇒ “ZIP” package (e.g., “apache-tomcat-8.5.{xx}.zip”, about 9 MB).
2. Create your project directory, say “d:\myProject” or “c:\myProject”. UNZIP the downloaded file into your project directory. 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>.

For Mac OS

• Goto http://tomcat.apache.org ⇒ Under “Tomcat 8.5.{xx} Released” (where {xx} is the latest upgrade number) ⇒ Downloads ⇒ Under “8.5.{xx}”⇒ Binary distribution ⇒ Core ⇒ “tar.gz” package (e.g., “apache-tomcat-8.0.{xx}.tar.gz”, about 9 MB).
• To install Tomcat:
  • 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}”).
  • Move the extracted folder (e.g., “apache-tomcat-8.0.{xx}”) to “/Applications”.
  • For ease of use, we shall shorten and rename this folder to “tomcat”.

Take note of Your Tomcat Installed Directory.
Hereafter, I shall refer to the Tomcat installed directory as <TOMCAT_HOME>.

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), shutdown script (shutdown.bat for Windows and shutdown.sh for Unix and Mac OS), 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.

• First, find your JDK installed directory. The default is “c:\Program Files\Java\jdk1.8.0_{xx}”, where {xx} is the upgrade number. Take note of your JDK installed directory.
• To set the environment variable JAVA_HOME in Windows 7/8/10: Start “Control Panel” ⇒ System and Security (Optional) ⇒ System ⇒ Advanced system settings ⇒ Switch to “Advanced” tab ⇒ Environment Variables ⇒ System Variables ⇒ “New” ⇒ In “Variable Name”, enter “JAVA_HOME” ⇒ In “Variable Value”, enter your JDK installed directory as noted in Step 1.
• To verify, RE-START a CMD shell (restart needed 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)

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/conf” (for Mac OS). 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, Sublime, Atom for Windows; or gEdit, jEdit, Sublime, Atom for Mac OS) 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 (around Line 69) that define the HTTP connector, and change port=”8080″ to port=”9999″.

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 (around Line 103) that define the “default” servlet; and change the “listings” from “false” to “true”.

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 (around Line 19), and change it to <Context reloadable=”true”>.

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

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

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).

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:

For Mac OS

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

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 sent to this console. System.out.println() issued by your Java servlets will also be sent to this console.

(Skip Unless …) Cannot Start Tomcat: Read “How to Debug“.

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”.

Starting and Stopping the Tomcat Server

This appendix describes how to start and stop the Tomcat server from a command line prompt as follows:

Go to the appropriate subdirectory of the EDQP Tomcat installation directory. The default directories are:

On Linux: /opt/Oracle/Middleware/opdq/server/tomcat/bin

On Windows: c:\Oracle\Middleware\opdq\server\tomcat\bin

Where server is the name of your Oracle DataLens Server.

Run the startup command:

On Linux: ./startup.sh

On Windows: % startup.bat

Verify that the service was started correctly by looking for the final server startup messages.

Likewise, the Tomcat Server can be stopped from the command line with the following command:

On Linux: ./shutdown.sh

On Windows: % shutdown.bat

This command line service directly corresponds to the Tomcat Server service that is used in the Services Tool. Any combination of dialog and command line commands can be used to start and stop the service.