A Guide To Apache Tomcat Linux Installation and Set-Up

Many Apache Tomcat users choose to run their Tomcat instances on Linux, with good reason - it's a rock solid operating system, with many different flavors to cater to the needs of a wide variety of users and situations.  

Installing Tomcat on Linux need not be cumbersome.  Some users will have no problem getting Tomcat up and running on their Linux machine.  However, the large number of available Linux distributions with slightly differing features can leave a large number of users hung up on small installation errors.  

This situation isn't helped by the fact that many Linux distributions include custom Tomcat packages, which are often modified in odd ways, and sometimes contain bugs that have already been fixed in the official Tomcat releases. 

The aim of this article is to guide you through a successful, error-free installation of Tomcat on Linux.  We'll focus on installing Tomcat on Linux from the official binary distribution, as this is the most sure way to avoid errors down the line.  

We hope that you find this guide useful as you set-up Tomcat for the first time on your Linux machine! Let's get started.

Tip: Tcat Server is the enterprise Tomcat application server, providing key enterprise features such as deep diagnostics, configuration management, advanced deployment functionality and reliable restarts. Try Tcat Server today!

Installing Tomcat From the Apache Distribution

It might not be as simple as typing a single repository command, but installing Tomcat using the latest official Apache binary release is the best way to avoid errors and confusion, provided you do it correctly.  This method is recommended especially if you are new to Tomcat, because it will be a good introduction to Tomcat's internal configuration files.

Also, the Tomcat documentation available on the Apache project site, which is quite good, references the unmodified binary distribution exclusively - there is no comprehensive package-specific documentation.  If you anticipate having to look up a good amount of infuriation early on, using the official distribution will potentially save you a lot of hassle.

Finally, and most importantly, using the official distribution ensures that you are using the most up-to-date version of Tomcat available.  The Tomcat developers are very active, often releasing multiple patches per day for bugs and security risks.  Using the binary distribution ensures that you'll be able to take advantage of all their hard work.

Step 1 - Download And Extract The Latest Binary Distribution

You can download the latest version of Tomcat from the Apache project site.  Click here to see the list of available versions.  Most Linux users will want to use the latest TAR package. 

To download the package directly from the Linux command line, you'll use a command that looks something like this:

  $ wget http://apache.YourFavoriteMirror.com/tomcat/tomcat-[#]/v[#]/apache-tomcat-[#].tar.gz

After you have downloaded the package, make sure to verify the MD5 checksum against the key provided on the Apache website, like this:

  $ md5sum apache-tomcat-[#].tar.gz


Next, extract the package:

  $ tar xvzf apache-tomcat-[#].tar.gz

...And move the extracted folder into a dedicated directory:

  $ sudo mv apache-tomcat-[#] /usr/local/example/path/to/tomcat

Step 2 - Set The Required Environment Variables

If you haven't already done so during a different application's install process, you'll need to set the JAVA_HOME environment variable in order for Tomcat to run.  We recommend doing this by editing ".bashrc", as it this will allow you to set up automatic start for Tomcat, if you need it.  Open the file with vi:

  $ vi ~/.bashrc

...And set the variable like this:

  export JAVA_HOME=/usr/lib/path/to/java

While you're here, you should also set the CATALINA_HOME variable, which should point to the main Tomcat directory:

  export CATALINA_HOME=/path/to/tomcat

Log out and log back into bash to have your changes take effect.

Step 3 - Start Tomcat

If you followed all these steps correctly, you should be able to start Tomcat via its included startup script, startup.sh:

$ $CATALINA_HOME/bin/startup.sh

Tomcat runs on port 8080 by default.  To check if your server is up and running correctly, use:

$ ps -ef | grep java | grep 8080

If this command returns the Catalina process, Tomcat is up and running. You should now be able to access the Tomcat Welcome Page at http://localhost:8080/


Step 4 - What To Do Next

Now that you've installed Tomcat, you may want some additional information to get you started.  

If you want more information about configuring Tomcat, please visit our helpful guide to Tomcat Configuration, as well as our Tomcat Performance and Tomcat JVM guides, which will help you get Tomcat performing at its best on your machine.

Running Tomcat Automatically At Linux Startup

A potential drawback of installing Tomcat from a binary distribution instead of using a Linux-packaged version is that you'll have to do some extra legwork to make Tomcat start automatically when Linux boots up.  To make this process easy and pain-free, follow this simple guide.

Step 1 - Create A Tomcat-Specific User and User Group

It's a bad idea to run Tomcat as the root user, especially if you're going to be starting Tomcat automatically.  It's much more secure to create a new group and user specifically to run Tomcat.  You can do so with the following commands (in this example, we have created a user group named tomcat, and a user named tomcat with the password tomcat; you can certainly be more creative if you wish):

  $ groupadd tomcat

  $ useradd -s /sbin/nologin -g tomcat -d /path/to/tomcat tomcat

  $ passwd tomcat

Step 2 - Adjust Ownership For New Users And Groups

Now that you have created a user to run Tomcat, you'll need to give them access to the correct directories.  Use the following commands, substituting your own usernames and groups as necessary:

  # chown -R tomcat.tomcat /path/to/tomcat

  # chmod 775 /path/to/tomcat/webapps

The first gives ownership of the Tomcat directories to the Tomcat user, and the second gives the user write access for the web apps directory.


Step 3 - Relay Traffic For Non-Root Tomcat User

When running Tomcat as a user other than the root user, you will not be able to bind to port 80, which is where Tomcat listens for HTTP requests.  To get around this, you can use Netfilter, which is packaged with all major Linux distributions:

  # iptables -t nat -I PREROUTING -p tcp --dport 80 -j REDIRECT --to-ports 8080

  # iptables -t nat -I OUTPUT -p tcp --dport 80 -j REDIRECT --to-ports 8080

To preserve these rules through re-boot, save them with the "ip-tables-save" command, and then follow the procedure appropriate for your Linux distribution (for most distributions, this means editing the iptables init script; Debian users should load the configuration via a script called by if-up.d or pre-up.d).


Step 3 - Create A Custom init Script

To start Tomcat at Linux boot time, we'll need to create an init script that calls the startup.sh and shutdown.sh scripts included with Tomcat.  

The actual creation of this script is outside the scope of this article, but there are many useful resources available online.  All you need to know in order to use the basic init script format to call Tomcat is how the startup.sh and shutdown.sh scripts work.  

For more information about these scripts, visit our Tomcat Start page, which includes a simple, step-by-step guide to Tomcat's three start-up shell scripts.