User Guide - Tomcat with mod_jk and mod_proxy_ajp

  1. Portal Home
  2. Knowledgebase
  3. User Guide - Tomcat with mod_jk and mod_proxy_ajp

Applicable Plans: Standard Plus VPS, Standard Max VPS, all Advanced VPS, all Premier VPS (not for Plesk or cPanel users)

Tomcat User Guide - Deployment with mod_jk and mod_proxy_ajp

“Tomcat is the servlet container that is used in the official Reference Implementation for the Java Servlet and Java Server Pages technologies. The Java Servlet and Java Server Pages specifications are developed by Sun under the Java Community Process.- From the Apache Software Foundation Website”
http://tomcat.apache.org/index.html

The eApps Hosting service is designed to make it easy to use Tomcat for serving dynamic content in your Virtual Private Server (VPS). This User Guide is not intended as a reference source for Tomcat. See the Links to other information at the end of this document if you need detailed information about Tomcat.

The purpose of this User Guide is to explain how to deploy your Tomcat application in your VPS on the eApps Hosting service using either mod_jk or mod_proxy_ajp. Instructions on how to deploy Tomcat applications in Standalone mode are found here.

The information in this User Guide is based on the assumption that you have already read the Tomcat User Guide – Installation and Tuning, and have met all the Prerequisites. If you have not read that User Guide, please do so now. Reading and following that User Guide is the key to success with the information in this User Guide.
Information covered the the Installation and Tuning User Guide, such as how to deploy your applications to the VPS and how to configure Tomcat, is not covered in this User Guide.

If you follow the guidelines explained in this User Guide you will remain safely inside the eApps Support boundaries. If you choose to use a custom configuration that is outside of the guidelines contained in this document, you may be subject to service fees if you need assistance from the eApps Support department. If you have any questions about this User Guide please contact support@eapps.com for assistance.

If you are a JBoss user, please do not use this Guide. Refer to the JBoss User Guide instead. Tomcat is bundled with JBoss and as such the User Guide for JBoss includes information to configure Tomcat.

Apache as a front end to Tomcat using mod_jk 

mod_jk syntax overview 

Examples using mod_jk 

Deployment with Tomcat serving JSP and Servlets, Apache serving all other content 
Deployment with Tomcat serving JSP and Servlets using a WAR file, Apache serving all other content 
Deployment with Tomcat serving JSP and Servlets, bypassing Apache by default 
Deployment with multiple applications using Tomcat 

Apache as a front end to Tomcat using mod_proxy_ajp (CentOS 5 only) 
Examples using mod_proxy_ajp 

Deployment with Tomcat serving JSP and Servlets, Apache serving all other content 
Deployment with Tomcat serving JSP and Servlets using a WAR file, Apache serving all other content 
Deployment with Tomcat serving JSP and Servlets, bypassing Apache by default 
Deployment with multiple applications using Tomcat 

Links to other information



Apache as a front end to Tomcat using mod_jk

mod_jk is used to forward requests from Apache to Tomcat. Apache runs securely on port 80, and Tomcat runs securely on port 8080. This means that by default, the URL of your application will either be http://example.com:8080 or http://example.com:8080/webapp. With mod_jk, you are able to run Tomcat securely on port 8080 and have Apache forward requests to Tomcat. This eliminates the 8080 from the URL.

As a reminder, make sure that mod_jk is installed. You can verify this from the Control Panel, System Tab, All Applications.

In this User Guide, remember to substitute TomcatX or tomcatX with your version of Tomcat, and example.com with your actual domain name.

When mod_jk is installed, default directives are created in /etc/httpd/conf.d/mod_jk.conf or in /etc/httpd/conf/httpd.conf depending on the version of mod_jk installed. These are the default mod_jk directives:

JkMount /*.jsp ajp13
JkMount /*.do ajp13
JkMount /manager* ajp13
JkMount /admin* ajp13
JkMount /web-console*

You must also specify mod_jk directives for your application in the Custom Settings tab for each website you create that uses Tomcat. Custom Settings is found in the Website Settings link for each site listed in the Site Tab of the Control Panel. Click on Edit to add your mod_jk directives, and then Update to save them.

mod_jk also offers no-jk directives, which allow requests for certain applications, such as Open Webmail or Awstats to bypass Tomcat so they can be served directly by Apache. The no-jk directives are also added to the Custom Settings tab for each site. Examples of no-jk directives are given as part of the mod_jk examples in the deployment examples that follow.

NOTE – if you add mod_jk directives for your application manually to the /etc/httpd/httpd.conf file, your changes WILL be over written by the Control Panel. This is a function of how the Control Panel software works, and cannot be changed. Please add all mod_jk directives for your applications to the Custom Settings tab for your site.

mod_jk syntax overview

The standard format for a mod_jk directive is:
JkMount /servlet/* ajp13
  • JkMount – this is the JkMount directive that calls mod_jk
  • /servlet/* - this is the regular expression(regex) that is matched in the referring URL and is passed to the servlet container. Typically, this is the only part of a JkMount directive you will change
  • ajp13 – this is the internal handler that will receive the request. Unless you are a very advanced user you will never change this part of the directive. eApps only supports the ajp13 handler.
The above directive will pass all URLs with a suffix of /servlet/ to the ajp13 handler and the request will be handled by Tomcat. A URL with a suffix of /mail will still be handled by Apache.

Examples using mod_jk

Deployment with Tomcat serving JSP and Servlets, Apache serving all other content

This deployment example assumes that you are serving your Tomcat application from the Apache DocumentRoot for example.com, and that the files are NOT packaged as a WAR file.

Remember to substitute TomcatX or tomcatX with your version of Tomcat, and example.com with your actual domain name.

  • server.xml - add the following Host block just below the last closing </Host> tag in your /opt/tomcatX/conf/server.xml file. This will serve your application at http://example.com and http://www.example.com
<Host appBase="/home/webadmin/example.com" name="example.com" unpackWARs="true" autoDeploy="true">
<Alias>www.example.com</Alias>
<Context path="" docBase="html" debug="0" reloadable="true"/>
<Logger className="org.apache.catalina.logger.FileLogger" prefix="example.com." suffix=".txt" timestamp="true"/>
</Host>

  • mod_jk directives - the default directives are sufficient. No additional directives need to be added for this example.

Deployment with Tomcat serving JSP and Servlets using a WAR file, Apache serving all other content

This deployment example assumes you are serving a WAR file from the Apache DocumentRoot directory for example.com.

Remember to substitute TomcatX or tomcatX with your version of Tomcat, and example.com with your actual domain name.

  • server.xml – this example uses a mywebapp.war file that will be extracted inside /home/webadmin/example.com/html – add the following Host block just below  the last closing </Host> tag in your /opt/tomcatX/conf/server.xml file. This will serve your application at http://example.com and http://www.example.com
<Host appBase="/home/webadmin/example.com/html" name="example.com" unpackWARs="true" autoDeploy="true">
<Alias>www.example.com</Alias>
<Context path="" docBase="mywebapp" debug="0" reloadable="true"/>
<Logger className="org.apache.catalina.logger.FileLogger" prefix="example.com." suffix=".txt" timestamp="true"/>
</Host>

  • mod_jk directives - the default directives are sufficient. No additional directives need to be added for this example.

Permissions

Tomcat will need to have access to the Apache document root, so it must be added to the group that owns the DocumentRoot of the site. In these examples that is the webadmin group, your actual group may be different. Please adjust accordingly. Here is how to add the tomcat user to the webadmin group, using either the Control Panel or the command line.

Using the Control Panel
Login to your Control Panel, and click on the System Tab. If necessary, click the Select Another System (Subscription) link on the left and choose the correct Virtuozzo container.

Go to Users and Groups, and click on Users. Find the tomcat user in this list, and click on that user. In the next screen, in the Group Membership section, find webadmin, click on it, then on the ‘>>’ radio button to move it into Selected secondary groups. Then click Update on the bottom right.

Next, click on the System Tab again, and then on File Manager. Navigate to the home directory, then to the webadmin directory, then to the example.com directory. Click the check box next to the html directory, and then click the Properties link just above the directory listing. In the Permissions section, check the box for Write in the Group row, and then click OK.

Using the Command line
Note – this assumes you are logged into the VPS via SSH as the root user

[root@example]# cd /home/webadmin/example.com/
[root@example webadmin]# usermod -G webadmin tomcat
[root@example webadmin]# chmod 775 /home/webadmin/example.com/html

Apache Directory Index

The webapp directory that is expanded from the webapp.war file will need to be the DirectoryIndex for the site. In the Website Settings for the example.com site, add this line to the Custom Settings tab
DirectoryIndex /mywebapp

Deployment with Tomcat serving JSP and Servlets, bypassing Apache by default

This deployment example assumes you are serving either a WAR file or JSP files from the default Tomcat directory, not from the Apache DocumentRoot directory. This is the most common setup.

To keep an application restricted to a specific domain, you must create a directory below the Tomcat webapps directory specifically for that domain. This directory will then be the appBase for the Host in server.xml. The directory can either be created from the Control Panel or the command line.

Using the Control Panel
Login to your Control Panel, and click on the System Tab. If necessary, click the Select Another System (Subscription) link on the left and choose the correct Virtuozzo container.

Click on File Manager, and navigate to the opt directory, and then to the tomcatX directory (where X is the version of tomcat installed) and then to the webapps directory. Click the Make Directory icon near the top of the screen. Enter your directory name – you should use the name of your domain to keep things organized, but you can use any name you wish. In this example we are using example.com. Keep the default permissions, and then click OK. This takes you back one screen, and now the new directory is created.

Now the new directory has to have the correct owner and group. Click the check box next to the new directory, and then click on the Properties link just above the directory listing. In the Ownership section, select tomcat from the drop down menu for both Owner and Group. Then, click OK.

Using the Command line
Note – this assumes you are logged into the VPS via SSH as the root user

[root@example]# cd /opt/tomcatX/webapps
[root@example webapps]# mkdir -p example.com
[root@example webapps]# chown tomcat:tomcat example.com

Upload/deploy your application files using your preferred method to the new directory. Make sure they have the correct owner and group of tomcat:tomcat and also the correct permissions. By default a directory will be 755 permissions and files will be 644 permissions.

Since the deployment of the applications is outside of the default webapps directory, each Host must have an application named ROOT in the appBase. If the application is a WAR file, the application has to be named ROOT.war. If any additional applications are deployed in this Host they can have any name except for ROOT.

Remember to substitute TomcatX or tomcatX with your version of Tomcat, and example.com with your actual domain name.

  • server.xml - add the following Host block just below the last closing </Host> tag in your /opt/tomcatX/conf/server.xml file. This will serve your application at http://example.com and http://www.example.com
<Host appBase="webapps/example.com" name="example.com" unpackWARs="true" autoDeploy="true">
<Alias>www.example.com</Alias>
<Context path="" docBase="ROOT" debug="0" reloadable="true"/>
<Logger className="org.apache.catalina.logger.FileLogger" prefix="example.com." suffix=".txt" timestamp="true"/>
</Host>

  • mod_jk directives - in this example, Apache will be bypassed and all content will be served by Tomcat. Add the following to the Custom Settings tab in Website Settings for the example.com site.
JkMount /* ajp13
# Directives to enable Apache to continue serving applications dependent on it.
SetEnvIf Request_URI "/webmail*" no-jk
SetEnvIf Request_URI "/mail*" no-jk
SetEnvIf Request_URI "/awstats*" no-jk
SetEnvIf Request_URI "/myadmin*" no-jk
SetEnvIf Request_URI "/pgadmin*" no-jk
SetEnvIf Request_URI "/cgi-bin*" no-jk
SetEnvIf Request_URI "/openwebmail*" no-jk

Note - Unless you specify no-jk directives for each non-Tomcat web application, those requests will be sent to Tomcat and your will get a 404 not found error. Depending on what other applications are trying to be served by Apache, you may need to add additional no-jk directives also.

Deployment with multiple applications using Tomcat

This example assumes you are going to serve two applications for one domain using Tomcat, a ROOT application as described in the previous example, and one called mywebapp. This also assumes you have created the directory per the previous example, and have uploaded both your applications to the new directory.

Remember to substitute TomcatX or tomcatX with your version of Tomcat, and example.com with your actual domain name.

  • server.xml – to serve two applications for the same domain, there has to be another Context added to server.xml. Using the server.xml from the previous example as a guide, add, the line in BOLD to serve the second application.

<Host appBase="webapps/example.com" name="example.com" unpackWARs="true" autoDeploy="true">
<Alias>www.example.com</Alias>
<Context path="" docBase="ROOT" debug="0" reloadable="true"/>
<Context path="/mywebapp" docBase="mywebapp" debug="0" reloadable="true"/>
<Logger className="org.apache.catalina.logger.FileLogger" prefix="example.com." suffix=".txt" timestamp="true"/>
</Host>

  • mod_jk directives – use the mod_jk directives from the previous example.

Apache as a front end to Tomcat using mod_proxy_ajp (CentOS 5 only)

Mod_proxy_ajp is an extension of the mod_proxy module that is available in Apache 2.2. The required modules are installed automatically if you have Tomcat installed and have an eApps VPS running the CentOS 5 operating system or higher version. As with mod_jk, the mod_proxy_ajp directives must be specified in Custom Settings for each site.

Examples using mod_proxy_ajp

Deployment with Tomcat serving JSP and Servlets, Apache serving all other content

This deployment example assumes that you are serving your Tomcat application from the Apache DocumentRoot for example.com, and that the files are NOT packaged as a WAR file.

Remember to substitute TomcatX or tomcatX with your version of Tomcat, and example.com with your actual domain name.

  • server.xml - add the following Host block just below the last closing </Host> tag in your /opt/tomcatX/conf/server.xml file. This will serve your application at http://example.com and http://www.example.com
<Host appBase="/home/webadmin/example.com" name="example.com" unpackWARs="true" autoDeploy="true">
<Alias>www.example.com</Alias>
<Context path="" docBase="html" debug="0" reloadable="true"/>
<Logger className="org.apache.catalina.logger.FileLogger" prefix="example.com." suffix=".txt" timestamp="true"/>
</Host>

  • mod_proxy_ajp directives - add the following to the Custom Settings tab in Website Settings for the example.com site. The order must be maintained.
RewriteEngine on
RewriteCond %{REQUEST_URI} /(.*)(\.jsp|\.do|servlet)$
RewriteRule ^/(.*) ajp://localhost/$1 [P]

Deployment with Tomcat serving JSP and Servlets using a WAR file, Apache serving all other content

This deployment example assumes you are serving a WAR file from the Apache DocumentRoot directory for example.com.

Remember to substitute TomcatX or tomcatX with your version of Tomcat, and example.com with your actual domain name.

  • server.xml - this example uses a mywebapp.war file that will be extracted inside /home/webadmin/example.com/html – add the following Host block just below  the last closing </Host> tag in your /opt/tomcatX/conf/server.xml file. This will serve your application at http://example.com and http://www.example.com
<Host appBase="/home/webadmin/example.com/html" name="example.com" unpackWARs="true" autoDeploy="true">
<Alias>www.example.com</Alias>
<Context path="" docBase="mywebapp" debug="0" reloadable="true"/>
<Logger className="org.apache.catalina.logger.FileLogger" prefix="example.com." suffix=".txt" timestamp="true"/>
</Host>

  • mod_proxy_ajp directives - add the following to the Custom Settings tab in Website Settings for the example.com site. The order must be maintained.
RewriteEngine on
RewriteCond %{REQUEST_URI} /(.*)(\.jsp|\.do|servlet)$
RewriteRule ^/(.*) ajp://localhost/$1 [P]

Permissions

Tomcat will need to have access to the Apache document root, so it must be added to the group that owns the DocumentRoot of the site. In these examples that is the webadmin group, your actual group may be different. Please adjust accordingly. Here is how to add the tomcat user to the webadmin group, using either the Control Panel or the command line.

Using the Control Panel
Login to your Control Panel, and click on the System Tab. If necessary, click the Select Another System (Subscription) link on the left and choose the correct Virtuozzo container..

Go to Users and Groups, and click on Users. Find the tomcat user in this list, and click on that user. In the next screen, in the Group Membership section, find webadmin, click on it, then on the ‘>>’ radio button to move it into Selected secondary groups. Then click Upate on the bottom right.

Next, click on the System Tab again, and then on File Manager. Navigate to the home directory, then to the webadmin directory, then to the example.com directory. Click the check box next to the html directory, and then click the Properties link just above the directoy listing. In the Permissions section, check the box for Write in the Group row, and then click OK.

Using the Command line
Note – this assumes you are logged into the VPS via SSH as the root user

[root@example]# cd /home/webadmin/example.com/
[root@example webadmin]# usermod -G webadmin tomcat
[root@example webadmin]# chmod 775 /home/webadmin/example.com/html

Apache Directory Index
The webapp directory that is expanded from the webapp.war file will need to the DirectoryIndex for the site. In the Website Settings for the example.com site, add this line to the Custom Settings tab
DirectoryIndex /mywebapp

Deployment with Tomcat serving JSP and Servlets, bypassing Apache by default

This deployment example assumes you are serving either a WAR file or JSP files from the default Tomcat directory, not from the Apache DocumentRoot directory. This is the most common setup.

To keep an application restricted to a specific domain, you must create a directory below the Tomcat webapps directory specifically for that domain. This directory will then be the appBase for the Host in server.xml. The directory can either be created from the Control Panel or the command line.

Using the Control Panel
Login to your Control Panel, and click on the System Tab. If necessary, click the Select Another System (Subscription) link on the left and choose the correct Virtuozzo container.

Click on File Manager, and navigate to the opt directory, and then to the tomcatX directory (where X is the version of tomcat installed) and then to the webapps directory. Click the Make Directory icon near the top of the screen. Enter your directory name – you should use the name of your domain to keep thing organized, but you can use any name you wish. In this example we are using example.com. Keep the default permissions, and then click OK. This takes you back one screen, and now the new directory is created.

Now the new directory has to have the correct owner and group. Click the check box next to the new directory, and then click on the Properties link just above the directory listing. In the Ownership section, select tomcat from the drop down menu for both Owner and Group. Then, click OK.

Using the Command line
Note – this assumes you are logged into the VPS via SSH as the root user

[root@example]# cd /opt/tomcatX/webapps
[root@example webapps]# mkdir -p example.com
[root@example webapps]# chown tomcat:tomcat example.com

Upload/deploy your application files using your preferred method to the new directory. Make sure they have the correct owner and group of tomcat:tomcat and also the correct permissions. By default a directory will be 755 permissions and files will be 644 permissions.

Since the deployment of the applications is outside of the default webapps directory, each Host must have an application named ROOT in the appBase. If the application is a WAR file, the application has to be named ROOT.war. If any additional applications are deployed in this Host they can have any name except for ROOT.

Remember to substitute TomcatX or tomcatX with your version of Tomcat, and example.com with your actual domain name.
  • server.xml - Add the following host just below the last closing host tag (</Host>) in your server.xml configuration file. This will serve your application at example.com and www.example.com.
<Host appBase="webapps/example.com" name="example.com" unpackWARs="true" autoDeploy="true">
<Alias>www.example.com</Alias>
<Context path="" docBase="ROOT" debug="0" reloadable="true"/>
<Logger className="org.apache.catalina.logger.FileLogger" prefix="example.com." suffix=".txt" timestamp="true"/>
</Host>

  • mod_proxy_ajp directives - add the following to the Custom Settings tab in Website Settings for the example.com site. The order must be maintained.
# Directives for eApps applications dependent on Apache
ProxyPass /webmail !
ProxyPass /mail !
ProxyPass /joomla !
ProxyPass /awstats !
ProxyPass /myadmin !
ProxyPass /cgi-bin !
ProxyPass /pgadmin !
ProxyPass /openwebmail !
# Directives for your application
ProxyPass / ajp://localhost:8009/
ProxyPassReverse / ajp://localhost:8009/

Deployment with multiple applications using Tomcat

This example assumes you are going to serve two applications for one domain using Tomcat, a ROOT application as described in the previous example, and one called mywebapp. This also assumes you have created the directory per the previous example, and have uploaded both your applications to the new directory.

Remember to substitute TomcatX or tomcatX with your version of Tomcat, and example.com with your actual domain name.
  • server.xml – to serve two applications for the same domain, there has to be another Context added to server.xml. Using the server.xml from the previous example as a guide, add, the line in BOLD to serve the second application.
<Host appBase="webapps/example.com" name="example.com" unpackWARs="true" autoDeploy="true">
<Alias>www.example.com</Alias>
<Context path="" docBase="ROOT" debug="0" reloadable="true"/>
<Context path="/mywebapp" docBase="mywebapp" debug="0" reloadable="true"/>
<Logger className="org.apache.catalina.logger.FileLogger" prefix="example.com." suffix=".txt" timestamp="true"/>
</Host>

  • mod_proxy_ajp directives – use the mod_proxy_ajp directives from the previous example.

Links to other information

Tomcat Home Page: http://tomcat.apache.org/
Load testing: http://jakarta.apache.org/jmeter/
Apache 2.2 Documentation: http://httpd.apache.org/docs/2.2/
Mod_jk Home Page: http://tomcat.apache.org/connectors-doc/
eApps mod_proxy_balancer User Guide:http://support.eapps.com/hsp/mod_proxy_balancer

  Print

Comments

Please login to comment