Apache::Wombat

Apache::Wombat is a connector for the Wombat servlet engine that embeds the engine in an Apache web server built with mod_perl.

This guide will help you quickly get Wombat installed, configured and running for the purposes of demonstration. It is not a user manual for Wombat (one of those is forthcoming). It assumes intermediate to advanced knowledge of building and configuring Apache, mod_perl, and CPAN modules.

Questions? Join the wombat-users@lists.sourceforge.net mailing list and send them to us.

The master versions of these documents are located at http://wombat.sourceforge.net/apache/.

Installation Instructions

Make sure you have at least version 5.6.0 of perl.
Make sure you have built mod_perl with Apache. Apache 1.3.0 is required. Any recent version of mod_perl will do). mod_perl must be built with the following hooks enabled:
- PERL_CHILD_INIT (enabled by default)
- PERL_CHILD_EXIT (enabled by default)
- PERL_TABLE_API
- PERL_METHOD_HANDLERS
Obviously the easy way is to build with EVERYTHING.
Install Apache::Wombat. This will catch all of the non-optional dependencies, including libservlet and Wombat (you will still have to install dependencies for optional components, such as DBI for DBIRealm, separately):
```
$ perl -MCPAN -e 'install Apache::Wombat'
```
The build process will ask you some questions about your installation preferences. You can simply hit enter to accept the defaults. You can also use '.' to refer to the current working directory (the directory from which you ran Makefile.PL) and '~' to refer to your home directory.
- Installation directory: This is where the Apache::Wombat modules will be installed. The default is the normal perl site library directory. If you specified a PREFIX when you built mod_perl, you might like to use the same value here.
- Apache config directory: This is where generated config files will be installed.
- Apache log directory: This is where the wombat.log file will be written, if you enable the Apache::Wombat::FileLogger module (not enabled by default).
- Webapps directory: This is where Wombat will look for your web applications.
The below instructions assume you made the following choices:
- Installation directory: /usr/local/apache
- Config directory: /usr/local/apache/conf
- Log directory: /usr/local/apache/logs
- Webapps directory: /usr/local/apache/webapps

Install the wombat-webapps package into the webapps directory you just specified.

$ cd /usr/local/apache/webapps
$ lwp-download http://prdownloads.sourceforge.net/wombat/wombat-webapps.tar.gz
$ tar xzvf wombat-webapps.tar.gz

Add an Include directive to httpd.conf to include the generated wombat.conf file.
```
Include /usr/local/apache/conf/wombat.conf
```
If you installed Apache::Wombat into a non-standard location, add that location to $PERL5LIB in your environment.
```
$ export PERL5LIB=/where/my/libs/are:$PERL5LIB
```

Now you should be able to start Apache. You should see something like this printed to the console:

[Thu Oct 25 18:20:37 2001] [info] [28898] Engine[Apache-Wombat]: StandardSessionManager started
[Thu Oct 25 18:20:37 2001] [info] [28898] Engine[Apache-Wombat]: ApacheConnector[Apache/mod_perl Connector]: Apache/mod_perl Connector started
[Thu Oct 25 18:20:37 2001] [info] [28898] Engine[Apache-Wombat]: ApacheConnector[Apache/mod_perl Connector]: Apache/mod_perl Connector started
[Thu Oct 25 18:20:37 2001] [error] [28898] Engine[Apache-Wombat]: Wombat/0.7.0 configured -- resuming normal operations

Point your browser at /wombat-examples and begin viewing the examples.
At this point you can start customizing the configuration. For reference, use the following documents:
- Apache::Wombat man page (Apache config info)
- Wombat man page (Wombat and webapp config info)
- Wombat optional components man pages (Wombat config info)
- generated wombat.conf and server.xml
- Java (TM) Servlet 2.3 Specification (webapp config info)
Use the Examples application as a template for your own applications. The web.xml deployment descriptor located in the WEB-INF application resource directory is essential. Refer to the Java (TM) Servlet Specification for a discussion of the contents of web.xml and the Wombat man page for a list of supported elements and features.

Good luck and have fun!