How to Install Tomcat on MacOS X


Amandeep Jawa
deep AT worker DASH bee DOT com
Worker Bee Software
Document Version 1.0.4



Note: This info is out of date - better instructions exists here on the Apple website.

I will leave the document up in case some of the techniques are still useful, but I no longer recommend using this document.


This document describes how I installed Tomcat 3.2.1, Apache 1.3.19 & mod_jk on my MacOS X 10.0.3 installation on my Powerbook G4 Titanium. This information is presented to supplement existing offical documenation & in NO WAY supercedes it. Also it should be noted that this is ONE way to accomplish these goals - it is by no means the only way and probably isn't even the best way. Improvements are welcome!

This document assumes that you have installed the Developer tools & that you are logged in as an administrative user. You do not need to have root access to accomplish this. If you do have root access, you do not need to preface commands with sudo as I have done.

Note: Internet Explorer 5.1 Preview for MacOS X mangles the numbering of these lists - there is nothing I can do.

Doc History:
5/10/01 asj Created
5/14/01 asj Finished 1.0, cleaned up & converted to HTML
5/18/01 asj Added comments to this header and clarified the creation of the Tomcat home directory.
8/14/01 asj Fixed major oversight: Adding Tomcat support to httpd.conf
9/27/01 asj Fixed minor broken link to sourceforge
2/26/02 asj Retired in favor of Apple's documentation


  1. My first step was to upgrade Apache to the latest release version, which as of this writing is (5/14/01) is 1.3.19. I opened a terminal & did the following:
    	wget http://www.apache.org/dist/httpd/apache_1.3.19.tar.gz
    	gnutar xzf apache_1.3.19.tar.gz
    	cd apache_1.3.19
    	./configure --enable-module=most --enable-shared=max
    	make
    	sudo make install
    	
    Many thanks to Wincent Colauta for his article on how to do this.

  2. Then I downloaded the latest release build of Tomcat, which as of this writing is (5/14/01) is 3.2.1.:
    	http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.2.1/bin/jakarta-tomcat-3.2.1.tar.gz
    	
  3. Next I launched Terminal & found the directory where I downloaded Tomcat & moved it to /Applications/Tomcat:
    sudo mv jakarta-tomcat-3.2.1 /Applications/Tomcat
    This directory will now be referred to as the Tomcat home directory. Note that we are not only moving the directory, but renaming it as well. This is mostly just a matter of aesthetics - I thought the name "jakarta-tomcat-3.2.1" was too cumbersome.

  4. To run Tomcat, you need to create an environment variable TOMCAT_HOME which refers to the Tomcat home directory you just created. To make an environment variable, I made a .tcshrc file as follows:
    1. create a text file
    2. copy the text below into it.
      			#################################################################################
      			#	.tcshrc
      			#	Amandeep Jawa
      			# 
      			#	This file is my first attempt at making a tcshrc file to set my environment 
      			#	variables and such on MacOS X.
      			#
      			#	<REVISION HISTORY>
      			#	05/09/01  asj  Created
      			#
      			#################################################################################
      			
      			# Environment variables
      			setenv TOMCAT_HOME /Applications/Tomcat
      			
    3. Save the file as .tcshrc in your home directory: /Users/your_user_name.
    4. Note that the "." in the file name is very important & that it must not have an extension like .rtf or .txt. and that it MUST be placed in your user's home directory.
    5. Also make SURE that there are blank lines at the end of the file.

  5. Now you must change the permissions on the .tcshrc file. Go to a terminal window & type:
    		cd 
    		chmod 775 .tcshrc
    	

  6. Now you should logout & log back in for the .tcshrc file to take effect.

  7. Now try to start Tomcat. Open a terminal & type:
    	cd $TOMCAT_HOME/bin
    	./startup.sh
    	
    You should see output like:
    	Using classpath: /Applications/Tomcat/lib/ant.jar:/Applications/Tomcat/lib/jasper.jar:/Applications/Tomcat/lib/jaxp.jar:/Applications/Tomcat/lib/parser.jar:/Applications/Tomcat/lib/servlet.jar:/Applications/Tomcat/lib/test:/Applications/Tomcat/lib/webserver.jar
    	
    And then after a few seconds:
    	2001-05-15 12:50:12 - ContextManager: Adding context Ctx( /examples )
    	2001-05-15 12:50:12 - ContextManager: Adding context Ctx( /admin )
    	Starting tomcat. Check logs/tomcat.log for error messages 
    	2001-05-15 12:50:12 - ContextManager: Adding context Ctx(  )
    	2001-05-15 12:50:12 - ContextManager: Adding context Ctx( /test )
    	2001-05-15 12:50:15 - PoolTcpConnector: Starting HttpConnectionHandler on 8080
    	2001-05-15 12:50:15 - PoolTcpConnector: Starting Ajp12ConnectionHandler on 8007
    	2001-05-15 12:50:15 - PoolTcpConnector: Starting Ajp13ConnectionHandler on 8009
    	
    If you don't you may need to fix some permissions on the tomcat scripts, so type:
    	sudo chmod ug+x startup.sh
    	sudo chmod ug+x shutdown.sh
    	sudo chmod ug+x tomcat.sh
    	

  8. Now confirm that you can run servlets in Tomcat as a standalone container. Go to your web browser & access the URL: http://localhost:8080
    You should see the Tomcat default page with a Tomcat logo & some links to JSP & Servlet examples. Click on the examples & make sure they run.

    If all you need from Tomcat is the ability to run servlets for development & testing this installation may be enough for you. If so, you can stop now. Otherwise, you should continue & set up Apache to work with Tomcat.


  9. To create a connection between Tomcat & Apache you need to make & install mod_jk.so
    1. Get the Tomcat source code.
      1. Download the source from the Tomcat site.:
        http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.2.1/src/jakarta-servletapi-3.2-src.tar.gz
      2. Unzip the source code using Stuffit Expander.
      3. We will refer to this directory that you unziped as the tomcat source directory. In my case it is: /Users/deep/Documents/Downloads/jakarta-tomcat-3.2.1-src/src/native/apache1.3/
    2. Get two missing header files dlfcn.h and dlopen.c from SourceForge
      1. http://download.sourceforge.net/fink/dlcompat-20010123.tar.gz
      2. Unzip the source code using Stuffit Expander.
      3. Copy the two files dlfcn.h and dlopen.c into the tomcat source directory.
    3. Now make mod_jk.so
      1. cd to the tomcat source directory.. In my case:
        					cd /Users/deep/Documents/Downloads/jakarta-tomcat-3.2.1-src/src/native/apache1.3/
        				
      2. Execute the build command:
        					apxs -o mod_jk.so -I. -I/System/Library/Frameworks/JavaVM.framework/Headers -I../jk -DFREEBSD -c *.c ../jk/*.c
        				
        By the way, for all you Unix Java people, this implies that on MacOS X: /usr/local/jdk/include = /System/Library/Frameworks/JavaVM.framework/Headers
      3. Fix the permissions:
        					sudo chmod ugo+x mod_jk.so
        				
      4. Copy mod_jk.so to where it should live:
        					sudo cp *.so /usr/libexec/httpd
        				
      5. Make a link to mod because Tomcat expects it to live elsewhere:
        					sudo ln -sf /usr/libexec/httpd/mod_jk.so /usr/libexec/mod_jk.so
        				
      6. Clean up the leftovers from your build, BUT make sure you are still in the tomcat source directory.:
        					cd /Users/deep/Documents/Downloads/jakarta-tomcat-3.2.1-src/src/native/apache1.3/
        					rm *.o
        				
    Many Many Many thanks to Murray Todd Williams for his article on how to do this.


  10. Now simply add some Apache configuration to Tomcat's server.xml file. Open /Applications/Tomcat/conf/server.xml in a text editor. Find the part that says:
    	
    		<!-- Apache AJP12 support. This is also used to shut down tomcat. -->
    		<Connector className="org.apache.tomcat.service.PoolTcpConnector">
    			<Parameter name="handler"  value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
    			<Parameter name="port" value="8007"/>
    		</Connector>
    	
    and add this after it:
    		<!-- Apache AJP13 support. Use for mod_jk rather than mod_jserv -->
    		<CONNECTOR CLASSNAME="org.apache.tomcat.service.PoolTcpConnector">
    			<PARAMETER NAME="handler" VALUE="org.apache.tomcat.service.connector.Ajp13ConnectionHandler"/>
    			<PARAMETER NAME="port" VALUE="8009"/>
    		</CONNECTOR>
    	

  11. Finally, add the Tomcat reference to Apache's configuration file httpd.conf file. Open /private/etc/httpd/httpd.conf in a text editor. At the end add the following lines:
    # Changed by <your initials here> on <today's date>
    Include /Applications/Tomcat/conf/mod_jk.conf-auto
    	

  12. Now test your Tomcat/Apache installation.
    1. First restart Tomcat:
      			$TOMCAT_HOME/bin/shutdown.sh
      			$TOMCAT_HOME/bin/startup.sh
      			
    2. Then restart Apache:
      			sudo /usr/sbin/apachectl restart
      			
    3. Test by going to http://localhost/examples. You should see a directory listing for the Tomcat directory. links to JSP & Servlet examples. Click on the servlets link or the jsp link & you should find the same examples you found when you ran Tomcat as a standalone above.

  13. You are done.

  14. I also recommend Richard Laing's helpful GUI Tomcat launcher TomcatX. It allows you to run Tomcat without having to open up a command line & it integrates well with Apache.



Amandeep Jawa  Worker Bee Software