Install and configure a development Web server in UNIX

Build a fast, functional, and free Web server while jump-starting your UNIX skills

Before you start

Learn what to expect from this tutorial and how to get the most out of it.

About this tutorial

So, you want (or need) to install a fully functional application server for developing, testing, deploying, and tuning your Java™ 2 Platform, Enterprise Edition (J2EE™) application? Or perhaps you just want to learn something new, so you decided to stand up your own application server environment. Where do you start?

Regardless of your motivation, if you're reading this tutorial, you're likely familiar with the basics of how a Web site works and what may be needed as the lowest common denominator for accessing an application from your browser (domain, code, Web browser, database, and so on). As long as you know the basics, have a need for a Web or application server, have access to a UNIX server, and have a desire to learn a thing or three about Web server administration, this tutorial is for you.


In this tutorial, you will find:

  • An introduction to Apache Tomcat and UNIX, as well as what you need to begin.
  • A comparison of enterprise versus stand-alone Web architectures.
  • How to set up your UNIX server from scratch to prepare for installation of your Web or application server.
  • Detailed, step-by-step instructions on how to install and start your Tomcat Web server.
  • Information on setting up access to the Tomcat Web Application Manager.
  • Instructions for deploying a sample application.
  • Additional resources.

All this while slowly molding you . . . scratch that—quickly chiseling you into a beginner UNIX administrator.


This tutorial assumes that you have already installed the base UNIX operating system of your choice. To run the examples in this tutorial, you must also have Tomcat version 6 installed and running.

System requirements

Your server should have at least 10GB of available hard disk space and a minimum of 512MB of RAM. You need the following additional tools installed on your UNIX server before you can begin:

  • A Web browser: Any browser will do.
  • Java 2 Standard Edition Runtime Environment (JRE) release version 5.0 or later: Apache Tomcat version 6 requires the JRE.
  • A C compiler: Unfortunately, the base UNIX builds for flavors such as Solaris and IBM® AIX® do not come with such a compiler. See the link to the GNU GCC article in Related topics for more information.
  • File-extraction tools: On your server, you will likely need gunzip, tar, bzcat, and possibly GNU make and tar (gmake, gtar—available for download from the GNU site) to properly extract the files.

    To check which tools if any are already running on your server, run the following command:

    cd /usr
    Find . –name *.tar (repeat for *make, *zip, etc.)
  • Tomcat code: You need to download the Tomcat version 6 code from the Apache download site before proceeding. Save the tar.gz file to your server.

Tomcat and UNIX

The goal of this tutorial is not to give you an authoritative guide to all things related to Tomcat but rather to get you up and running with a great base foundation of knowledge regarding your stand-alone development or test server environment. When you have such a foundation, you can expand it into a full-blown enterprise environment, if you so desire.

Why Tomcat?

Why should you use Tomcat instead of one of the alternatives, such as JBoss, Geronimo, or WebSphere Application Server Express?

Tomcat version 6 by itself is a lightweight solution. It does not come with all the Java Platform, Enterprise Edition (Java EE) features and additional packages found in JBoss, Geronimo, and IBM WebSphere® Application Server Express, but it also doesn't require much memory and runs fast even on smaller servers. Plus, it is available at no cost.

Tomcat is a JavaServer™ Pages (JSP)/servlet container that supports only basic Java application server features. It lacks the scalability and Java EE version 5 compliance, which is why it is only rarely used in production environments.

If you're looking to use your new server in an enterprise environment, the more obvious UNIX flavors are AIX and Solaris. In fact, Solaris has the highest percentage of enterprise market share. Other UNIX choices include FreeBSD and Mac OS X.

The UNIX and Windows® installations of Tomcat

It is possible to run the examples in this tutorial on a Windows computer. The Apache community did the courteous thing after years of catering only to UNIX by developing for the Windows platform. However, depending on which statistics you're checking, Apache Web Server and subsequent products are used in more than 90% of Web server architectural solutions. Without getting into too much detail, UNIX offers the stability, security, and simplicity of a pure multi-user operating system that Windows Server® operating system just haven't matched.

That said, if you decide to use Windows, there are a few differences in Tomcat setup between UNIX and Windows that you should note before moving on:

  • Extracting the initial installation files on a UNIX server will probably require bzcat, gunzip, and tar, or gtar. A Windows Server machine typically uses WinZip or a similar utility.
  • PATH setup is more overt on a UNIX server. Windows still uses pathing, but much of that is behind the scenes or automatic when installing software.
  • Permissions considerations are more important in the UNIX setup and configuration. The great security strength of UNIX servers is also the single biggest cause for problems: permissions problems. When initially installing software, you need proper permissions to write that software into the base operating system's file systems—/var, /tmp, and so on. Furthermore, always be aware of permissions considerations when connecting various internal and external software components to your UNIX server. Always take IDs, groups, and proper access into consideration.
  • In Windows, installation is graphical user interface (GUI) based, while UNIX traditionally uses the command-line interface (CLI). This is changing somewhat with the Gnome and other graphical environments, including the increasingly popular Mac OS X version 10.5 Leopard. However, purists will always swear by the CLI. Besides, it's the best way to learn.
  • Windows uses .bat files for automated batch processes and .exe files for executables. UNIX uses .sh or .ksh extension files by default for executable scripts, and so on. The .sh or .ksh format depends on which shell you're using.

Tomcat versions

With numerous fixes included in every release, tweaks, new features, or new ways perform old tasks, it's sometimes difficult to decide which software version to go with. In Tomcat, you're faced with the same problem. I recommend looking at the details in Table 1 to match up your administrative server to the J2EE specification for which the application you're deploying was coded.

Table 1. JSP specs in relation to Tomcat versions
JSP specificationTomcat version
2.2/1.13.3.x (archived)

Another not-so-technical way of deciding between software versions is to stick to using the latest stable version of the software you want to work with. Usually, you get all the latest security fixes and functionality.

Architecture overview

Learn about the limitations of Tomcat and how a typical enterprise environment is set up.


Does your Tomcat installation need to be a single server in a development environment only? Isn't that quite limiting? Yes, it is, as a matter of fact! Tomcat has actually been downloaded millions of times, and it successfully runs many well-known Web sites in production environments. However, it has its limitations.

Commercial software products—particularly, IBM WebSphere Application Server—are available that are far superior for a production environment, mainly because of full J2EE compliance, additional functionality, and security. If you're looking to implement Tomcat in a fully functional production environment, you can still use this tutorial to build your foundation.

Enterprise environment

The enterprise architecture shown in Figure 1 is a more or less accurate description of what you may see behind the scenes when you press Enter in your browser. The architecture consists of recurring elements that I have seen working for clients around the nation, including multi-million dollar mission-critical applications at IBM and the United States Air Force. The sections that follow expand on each area in Figure 1.

Figure 1. Example enterprise architecture
Example enterprise architecture
Example enterprise architecture

A. Guards for your network

Typically, there are guards to your network—routers or firewalls, then proxy servers (reverse proxy, to be specific) that match up the Web request with the appropriate domain. There may be a level of authentication and even authorization at the front-end IBM Tivoli® Access Manager (TAM)/TAM WebSEAL server level before the request even hits the first server in your network, which will likely be protected by a demilitarized zone (DMZ).

B. Web servers

Next are the Web servers. Note that all these servers likely have vertical and horizontal failover, meaning separate hardware at each level that is cloned and possibly even duplicated at the software level. When your Web server passes the Web request and does its job of serving up the static content, you may have another layer of network dispatchers (NDs) or at the very least, a plug-in (such as the IBM HTTP Server [IHS] plug-in) that performs additional routing.

C. Application servers (servlet engines)

Now you have a J2EE engine (WebSphere Application Server), which is likely composed of a Web or servlet container as well as an Enterprise JavaBean (EJB) container to handle basic and advanced Java functions and business logic. You likely have multiple adapters to do a myriad of things, including connecting Web services and IBM WebSphere MQ messages. And more often than not, you have a database connection pool that connects to a MySQL, IBM DB2®, or Oracle back end.

When you tie in the potential connections to Lightweight Directory Access Protocol (LDAP) servers and even legacy servers, you have a true n-tier architecture. Now, take a look at a starter Web server environment.

Development environment

Look at Figure 2 with the assumption that it's based on a single-server installation on a single UNIX operating system that also has some means of accessing the Internet through a browser. This server will house your Tomcat installation, various operating system-level tools, as well as (possibly) your own local database or, at the least, software and application code stored in a local repository (local directory structure).

Note: When I say Tomcat server, I'm talking about the whole container.

Figure 2. Example stand-alone server architecture
Stand-alone Tomcat server
Stand-alone Tomcat server

Although this looks nothing like a true enterprise architecture, you will at least be able to replicate basic application functionality from your server. You are very limited, but for all intents and purposes, you're treating this installation as an example test development server or just a sandbox server to play in if you are an administrator.

You can choose to set up and run a separate Apache HTTP Server front end with your Tomcat installation, but this is not recommended for purposes of this tutorial, because it requires more overhead and a lot more administration and setup. You would also need the mod_jk module, you'd have to set up proper routing, and so on.

Either way, let's move on to some common questions before proceeding to the installation and configuration.

Preparing your server

Prepare your server by configuring your variables, editing your configuration files, creating users, and more.

Set your paths

In addition to the tools that must be installed on the server, you need to have all your PATH variable settings for your shell set up correctly. The PATH variables tell the shell where to look for certain software installations, tools, and so on.


First, you must install the JRE according to the instructions included with the release. I typically choose to use the full Java software development kit (JDK) rather than just the JRE. If you do, too, set your JAVA_HOME environment variable to the path name of the directory into which you installed the JDK (for example, /usr/local/java/j2sdk5.0). Use the following code to set your JAVA_HOME variable:

bash-3.00# export JAVA_HOME=/usr/jdk/instances/jdk1.5.0

You can also run:

JAVA_HOME=/usr/bin/java; export JAVA_HOME'

(there's really no difference).

Type an echo command to double-check that the command worked:

bash-3.00# echo $JAVA_HOME

CATALINA_HOME (Tomcat's default home directory)

CATALINA_HOME is used to refer to the full path name of the release directory. Use the following code to set this variable on your server:

bash-3.00# export CATALINA_HOME=/opt/apache-tomcat-6.0.16

This code pertains specifically to the Tomcat version you have installed. When in doubt, name it after the .tar file you extract, because that carries with it the correct version in the name.

Edit the shell and configuration file under your user

You probably noticed that I have a few references to Bash in the command samples. Without getting into boring details, users logged in to UNIX run out of shells on the server to execute a CLI that allows them to navigate and administer the server. This is not unlike other operating systems but is more flexible in that you can define that shell by typing something like Bourne shell (sh) or Bourne-again shell (bash).

In addition, depending on which shell you're using, you can edit the custom shell profile for your CLI to automatically set PATH variables and even alias characters to represent useful common commands on the server. To do this, edit .bashrc, .profile (the default under the bash shell), and so on. Use the vi editor to create this file, then edit it appropriately under your root, personal, or Tomcat-specific user ID to ensure that the PATH variables will be set each time you log in to the server.

Under your home directory, create the .profile file (shown in Listing 1), if it does not exist already, using the standard UNIX editor, vi.

Listing 1. Create your .profile using a standard UNIX editor
cd ~/ (home dir)
vi .profile

Type i (for insert), and then add each path you set above. An example may look something like this:

# /bin/sh
stty istrip
export PATH
umask 077

export SHELL=/usr/bin/ksh
export ENV=$HOME/.kshrc
export EDITOR=vi
export FCEDIT=vi

#Tomcat specific PATHs

export JAVA_HOME=/usr/jdk/instances/jdk1.5.0
export CATALINA_HOME=/opt/apache-tomcat-6.0.16

This may also be a good time to add additional PATH variables to cover all the areas in which you have tools installed that you're going to reference. For my setup, I also need to create the following two paths:

bash-3.00# PATH=/usr/ccs/bin:$PATH; export PATH (for make cmd)
bash-3.00# PATH=/usr/sfw/bin:$PATH; export PATH

Users and groups

If multiple users will use your server, you definitely want to set up user and group privileges to allow your different users access to various tools and file systems. This is also necessary if you're going to run your Tomcat installation as a non-root user (recommended for most production environments). I will get into the details of this in a later tutorial; however, here are some commands to chew on.

To create a Tomcat group, use the code in Listing 2.

Listing 2. Create a unique group for Tomcat to run under
/usr/sbin/groupadd -g {specific gid. Leave this blank and the OS will assign you a gid} 
{group name}
/usr/sbin/groupadd -g 10004 tomcatgroup

To create a Tomcat user, use the code in Listing 3.

Listing 3. Create a unique user for Tomcat to run under
/usr/sbin/useradd -d {user home directory} -g {user primary group} -u 
{specific UID. You can leave this blank, and the operating system will assign you a UID.) 
-s {default shell path for this user} -c "{Description of the user}" {username}
/usr/sbin/useradd -d /export/home/tomcat -g tomcatgroup -u 10010 -s /bin/ksh -c 
"Main Tomcat Administrative User" tomcat

Download and extract the server installation file

Discover the various methods for extracting the server installation file.

Find and move the installation file

If you're using a GUI, open a terminal window by choosing Launch > Applications > Utilities > Terminal. If you saved this file to your desktop and you're still the root user, run the command cd /Desktop. Run ls -ltr to see if your Tomcat tar.gz file is there. Then, move this file under the /opt directory (which is where most new software is installed). To move the installation files, type:

mv *tar.gz /opt

Then, type Ls –ltr /opt to make sure it's there.

Set permissions

Permissions are the lifeblood of a UNIX system. Without the proper permissions, you can't do anything; without restricting permissions to certain things, any user can do anything. That is why you first must grant yourself higher-level permissions on the installation file so that you (or another user) can properly execute it. Next, use the umask command, shown in Listing 4, to make sure that you can write the files to all the temp and installation directories appropriately when you extract the installation code.

Listing 4. Set the proper permissions and umask
cd /opt
chmod +x *gz (same as chmod 775)
umask 007 (makes any new files your user creates to be created with a 770 permission. 
Think chmod in reverse)

Extract the installation file

Most code packages come as a .tar file, with a .gz file to compact it even further. The gunzip command simply expands the package from its first layer of compression:

gunzip *.gz

Extract the .tar file

Finally, you must "untar" (unpack) the code. Doing so extracts the code exactly as it was packed—directories and all. This is why it's important to untar the file under the directory path in which you need the code installed. In UNIX, the best place would be /opt.

tar -xvf *.tar

This command extracts your application files. Type ls -latr to view the extracted files. If for some reason your installation came with a .bat or .exe file, you can remove those by typing:

rm *.exe
rm *.bat

When the Tomcat directory established, you can move on to configuring, compiling, and starting the server.

Configure, compile, and start

All Apache products that I've worked with include steps for configuring, compiling, and starting the product. This process gets the code ready, tells the software how and where to install, and so on.

Configure the software

To configure the Tomcat software, type:


./configure --with-java=/usr/java


export JAVA_HOME

Compile the code

With the Tomcat software configured, it's time to compile it.

Build the binaries and libraries

Listing 5 shows the code for building the Tomcat binaries and libraries.

Listing 5. Build the binaries and libraries
# gunzip jsvc.tar.gz

# pwd

# tar -xvf jsvc.tar

# gmake

Make sure that the path to gmake is in your PATHS (for example, ./sfw/bin/).

Note: The Tomcat site states that you should use the GNU make (gmake) instead of the native BSD make command on FreeBSD systems.

The code in Listing 6 generates the executable file, .jsvc. This file is required to successfully run Tomcat as a daemon.

Listing 6. Set the permissions on jsvc and copy
chmod 775 jsvc
cp jsvc ..
cd ..

Start the server

You can start the server from the CLI or from a Java program as an embedded server. Furthermore, the server can run as a daemon, which will run automatically, similar to a service setup in a Windows environment.

Run the basic startup script

Listing 7 shows the basic startup script for Tomcat.

Listing 7. Run the basic startup script
cd ../logs

Check catalina.out for errors! If you use cat, vi, more, or less on this file, type shift G to go to the bottom of the file. Or, you can type something like:

tail -50 catalina.out

to check the last 50 lines of the file for errors.

Although doing so is beyond the scope of this tutorial, you can also customize the startup process by modifying the Tomcat code or by implementing your own LifecycleListeners.

Run the startup daemon

You can start the daemon using a variety of options, such as -user for non-root user, -pid to specify the .pid file location, and -errfile and -outfile to specify the error and output file logs, respectively. For a complete list, find your jsvc process, and type ./jsvc -help. Listing 8 shows an example of a jsvc startup script.

Listing 8. Example jsvc startup script
Bash#./jsvc –home /usr/jdk/instances/jdk1.5.0 \
–Dcatalina.home=/opt/apache-tomcat-6.0.16 \
-cp ./bin/bootstrap.jar -outfile ./logs/catalina.out \
-errfile ./logs/catalina.err \

It is also very helpful to use the script included under the jsvc/bin directory. However, you will need to edit the variables to make sure the paths and such match your environment.

Test your Tomcat installation

The base Tomcat installation installs an internal HTTP server—Coyote HTTP/1.1—on http port 8080. For this architecture and setup, you don't need a separate Apache HTTP Server. You can change the ports to a more typical Web server port, like 80, simply by editing the server.xml file under the $CATALINA_HOME directory tree. You can also change the default Secure Sockets Layer (SSL) port to a typical SSL port, port 443. The server.xml file is where Tomcat gets most of its core configuration server information.

You can verify whether you started Tomcat successfully by going to http://localhost:8080/. You should see a startup page similar to Figure 3.

Figure 3. Initial Tomcat administrative console welcome page
Tomcat initial startup page
Tomcat initial startup page

Setting up Tomcat Web Application Manager

The Tomcat Web Application Manager provides many capabilities to help manage your Web applications. It allows you to deploy and "undeploy" Web applications in multiple ways, list applications, reload them, and even stop and start them.

Grant specific user access

To implement Tomcat Web Application Manager, you must first grant access to a specific user in the tomcat-users.xml file. To do so, use the code in Listing 9.

Listing 9. Grant access to Tomcat Web Application Manager by adding a user and role
vi tomcat-users.xml
Add these two lines below in between the two <tomcat-users> tags
	<role rolename="manager"/>
	<user username="tomcat1" password="test1234" roles="manager"/>

Just in case you're wondering, the above user and password are completely arbitrary. You do not need to create that user with the password on your UNIX server and can set these to whatever you wish. You will, however, use that information to log in to the management console.

For additional security, limit the access to that tomcat-users.xml file to only the owner of the file. To do so, you must set the permissions at 700 or below—for example:

# chmod 600 tomcat-users.xml

Restart the Tomcat server

For the changes above to take effect, you must restart your Tomcat server. To do so, use the code in Listing 10.

Listing 10. Restart your Tomcat server
./ ;tail -f ../logs/catalina.out

You should see something similar to this when you tail your catalina.out log file:

May 15, 2008 4:08:12 PM org.apache.jk.server.JkMain start
INFO: Jk running ID=0 time=0/74  config=null
May 15, 2008 4:08:12 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 6271 ms

Open the Tomcat Web Application Manager console

Go back to your Tomcat management console. Click the Tomcat Manager link in the Administration section of the left navigation pane. When successful, you will see the a window similar to Figure 4.

Figure 4. Tomcat Web Application Manager startup page
Tomcat Web Application Manager
Tomcat Web Application Manager

Tomcat also has a status application, which displays the status of the Tomcat server, including memory utilization of the JVM and the number of threads. You can access this very useful tool by clicking Server Status at the top right-hand side of the Tomcat Web Application Manger.

Installing the sample application

Tomcat comes with one main sample application. This certainly isn't sufficient to test your specific application needs, but it will provide a functional test of a basic JSP application and basic servlet.

Find the location of the WAR

When you pull up the Tomcat Web Application Manager to deploy your application, you need to know which directory to look in to select the Web Archive (WAR) for deployment. Use the code in Listing 11 to find this file.

Listing 11. Find your WAR file for deployment
bash-3.00# cd $CATALINA_HOME
bash-3.00# find . -name *.war

Open the Tomcat Web Application Manager Console to deploy the server

Under Manager Application, scroll down to the Deploy section, shown in Figure 5.

Figure 5. Sample application deployment
Sample application deployment
Sample application deployment

Under War file to deploy, simply click Browse. Select the sample application WAR using the path you found above. Click Open, and then click Deploy. Really, it's as simple as that to deploy the sample application.

Test the sample application

After you've deployed the application, you can see whether it came up by going to http://localhost:8080/sample/. Here, you can click JSP, and then click Servlet to verify that these come up and that basic application functionality is there, as shown in Figure 6. The server should now be ready for your application.

Figure 6. Sample application test and verification page
Sample application test and verification page
Sample application test and verification page

As you can tell, this is just a verification that your Tomcat server was installed correctly and is functioning as intended. To deploy your personal application, you must follow J2EE guidelines regarding packaging and installing under certain "context roots" under the Tomcat server directory.



By now, you should be well on your way to deploying and testing your dynamic J2EE application on your new Tomcat server! Hopefully, you learned about common Web architecture, how to install and configure your Tomcat development server on your UNIX operating system, and picked up some good UNIX administration tips along the way. From here, the possibilities are endless, and there's still a lot to learn.

Best of luck!

Downloadable resources

Related topics

Zone=AIX and UNIX
ArticleTitle=Install and configure a development Web server in UNIX