Hyrax - Apache Integration: Difference between revisions
No edit summary |
|||
Line 24: | Line 24: | ||
---- | ---- | ||
==Install Hyrax== | ==Install Software Components== | ||
===Install Hyrax=== | |||
Install Hyrax as described in the [[Hyrax - Installation Instructions | installation instructions]]. No matter how you want things to end up you have to do this first. | Install Hyrax as described in the [[Hyrax - Installation Instructions | installation instructions]]. No matter how you want things to end up you have to do this first. | ||
==Install mod_jk== | ===Install mod_jk=== | ||
'''Before proceeding make sure you have installed the ''mod_jk'' library in your Apache ''modules'' directory.''' | '''Before proceeding make sure you have installed the ''mod_jk'' library in your Apache ''modules'' directory.''' | ||
[http://tomcat.apache.org/connectors-doc/index.html | Please read and follow the [http://tomcat.apache.org/connectors-doc/index.html Apache instructions to install mod_jk] into your instance of Apache. | ||
===Install mod_rewrite=== | |||
Depending on your Apache installation you may need to rebuild/compile Apache to enable ''rewrite''. You should first look at the ''http.conf'' configuration file. Find the ''LoadModule'' directives and look for the lines that load the proxy and rewrite modules. They should look something like this: | |||
Depending on your Apache installation you may need to rebuild/compile Apache to enable ''rewrite | |||
LoadModule rewrite_module modules/mod_rewrite.so | LoadModule rewrite_module modules/mod_rewrite.so | ||
If you see the | If you see the module loaded then you're set to go, skip to the next section. | ||
If not then you will probably need to compile Apache from source and enable the rewrite and proxy modules. | If not then you will probably need to compile Apache from source and enable the rewrite and proxy modules. | ||
Line 47: | Line 46: | ||
#(Re)compile. | #(Re)compile. | ||
#(Re)install. | #(Re)install. | ||
---- | |||
---- | |||
==Configure mod_jk== | |||
The Apache Tomcat Connector (aka mod_jk) has a large list of features (such as load balancing options) that are beyond the scope of this discussion. We will review a simple configuration to get things started. | |||
===workers.properties file === | |||
Mod_jk uses a '''workers.properties''' file that defines the workers that are connecting to Tomcat. Here is a minimum example of a workers.properties file for Hyrax: | |||
# Define 1 real worker | |||
worker.list=hyrax | |||
# | |||
# Set properties for hyrax worker | |||
# | |||
# Define it as an AJP1.3 protocol worker. | |||
worker.hyrax.type=ajp13 | |||
# Hostname or IP address for the tomcat instance that is running Hyrax | |||
worker.hyrax.host=localhost | |||
#Define the port for the AJP connector for the Tomcat instance | |||
worker.hyrax.port=8009 | |||
The workers.properties can be placed anywhere on the Apache host system, but is typically located in ''/etc/httpd/conf/workers.properties'' | |||
== | === httpd.conf === | ||
''' | |||
Once you have saved the workers.properties file you will need to edit the Apache configuration, http.conf. The httpd.conf file is typically located in one of: | |||
* /etc/httpd/conf/ | |||
* /etc/httpd2/conf/ | |||
* /usr/local/apache/conf/ | |||
* /etc/apache2/ (on my OS-X 10.5 system) | |||
At the bottom of '''httpd.conf''' you will need to add the following, localized to you specific system: | |||
# Load mod_jk module. This location was determined when you installed mod_jk | |||
LoadModule jk_module ''location/of/''mod_jk.so | |||
# Where to find workers.properties | |||
JkWorkersFile /etc/httpd/conf/mod_jk/workers.properties | |||
# Where to put jk shared memory | |||
JkShmFile /var/log/httpd/mod_jk.shm | |||
# Where to put jk logs | |||
JkLogFile /var/log/httpd/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] " | |||
# Send servlet for context /examples to worker named worker1 | |||
JkMount /opendap* hyrax | |||
*You may not need to the line: | |||
:: <tt>LoadModule jk_module ''location/of/''mod_jk.so''</tt> | |||
:If it already exists elsewhere in httpd.conf | |||
* The last line of the ''mod_jk'' configuration: | |||
JkMount /opendap/* hyrax | |||
: Maps all incoming requests whose local URL matches '''opendap/*''' to the ''hyrax'' worker defined in the '''workers.properties''' file. | |||
This should complete the configuration of mod_jk. Restart Apache (apachectl -k restart) and see if in fact hitting you Apache server at the opendap context brings you to your Hyrax service: | |||
http://my.host/opendap/ | |||
If not then you will need to trouble shoot you mod_jk installation and configuration. | |||
== Preserving old DAP/DODS data URL's == | |||
Using the APache rewrite module (mod_rewrite) we can map olds data URL's that were serviced by early versions of the DAP server to the new Hyrax installation. | |||
=== mod_rewrite === | |||
'''Advice''': ''If you are not familiar with Apache [http://httpd.apache.org/docs/2.2/mod/mod_rewrite.html mod_rewrite] go read about it now, before you do anything else.'' | |||
Once you have Apache with | Once you have installed Apache with the ''rewrite'' module (*mod_rewrite) enabled you will need to edit Apache's httpd.conf file. Add the following lines: | ||
<pre> | <pre> | ||
# Enable the rewrite module | # Enable the rewrite module | ||
RewriteEngine on | RewriteEngine on | ||
# Target it's logging somewhere useful | # Target it's logging somewhere useful | ||
RewriteLog / | RewriteLog /var/log/httpd/rewrite.log | ||
# Turn on logging (Set to 0 to disable) | # Turn on logging (Set to 0 to disable) | ||
RewriteLogLevel 2 | RewriteLogLevel 2 | ||
# Uses a reverse proxy to enable mapping old OPeNDAP URL's to Tomcat. | # Uses a reverse proxy to enable mapping old OPeNDAP URL's to Tomcat. | ||
RewriteRule ^/cgi-bin/nph-dods(.*) | RewriteRule ^/cgi-bin/nph-dods(.*) /opendap/$1 [P] | ||
</pre> | </pre> | ||
Revision as of 19:55, 22 June 2010
Request for Alternate Solutions: If these suggestions work for you then we are all happy. If you have a better method for achieving the same or similar goals then we would love to hear about it. If you're stuck and can't figure out how to achieve your goals, get in touch and I will try to help. - ndp (ndp at opendap dot org) Or email the OPeNDAP tech support list (opendap-tech at unidata dot ucar dot edu); see mail lists for information about the list.
Overview
If you are not concerned about the URL's for your data changing when you install tHyrax, then just run Tomcat as a standalone server. It can even be configured to operate on port 80, just like Apache. If however you want to keep your existing data access URL's intact, read on.
Many people deploying Hyrax have been using previous versions of the OPeNDAP servers with their data. These OPeNDAP servers required the Apache web server and utilized CGI to deliver their functionality. This is no longer the case, as Hyrax is a Java servlet designed to run in conjunction with Tomcat. However many OPeNDAP administrators may wish to keep the URL hierarchies of their existing systems unchanged and simply replace their existing implementation of the OPeNDAP server with the new server. To this end Tomcat needs to be integrated with the Apache installation. The directions here offer methods for integrating Hyrax with Apache version 2.x. If you are using earlier versions of Apache (1.x or older) you might wish to consider upgrading Apache to a more current version (version 2.x really is better...), otherwise these instructions may or may not be helpful.
There are 2 basic steps to integrating Hyrax (and Tomcat) with Apache and Tomcat. The first step is to integrate Tomcat with Apache using the Apache Tomcat Connector, the second step is to map your old OPeNDAP (or even DODS) URLs to the new service using Apache rewriet module (mod_rewrite).
Tomcat must be running and listening on a port (which one depends on how you set things up) for it to interact with Apache.
mod_jk
Most discussions of integrating Tomcat and Apache start (and often end with) an Apache module called mod_jk, which allows Tomcat to work as part of Apache. However, mod_jk is generally not installed by default with Apache (while the rewrite and proxy modules are) so you will need to install mod_jk .
That said, if you want to read about how to hook this all up using mod_jk then go here.
mod_rewrite
The simplest method for integrating Tomcat with Apache while preserving preexisting URL hierarchies is to use a mod_rewrite to map your old data URL's into the new service.
Install Software Components
Install Hyrax
Install Hyrax as described in the installation instructions. No matter how you want things to end up you have to do this first.
Install mod_jk
Before proceeding make sure you have installed the mod_jk library in your Apache modules directory. Please read and follow the Apache instructions to install mod_jk into your instance of Apache.
Install mod_rewrite
Depending on your Apache installation you may need to rebuild/compile Apache to enable rewrite. You should first look at the http.conf configuration file. Find the LoadModule directives and look for the lines that load the proxy and rewrite modules. They should look something like this:
LoadModule rewrite_module modules/mod_rewrite.so
If you see the module loaded then you're set to go, skip to the next section.
If not then you will probably need to compile Apache from source and enable the rewrite and proxy modules.
- Make sure you have the Apache source.
- Run the Apache configure script with the --enable-rewrite and --enable-proxy switches. Minimally your configure command should look like this:
./configure --enable-rerwrite --enable-proxy
- (Re)compile.
- (Re)install.
Configure mod_jk
The Apache Tomcat Connector (aka mod_jk) has a large list of features (such as load balancing options) that are beyond the scope of this discussion. We will review a simple configuration to get things started.
workers.properties file
Mod_jk uses a workers.properties file that defines the workers that are connecting to Tomcat. Here is a minimum example of a workers.properties file for Hyrax:
# Define 1 real worker worker.list=hyrax # # Set properties for hyrax worker # # Define it as an AJP1.3 protocol worker. worker.hyrax.type=ajp13 # Hostname or IP address for the tomcat instance that is running Hyrax worker.hyrax.host=localhost #Define the port for the AJP connector for the Tomcat instance worker.hyrax.port=8009
The workers.properties can be placed anywhere on the Apache host system, but is typically located in /etc/httpd/conf/workers.properties
httpd.conf
Once you have saved the workers.properties file you will need to edit the Apache configuration, http.conf. The httpd.conf file is typically located in one of:
- /etc/httpd/conf/
- /etc/httpd2/conf/
- /usr/local/apache/conf/
- /etc/apache2/ (on my OS-X 10.5 system)
At the bottom of httpd.conf you will need to add the following, localized to you specific system:
# Load mod_jk module. This location was determined when you installed mod_jk LoadModule jk_module location/of/mod_jk.so # Where to find workers.properties JkWorkersFile /etc/httpd/conf/mod_jk/workers.properties # Where to put jk shared memory JkShmFile /var/log/httpd/mod_jk.shm # Where to put jk logs JkLogFile /var/log/httpd/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] " # Send servlet for context /examples to worker named worker1 JkMount /opendap* hyrax
- You may not need to the line:
- LoadModule jk_module location/of/mod_jk.so
- If it already exists elsewhere in httpd.conf
- The last line of the mod_jk configuration:
JkMount /opendap/* hyrax
- Maps all incoming requests whose local URL matches opendap/* to the hyrax worker defined in the workers.properties file.
This should complete the configuration of mod_jk. Restart Apache (apachectl -k restart) and see if in fact hitting you Apache server at the opendap context brings you to your Hyrax service:
http://my.host/opendap/
If not then you will need to trouble shoot you mod_jk installation and configuration.
Preserving old DAP/DODS data URL's
Using the APache rewrite module (mod_rewrite) we can map olds data URL's that were serviced by early versions of the DAP server to the new Hyrax installation.
mod_rewrite
Advice: If you are not familiar with Apache mod_rewrite go read about it now, before you do anything else.
Once you have installed Apache with the rewrite module (*mod_rewrite) enabled you will need to edit Apache's httpd.conf file. Add the following lines:
# Enable the rewrite module RewriteEngine on # Target it's logging somewhere useful RewriteLog /var/log/httpd/rewrite.log # Turn on logging (Set to 0 to disable) RewriteLogLevel 2 # Uses a reverse proxy to enable mapping old OPeNDAP URL's to Tomcat. RewriteRule ^/cgi-bin/nph-dods(.*) /opendap/$1 [P]
Assuming that your old OPeNDAP server was accessed via http://your.server/cgi-bin/nph-dods/ this will map it to the Hyrax servlet running in the Tomcat engine on the same system as your Apache server and listening on port 8080. You will need both of the RewriteRule directives, although you will probably tailor the first one to suit your previous server configuration, the second one should be as shown here. If you used Alias or AliasMatch with your old server, add more RewriteRule directives to get that same behavior.
Note: If you have AddEncoding directives in your Apache configuration, those will likely need to be replaced with AddType. If present, the AddEncoding directives will cause Apache 2.x to report that any page, such as the HTML form interface, is compressed, even though it is not. This problem can be very hard to track down.
# AddEncoding allows you to have certain browsers uncompress # information on the fly. Note: Not all browsers support this. # Despite the name similarity, the following Add* directives have nothing # to do with the FancyIndexing customization directives above # # AddEncoding x-compress .Z # AddEncoding x-gzip .gz .tgz # # If the AddEncoding directives above are commented-out, then you # probably should define those extensions to indicate media types: # AddType application/x-compress .Z AddType application/x-gzip .gz .tgz
Restart Apache (assuming Tomcat is already running) and you should be on your way.