installing tomcat in 15 minutes (cookbook approach for unix/linux)
- TARGET-AUDIENCE: beginners
- COCOON-RELEASES: n.a
- DOCUMENT-STATUS: *draft* reviewed released
This document applies to :
- tomcat-4.1.18 and newer under linux and unix
Warning: many pages on this wiki imply that a servlet container must be installed before running Cocoon, this is wrong - see NoServletContainerRequired. A basic installation of Cocoon for test or development purposes can be very simple.
What you will get from this page
You will learn, how to retrieve and setup tomcat, the official reference ServletContainer. This approach has been tested with tomcat 4.1.18 and newer releases.
Your basic skills
I assume, you
- have minimal knowledge about webapplications and application servers in general.
- know how to unzip or untar a compressed package
Technical prerequisites
In order to install tomcat you need
- an operating Java-1.2, or a newer Java Virtual Machine
- some basic knowledge in "sh" (unix shell)
Links to other information sources
For general infos about installation of tomcat refer to the official Tomcat site. See
http://jakarta.apache.org/tomcat/tomcat-4.1-doc/RUNNING.txt
for download install build and so on.
Step I: Get the distrib
Go to http://jakarta.apache.org/site/binindex.cgi and retrieve Tomcat 4.1.x.
It's not linked more exact from here for better usage of the Apache mirroring system.
On the distribution directory you will find several tomcat packages suitable for different operating systems and different java-versions. For linux or unix you will download the tar.gz distribution.
caveat: Make sure, which java version you have installed. If you are running the Java-1.4 runtime or JDK, please retrieve one of the tomcat distributions, which are clearly labeled with jdk14. If you are running a lower version of java, you must download one of the other distributions. You can check which java version you are running by issuing the following command:
java -version
Step II: Unpack it
unpack the distrib to any convenient place.
Unfortunately several conventions apply depending on which operating system you are working. And it depends, for which user group you are planning to install the Servlet Engine. If you install tomcat for your personal usage only, choose any convenient place under your home folder. If you are setting up a server for many users, it would be common place to choose /opt/tomcat as root of your installation. I personally choose /opt/tomcat, place the tar file into this directory, then i untar it at place. I end up with a subfolder named jakarta-tomcat-4.1.18
. The following set of commands will do the job:
mkdir /opt/tomcat cd /opt/tomcat # You need to retrieve the distrib now to /opt/tomcat tar xzf tomcat-4.1.18.tar.gz
caveat: some unix tars do NOT support the uncompression flag 'z' in these case you either need to gunzip first. The command sequence would be:
gunzip tomcat-4.1.18.tar.gz tar xf tomcat-4.1.18.tar
Step III: Prepare for startup
Once you have installed tomcat, you need to prepare it for startup. I recommend to try first starting the distribution as is. You only need to modify something, if the following ports are already occupied by some other program:
8005 |
Tomcat Shutdown port for maintenance |
8080 |
Tomcat Standard http port |
8009 |
Tomcat standard port for connection to a webserver |
Please note, that your Tomcat server comes with an included HTTP-server. So you don't need a webserver like the apache-server to run your servlets. You simply start tomcat, then you are ready to access it from your browser.
modify the standard port settings
As pointed out above, you need to do this only, if you are sure, that the Tomcat standard ports are already occupied. If you are unsure, just start Tomcat and check for errors telling about
"Adress already bound"
-messages. If this occurs, come here and do the following:
- Enter the subfolder named "conf"
- edit the file named server.xml
*Search for the shutdown port definitionYou may change the port to any convenient number above 1024 and below 32768.<Server port="8005" shutdown="SHUTDOWN" debug="0">
*Search for the http port definitionYou may change the port to any convenient number above 1024 and below 32768.<!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 9011 --> <Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8080" minProcessors="5" maxProcessors="75"
*Search for the Webserver connectorDepending on your system, either the Coyote/JK2 AJP Connector, the AJP 1.3 Connector is active. The inactive connector is commented out with XML comments of following syntax:<!-- Define a Coyote/JK2 AJP 1.3 Connector on port 8009 --> <Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8009" minProcessors="5" maxProcessors="75" enableLookups="true" redirectPort="8443" acceptCount="10" debug="0" connectionTimeout="0" useURIValidationHack="false" protocolHandlerClassName="org.apache.jk.server.JkCoyoteHandler"/> <!-- Define an AJP 1.3 Connector on port 8009 --> <!-- <Connector className="org.apache.ajp.tomcat4.Ajp13Connector" port="8009" minProcessors="5" maxProcessors="75" acceptCount="10" debug="0"/> -->
You may inactivate both connectors for the moment, but need to reactivate one as soon as you want to connect your Webserver with tomcat.<!-- anything except 2 consecutive '-' signs -->
Start your container for the first time
Enter the subfolder named "bin" of your distribution. You will find a set of usefull scripts:
catalina.sh |
best for manual startup from commandline |
startup.sh |
best for script based startup |
shutdown.sh |
best for script based shutdown |
For the beginning you may use catalina.sh :
cd /opt/tomcat/jakarta-tomcat-4.1.16/bin ./catalina.sh
You have started tomcat now in foreground. The shell is blocked and tomcat runs. You can stop tomcat by pressing CTRL-C at any time.
An alternative way is to use ./startup.sh
instead of
./catalina.sh
This would start tomcat in the background sending the screen output into a logfile instead. To stop tomcat in background mode, use the script
./shutdown.sh
Verify operation
Once you have started tomcat, you can use your Browser to access the Welcome page. Assuming you have not modified the $tomcat_root/bin/server.xml as described above, you may now access tomcat by typing in your browser:
http://localhost:8080
You might have to replace localhost by the name of your server only, if your browser runs on a different machine. If you see the tomcat welcome message, chances are very high, that your installation was correct. If you don't see anything see below.
Where to go next
Now you have managed to install the Tomcat Servlet Container. You have verified, that your container operates in your environment. Now it's time to get cocoon into play. I propose following documents:
BeginnerInstallation: We will show you, how you can setup cocoon within your new Servlet Container.
First aid if something goes wrong.
There is always the chance, that something goes wrong during setup. The most critical part of the installation is the modification of the file $tomcat_root/conf/server.xml
Here are some tips, how to proceed if Tomcat won't show up.
Look at the startup logs
You will find the logs under $tomcat_root/logs This is a typical list of logfiles, you may find:
catalina.out
localhost_log.2003-01-15.txt
catalina_log.2003-01-14.txt
localhost_admin_log.2003-01-14.txt
localhost_examples_log.2003-01-14.txt
- If you encounter any problem with tomcat it is best to first look into
catalina.out
. - If you can't find a clue to your problem there, look next at
localhost_log.<date>.txt
. You should get a clue by now. - If you still can't access your server with your browser, recheck the first lines of
catalina.out
and look for following pattern:and verify that your portsettings are corect.[INFO] Http11Protocol - -Initializing Coyote HTTP/1.1 on port 8080 Starting service Tomcat-Standalone Apache Tomcat/4.1.18
- And don't forget to enter the correct URL to your browser:
http://loalhost:8080
page metadata
- AUTHOR: Hussayn Dabbous
- AUTHOR-CONTACT: hussayn.dabbous@saxess.comBR
- REVIEWED-BY:
- REVIEWER-CONTACT:BR