Tomcat, XAMPP, and mod_jk
I recently upgraded to Snow Leopard (more on that later, it did not go so smoothly), and decided that rather than simply port my existing web development stack (which was rickety), I would try to build something clean and new that has all the features I need without eating all my available system resources.
My primary goal was to distance myself as much as possible from OS X’s flawed *AMP stack. Why flawed? Well, out-of-the-box, OS X doesn’t have MySQL, so you have to download, install, and manage that separately—a small pain in the ass, but a pain in the ass nonetheless. Further, the OS X compile of PHP is unnecessarily hobbled by a lack of image manipulation modules and is a missing the PDO module for MySQL. The last time I checked, it’s impossible to recompile PHP for OS X 10.5, which means that image manipulation is right out and installing PDO becomes far more difficult. I spent a weekend wrestling with recompiling MySQL with development headers just so I could build the PDO module for OS X and plug it in. Without PDO, my PHP object-relational mapper of choice (Doctrine PHP) simply won’t work.
My secondary goal is to have something that handles Tomcat Java server gracefully. In the past, I’ve spent a lot of time futzing about with settings to make Tomcat less of a resource-devouring monster, as well as integrating it more seamlessly with my local development environment. In general, I don’t appreciate appending a port number to the end of my URLs, and starting every new Java project with localhost:8080 seems like getting started with the wrong foot forward.
The tool to glue Apache and Tomcat together is mod_jk, a module that allows you to virtual host Tomcat webapps on your Apache server. I’ve played around with loading it with the OS X version of Apache in the past, but I never really got it working on my mac before. There was always one more configuration thing I was missing before I gave up and got back to doing real work.
In the past, I’ve been very impressed by the XAMPP project for OS X. It’s a simple drop-in replacement for the boxed OS X *AMP stack and it has almost every module I could ever want for web development. It comes with its own installation of MySQL, and both can be managed with a simple-but-robust control panel or a variety of shell scripts. Further, the files are laid out very simply in the xamppfiles directory, which makes it easy to find the configuration or log file that I’m looking for. It also means that if I want to get rid of XAMPP, I can be reasonably sure that it will be gone when I delete it from my Applications directory. Strangely, knowing I can cleanly delete a piece of software gives me confidence that it will operate correctly while it’s installed.
So, having settled on gluing XAMPP together with Tomcat via mod_jk, I set about downloading, installing, and stabbing at configuration files madly. The first thing I did was install XAMPP, which can be found at the Apache Friends OS X page, and the latest version of Tomcat, which can be found at the Tomcat Project page.
Tomcat
Tomcat comes in a tarball, which I extracted in my Downloads folder. I then kicked open Terminal and ran the following:
cd Downloads
mv Downloads/apache-tomcat-6.0.20 Tomcat
sudo mv Tomcat /Library/
Which places my Tomcat home directory in a place that’s easy to access when installing new webapps (new webapps will go in /Library/Tomcat/webapps). I also dragged the webapps directory into my sidebar for easy access. I then updated the tomcat-users.xml file in /Library/Tomcat/conf/ to allow me access to the Tomcat manager:
<tomcat-users>
<role rolename="manager" />
<user username="tomcat" password="admin" roles="manager" />
</tomcat-users>
I can now log into the manager app with username/password of tomcat/admin. You should probably pick something else, as I eventually did.
After that, I had to make sure the startup and shutdown scripts that Tomcat uses were executable. I also removed the scripts written for other platforms that I wouldn’t be using:
cd /Library/Tomcat/bin
rm *.bat *.exe
The next step is to write a more-robust startup/shutdown script. I wrote a simple shell script that’s accessible to me wherever I am that allows me to start and stop Tomcat quickly. In /usr/local/bin I added a file called tomcat and gave it executable privileges and opened my favorite text editor and added this inside it:
#!/bin/bash
case $1 in
start)
growlnotify -t "Tomcat" -m "Tomcat is starting up."
/Library/Tomcat/bin/startup.sh
;;
stop)
growlnotify -t "Tomcat" -m "Tomcat is shutting down."
/Library/Tomcat/bin/shutdown.sh
;;
restart)
growlnotify -t "Tomcat" -m "Tomcat is restarting."
/Library/Tomcat/bin/shutdown.sh
/Library/Tomcat/bin/startup.sh
;;
*)
echo "Usage: tomcat [ start | stop | restart ]"
;;
esac
Note the calls to growlnotify. If you have Growl installed and went out of your way to install the extras, you can call growlnotify on the command line to fire off an attractive growl notification. This is very handy if you want to embed calls to startup and shut down in other scripts (I often write a build script for java projects that shuts down Tomcat, installs the webapp, then starts Tomcat again). You can remove these lines if you aren’t interested in that, though. Save and close when you’re done—you’ll probably need to give your admin password.
Now, from anywhere in Terminal, you can call tomcat start, tomcat stop, or tomcat restart and expect it to perform those actions properly. You can check if Tomcat is running by visiting http://localhost:8080/
mod_jk
Now we have XAMPP working, and Tomcat working, but we want them to be working together, listening on the same port, without stepping on each other’s toes. To do this, we first need to acquire and install mod_jk, configure it, and then create the proper hostfile entry.
You can download mod_jk from the Apache Tomcat Connector project page. Download the macosx version for your processor; it should be named something like mod_jk-VERSION-httpd-VERSION.so. Make sure you download the one that’s appropriate for your version of Apache; In my case, I downloaded the httpd-2.2.4 version.
Rename the .so file to mod_jk.so and place it in /Applications/XAMPP/xamppfiles/modules.
The next step is getting mod_jk configured properly. To do this, we’re going to create a new configuration file in /Applications/XAMPP/xamppfiles/etc/extras called httpd-modjk.conf. In it, add the following:
LoadModule jk_module modules/mod_jk.so
<IfModule jk_module>
# Where to put jk shared memory
JkShmFile /Applications/XAMPP/xamppfiles/etc/mod_jk.shm
# Where to put jk logs
JkLogFile /Applications/XAMPP/xamppfiles/logs/mod_jk.log
# Set the jk log level [debug/error/info]
JkLogLevel info
# Select the timestamp log format
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
JkWorkerProperty worker.list=default
JKWorkerProperty worker.default.type=ajp13
JKWorkerProperty worker.default.host=localhost
JKWorkerProperty worker.default.port=8009
</IfModule>
NameVirtualHost *:80
<VirtualHost *:80>
ServerName tomcat
ServerAdmin root@localhost
DocumentRoot "/Library/Tomcat/webapps"
ErrorLog "logs/tomcat-error_log"
CustomLog "logs/tomcat-access_log" common
JkMount /* default
</VirtualHost>
Then, somewhere near the end of your /Applications/XAMPP/xamppfiles/etc/httpd.conf add:
Include /Applications/XAMPP/etc/extra/httpd-modjk.conf
That will load the configuration file we just created.
The final step to get this all glued together involves editing your /etc/hosts file. Open it in your favorite text editor and add the following to the end of it:
127.0.0.1 tomcat
You should now be able to start up Tomcat (using tomcat start on the command line), start Apache (with XAMPP), and browse to http://tomcat/ and see the Tomcat welcome page.
