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.
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 http://tomcat.apache.org/
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.
As the download page (http://tomcat.apache.org/download-70.cgi) 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 Windows.zip, 64-bit Windows zip, 64-bit Itanium Windows.zip). 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:
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.
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
When you are first learning Apache Tomcat, you don't need either of these libraries.
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 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
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.
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:
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
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/startup.sh which simply invokes the
catalina script with the
start argument. Similarly the
shutdown script simply invokes the
catalina script with the
To stop Apache Tomcat, you can call
shutdown.bat/shutdown.sh or call
catalina.bat stop/catalina.sh stop.
On a unix system, you'd set JAVA_HOME and run the
catalina.sh 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.
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.