Update: It’s been said that this howto will also work for Tomcat 6. I’ve not tested it, but I’d assume it would work considering the manual aspects of the installation and the unlikely event that Tomcat 6 would’ve changed its directory structure considerably. If you find evidence to the contrary, please let me know.
This HowTo explains the installation and configuration of Apache 2.2.3, Tomcat 5.5.25 and the Apache Jakarta module — a connector/proxy for Apache & Tomcat — under Debian Etch. It is geared towards those who already have experience configuring Apache and Tomcat and are aware of the basic principles behind Apache modules.
A working installation of Debian GNU/Linux that has an internet connection, or valid CD-ROM apt packages disc.
Step 1: Installing Apache
If you don’t already have Apache installed, you will need to run the following in a shell as root:
|apt-get install apache2|
This will install Apache 2 and any relevant dependencies. Configuration files for Apache can be found under /etc/apache2, and host-specific configuration are found under /etc/apache2/sites-available/. This is where you should configure your individual Virtual Hosts, as opposed to placing the configuration in /etc/apache2/apache2.conf.
Step 2: Install mod_jk
Using apt, you need to install the Apache Jakarta module by executing the following in a shell as root:
|apt-get install libapache2-mod-jk|
The module may need enabling via ‘a2enmod jk’, but it is not necessary at this time. Go ahead and execute the following as root:
Running the above should return a message similar to ‘Module enabled, now run /etc/init.d/apache2 force-reload’. I do not recommend reloading Apache’s configuration until everything has been installed and setup. This will ensure Apache remains usable while you setup Tomcat in the next step.
Step 3: Download and Extract Apache Tomcat 5.5.25
There’s a reason I installed Tomcat manually: Debian’s Tomcat package is a mess. The default package splits, amongst others, the webapps and conf folders. Whilst the conf folder is situated in a respectable location (/etc/tomcat5), the webapps directory is symlink’d under /var/, which tends to cause problems with Apache->Tomcat configuration. Therfore, I have chosen to manually install Tomcat using the .tar.gz from tomcat.apache.org; as well as this being a recommendation from various people in the #tomcat channel on irc.freenode.net. In short, it’s a configuration and administration nightmare.
Download Apache Tomcat 5.5.25 from here: http://tomcat.apache.org/download-55.cgi (select a mirror) and extract it to one of the following locations (I used /usr/share/):
To do the above, execute these commands as root:
|mv apache-tomcat-5.5.25.tar.gz /usr/share/; cd /usr/share
tar zxvf apache-tomcat-5.5.25.tar.gz; mv apache-tomcat-5.5.25 tomcat-5.5.25
Now, let’s setup a user and group so we can provide safe permission control over the conf and webapps directories.
Step 4: Add a tomcat user and group
|adduser tomcat && addgroup tomcat; cd /usr/share/tomcat-5.5.25|
We’ve just created the tomcat user & group, so let’s apply the ownership permissions to the webapps directory:
|chown -R tomcat:tomcat webapps; chmod -R 775 webapps|
This now means that any user who’s in the tomcat group can read, write and execute files under the webapps directory.
Note: if you use a specific user and group such as www-data for Apache ownership and execution, which is the default in Debian, you will need to add ‘tomcat’ to the www-data user’s groups:
|usermod -aG tomcat www-data|
The following is optional, as it sets the group permissions of the server.xml to writable by the tomcat group. This may not be what you want, so be careful!
|cd conf; chmod g+w server.xml|
Now that we’ve setup the most important directories, let’s make the tomcat startup and shutdown bash scripts executable, ready for starting it up:
|cd /usr/share/tomcat-5.5.25/bin/; chmod 755 shutdown.sh startup.sh|
Step 4: Create the workers.properties File
Create the following file, as root, under /etc/apache2 or a directory of your choice (/usr/share/tomcat-5.5.25/conf would also be fine), but make sure it’s readable by the tomcat user and/or group.
# This file provides minimal jk configuration properties needed to
# connect to Tomcat.
# We define a worker named ‘default’
The ‘worker.list’ parameter defines the names for the ajp13 connector(s). This is what Apache talks to. You can specify a name of your choice, but make sure you remember it for later, and ensure you’ve changed all parameters beginning with ‘worker.default’ to the name you’ve set.
Step 5: Configure an Apache to Talk To Tomcat and add a Virtual Host
This step is the most important part. It assumes that you’re using virtual hosts for Apache (you may not be), so if that isn’t the case, just place the JkMount configuration lines in the Virtual Host section along with the config. below in your main apache file (/etc/apache2/apache2.conf).
|# mod_jk config
# Where to find workers.properties
JkWorkersFile /etc/apache2/workers.properties# Where to put jk logs
JkLogFile /var/log/apache2/jk.log# Set the jk log level [debug/error/info]
JkLogLevel info# Select the log format
JkLogStampFormat “[%a %b %d %H:%M:%S %Y] “#JkOptions indicate to send SSL KEY SIZE,
JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories# JkRequestLogFormat set the request format
JkRequestLogFormat “%w %V %T”
For my virtual host, I created the following configuration file under /etc/apache2/sites-available:
JkMount /* default
JkMount /*.jsp default
DirectoryIndex index.jsp index.html
# Globally deny access to the WEB-INF directory
deny from all
The most important lines in the above quote are the following:
|JkMount /* default
JkMount /*.jsp default
These two lines specify the URL paths that should be handed to mod_jk and thus Tomcat. The ‘default’ section of the line specifies the JK worker identifier. This must match the name you specified in the workers.properties file!
That’s the configuration done, let’s fire this baby up!
Step 5: Unleashing the Beast; Starting Apache & Tomcat
To ensure a clean start up, I recommend stopping Apache entirely, and then starting up Tomcat, then Apache. Do so by executing the following commands (as root, see the note blow otherwise)::
Note: if you want tomcat to run as a separate user but keep ownership as root, use jsvc and the -user flag to specify the user it should change to at startup.
Both Tomcat and Apache should startup without error, and you should now be able to connect to Apache and the Tomcat via the specified Virtual Host.