Understanding Apache Tomcat: Getting Started

posted by fhanik on October 19, 2011 07:39 AM

Apache Tomcat, and other containers, have been around for so long today that it has become increasingly harder to get started with them today.

In this article, we will take you back from the beginning with how to get started with Apache Tomcat. We will go into the lowest level, so you don't have to rely on an IDE or other system to get started. This article is written for those that have never used Apache Tomcat and wish to get started in an easy, yet explanatory, way that helps you to understand what is happening under the hood. This will fast track you to become very proficient with this light weight application server.

Step 1. Download and Install Apache Tomcat

While there are a lot of different packages available to install Tomcat, for example some Linux distributions you can download it using that distributions package and dependency management. This is good, for the sake of simplicity, but once again, you lose the concept of what Tomcat is and what true dependencies it has as well on how to use it.

I strongly recommend only moving to a third party packaging of Apache Tomcat after you understand the container itself. This will help avoid complications when you try to create a plan for how you distribute, upgrade and maintain your software.

Rule 1. When learning, only download the software from

Now, since you are learning Apache Tomcat from scratch, I suggest you start with Apache Tomcat 7.  As explained in an earlier post,  the majority of features that are implemented, are driven by the (Servlet) and (JSP) specifications.  Each time the Servlet specification is upgraded, new features added, the Apache Tomcat will plan for a new major release of Apache Tomcat. The latest version, Apache Tomcat 7,  is based on the version of the Servlet specification, in this case, Servlet 3.0.

Currently, there are two major versions, Tomcat 6 and Tomcat 7, that are actively maintained by the Apache Tomcat community (Tomcat 5.5 is in the process of reaching end of life for next year). You can't expect any new features in Apache Tomcat 6. This version has been around for a while, and is being maintained for bug fixes, security fixes and minor improvements to performance and stability.

If new features are introduced into the development branch of Apache Tomcat, called trunk, there is a good chance that it will be incorporated into Apache Tomcat 7, but a much smaller chance that it will be added to Apache Tomcat 6.

So what version of Apache Tomcat should I really use? The answer to this question is another question: What version of the servlet specification did the developers use to develop their web application against? It's the application, and the Servlet API the application uses, that drives what container to pick.

If unsure, pick Apache Tomcat 7, but if possible, seek advice from the application developers first. 

Picking the right download option

As the download page ( suggests, there is a README file that explains what that package is. The first two packages are identical and you pick the .zip or .tar.gz based on what package extraction software you have.

On a Unix system I would use the tar.gz as they .zip file may not carry over executable permissions on the .sh shell script files. In every other aspect, these two files are identical.

Rule 2: If you are just getting started, start out with one of the platform neutral packages. These packages will work on both Windows and Unix systems. On Unix systems, if copied over, you may have to set executable permissions on the files ending with .sh in the bin directory.

The next three packages contain two libraries that are compiled for a specific architecture of Windows (32-bit, 64-bit Windows zip, 64-bit Itanium If you know that you will be running on Windows, and wish to run it as a service, one of these packages will contain everything you need. These packages exclude any files from the platform neutral packages, rather they simply add libraries specific to Windows. Namely:

  1. service wrappers
    • tomcat7.exe
    • tomcat7w.exe
  2. APR libraries

Service Wrappers

On the windows platform, Tomcat can run as a service. There are two executable that assist with this process. tomcat7.exe is the executable that manages (installs) the service into the Windows registry so that it starts up on startup. tomcat7w.exe is the actual executable that runs as a process on your Windows operating system when the service is running. To install/uninstall an Apache Tomcat installation as a service, you simply invoke the service.bat script found in the bin folder. More on that later.

APR libraries

Tomcat has several implementations on how it handles network traffic. One of these implementations is written in C and uses the Apache Portable Runtime (APR) library. This library is compiled for Windows and is found in the file tcnative-1.dll.

When you are first learning Apache Tomcat, you don't need either of these libraries.

GUI Installers

The last file (32-bit/64-bit Windows Service Installer) is a GUI installer, to install Apache Tomcat on a Windows system and install the service. This is how Windows users are familiar with installing software, and at first it seems this is the easiest way of installing Apache Tomcat. For the sake of learning, it is not, as it bypasses some important details hidden from the user.

Installing Apache Tomcat

Installing the software at this point becomes very easy. Simply extract the installation package you downloaded. You will end up with a folder structure that starts with the build name (e.g., apache-tomcat-7.0.22), and has the main directories of bin, conf, lib, logs, temp, webapps and work underneath. 

Tomcat 7 file structure

Apache Tomcat is lightweight, even in its simplicity and size on disk. What you see now on the file system is all you installed. You should note, there are no hard coded path anywhere in this installation. Therefore, you can rename or move this directory anywhere you wish.  

At this point, believe or not, you have installed Apache Tomcat!

Apache Tomcat only has one dependency, and that is a Java Runtime Environment (JRE). You may choose to install and use a Java Development Kit (JDK), since a JDK contains a JRE within it. If you have never used Java, and Apache Tomcat is the very first software you use that requires Java, you may start taking a tutorial on how to download and install Java. Make sure you take note of where you install Java as you will need to know this location. In the above YouTube tutorial, the recorder skips the option of selecting a directory where to install it.

Rule 3: For the sake of simplicity, when you install software, even if on Windows, choose file paths that do not contain white spaces. This will save you some troubleshooting time. 

In my own system, I have installed Java into "C:\software\Java\jdk1.6.0_25".  In order to run Apache Tomcat, you will have know this location.

Step 2. Starting/Stopping Apache Tomcat

In order to start Apache Tomcat, we need to define where we installed Java. You can do this in a command prompt, or you can define it as an environment variable (For how to define an environment variable check here). So after installing Apache Tomcat, in order to start it I have to accomplish two things:

  1. Define JAVA_HOME or JRE_HOME. JAVA_HOME would point to a JDK installation, while JRE_HOME would point to a JRE installation. If you are unsure what you should install, install the JDK and set JAVA_HOME.
  2. Launching Apache Tomcat.

In this example, I've started Apache Tomcat from a Windows command prompt by setting JAVA_HOME and executing the catalina.bat script with the run argument.

If Apache Tomcat started successfully you would see the following output:

Oct 17, 2011 3:22:21 PM org.apache.catalina.startup.Catalina start
INFO:Server startup in 735 ms

The catalina.bat script can be run with the start parameter. This method starts up Apache Tomcat as a background process (on unix) or in another command prompt (on windows). This is equivalent of running the script startup.bat/ which simply invokes the catalina script with the start argument. Similarly the shutdown script simply invokes the catalina script with the stop argument.

To stop Apache Tomcat, you can call shutdown.bat/ or call catalina.bat stop/ stop.

On a unix system, you'd set JAVA_HOME and run the script with the run argument. The run argument launches Apache Tomcat in the foreground, and we can easily shut it down by hitting Ctrl+C in the same console.

You may ask yourself why anyone would run Apache Tomcat this way? How does Apache Tomcat start up if the system reboots. These options will be described in the next article, we are now purely focused on getting you familiar with Apache Tomcat at the most basic level.

What is happening under the hood

Apache Tomcat is very lightweight java application in itself. To launch, it only needs a JVM, the java process running on your operating system. The catalina script launches a JVM. Next, the catalina script supplies all the arguments the JVM needs to launch a specific Java application, in this case Apache Tomcat.

Easy, wasn't it? Mission accomplished. In our next article, coming shortly, we will show you how to configure Apache Tomcat to run as a service, setting JVM parameters and configuring Apache Tomcat itself.

Filip Hanik is a Senior Software Engineer for the SpringSource Division of VMware, Inc. (NYSE: VMW) and a key participant in the company's Apache Tomcat initiatives. Filip brings 15 years of extensive experience in architecture, design and development of distributed application frameworks and containers and is recognized for his top-quality system development skills and continuous participation of Open Source development projects. Filip is an Apache Software Foundation member and a committer to the Apache Tomcat project where he is a leading authority on Tomcat clustering and a key contributor to the core of the platform. Filip has made contributions to software initiatives for, Sony Music, France Telecom and has held a variety of senior software engineering positions with technology companies in both the United States and Sweden. He received his education at Chalmers University of Technology in Gothenburg, Sweden where he majored in Computer Science and Computer Engineering.


Post new comment

This question is for testing whether you are a human visitor and to prevent automated spam submissions.