The odyssey of JWChat

This document serves to describe the steps to set up JWChat (a web based Jabber client), using the JabberHTTPBind servlet by the same author.
This document might be redundant, but I hope it will help new or unexperienced webmasters to get JWChat running. I will try to include the links to referenced documents whenever possible.

Note: I used Apache version 2.0.50, mod_jk 1.2.14, Tomcat 5.5.9, jabberd 1.4.2, JWChat 1.0beta2 and JabberHTTPBind 0.3. For other configurations, you will have to improvise (and use the search engines often).

Note: I wasn't able to get Erlang (necessary for ejabberd) running on Windows 2003. I would encourage you to take a look at it though, as it seems quite good.

Needed files

Apache 2 webserver
Tomcat 5.5.x
Java Runtime Machine (JRE 5.0 Update 4), necessary for Tomcat. NOTE: if want to use Tomcat for Java Server Pages (.jsp), you will need the full Java Development Kit (JDK)!
A Jabber server (in my case, jabberd 1.4.2
JWChat (go to Downloads to get the latest version)
JabberHTTPBind servlet
mod_jk 1.2.14 (right click - save as)

Conventions (or: what am I talking about?)

Apache-Dir: The directory where your Apache is installed, i.e. "C:\Program Files\Apache Group\Apache2".
Tomcat-Dir: The directory where your Tomcat is installed, i.e. "C:\Program Files\Tomcat5.5".
WebRoot: Where your webpages are kept.
Jabberd-Dir: The directory where your jabberd is installed, i.e. "C:\Program Files\JabberD".

Note: You best stop Apache, Tomcat and JabberD before changing confguration files.

Set up Apache

If needed, download and install Apache. Make sure you know where you put your website files (also called WebRoot).

Rename the mod_jk file you downloaded to "mod_jk.so" and copy it into the directory Apache-Dir\modules.

Set up Tomcat

Download and install the JRE.

Download and install Tomcat. Either keep the default port (8080) or change it to something Ok for you.
Test your Tomcat installation by trying to access it through http://localhost:your-port. You should get Tomcat's welcome page with access to the manager and other useful things.

Set up Jabberd

Download and install.

You will need a text editor that can save files in UNIX format!

Edit Jabberd-Dir\jabber.xml and replace all occurances of localhost with the name you choose for your jabber server, for example jabber.myserver.com.

If you want your jabber server to only work internally (like in an intranet), comment out the following sections:

<service id="dnsrv">
  <host/>
  <load><dnsrv>dnsrv/dnsrv.so</dnsrv></load>
  <dnsrv xmlns="jabber:config:dnsrv">
    <resend service="_jabber._tcp">s2s</resend>
    <resend>s2s</resend>
  <dnsrv>
</service>

<service id="s2s">
  <load><dialback>dialback/dialback.so</dialback></load>
  <dialback xmlns='jabber:config:dialback'>
    <ip port="5269"/>
  </dialback>
</service>

Now your jabber server will not communicate with other jabber servers.

Set up JabberHTTPBind

Unpack the .war file (WinRar can do it, or use jar). to Tomcat-Dir\webapps\JHB. The directory should look like this:

  Tomcat-Dir
  +- webapps
     +- JHB
        +- META-INF
        +- WEB-INF

Set up JWChat

Unpack the zip into a directory below your WebRoot, for example \jwchat. For now, the setup will use the files as-is, you can customize it to your needs when you know everything is working.

Configure Tomcat

In your Apache-Dir\logs directory create three empty files:

stdout.log
stderr.log
jk.shm

Copy the following workers2.properties file into your Apache-Dir\conf directory:

[logger]
level=DEBUG

[config:]
#file=${serverRoot}/conf/workers2.properties
file=Apache-Dir/conf/workers2.properties
debug=0
debugEnv=0

[uriMap:]
info=Maps the requests. Options: debug
debug=0
 
# Alternate file logger
#[logger.file:0]
#level=DEBUG
#file=${serverRoot}/logs/jk.log
 
[shm:]
info=Scoreboard. Required for reconfiguration and status with multiprocess servers
file=${serverRoot}/logs/jk.shm
size=1000000
debug=0
disabled=0
 
[workerEnv:]
info=Global server options
timing=1
debug=0
# Default Native Logger (apache2 or win32 ) 
# can be overriden to a file logger, useful 
# when tracing win32 related issues
#logger=logger.file:0

[lb:lb]
info=Default load balancer.
debug=0
 
#[lb:lb_1]
#info=A second load balancer.
#debug=0
 
[channel.socket:localhost:8009]
info=Ajp13 forwarding over socket
debug=0
tomcatId=localhost:8009
 
#[channel.socket:localhost:8019]
#info=A second tomcat instance. 
#debug=0
#tomcatId=localhost:8019
#lb_factor=1
#group=lb
#group=lb_1
#disabled=0
 
#[channel.un:/opt/33/work/jk2.socket]
#info=A second channel connecting to localhost:8019 via unix socket
#tomcatId=localhost:8019
#lb_factor=1
#debug=0
 
[channel.jni:jni]
info=The jni channel, used if tomcat is started inprocess
 
[status:]
info=Status worker, displays runtime informations
 
[vm:]
info=Parameters used to load a JVM in the server process
#JVM=C:\jdk\jre\bin\hotspot\jvm.dll
OPT=-Djava.class.path=Tomcat-Dir/bin/tomcat-juli.jar;Tomcat-Dir/bin/commons-logging-api.jar
OPT=-Dtomcat.home=${TOMCAT_HOME}
OPT=-Dcatalina.home=${TOMCAT_HOME}
OPT=-Xmx128M
#OPT=-Djava.compiler=NONE
disabled=0
 
[worker.jni:onStartup]
info=Command to be executed by the VM on startup. This one will start tomcat.
class=org/apache/jk/apr/TomcatStarter
ARG=start
disabled=0
stdout=Apache-Dir/logs/stdout.log
stderr=Apache-Dir/logs/stderr.log
 
[worker.jni:onShutdown]
info=Command to be executed by the VM on shutdown. This one will stop tomcat.
class=org/apache/jk/apr/TomcatStarter
ARG=stop
disabled=0
 
[uri:/jkstatus/*]
info=Display status information and checks the config file for changes.
group=status:
 
#[uri:127.0.0.1:8003]
#info=Example virtual host. Make sure myVirtualHost is in /etc/hosts to test it
#alias=myVirtualHost:8003
 
#[uri:127.0.0.1:8003/ex]
#info=Example webapp in the virtual host. It'll go to lb_1 ( i.e. localhost:8019 )
#context=/ex
#group=lb_1
 
[uri:/examples]
info=Example webapp in the default context. 
context=/examples
debug=0
 
#[uri:/examples1/*]
#info=A second webapp, this time going to the second tomcat only.
#group=lb_1
#debug=0
 
[uri:/examples/servlets/*]
info=Prefix mapping
 
[uri:/examples/*.jsp]
info=Extension mapping
 
[uri:/examples/*]
info=Map the whole webapp
 
[uri:/examples/servlets/HelloW]
info=Exampel with debug enabled.
debug=10

Rename the file Tomcat-Dir\jk2.properties to jk2.properties.orig. Copy the following jk2.properties file into the Tomcat-Dir\conf directory:

## THIS FILE MAY BE OVERRIDEN AT RUNTIME. MAKE SURE TOMCAT IS STOPED
## WHEN YOU EDIT THE FILE.
 
## COMMENTS WILL BE _LOST_
 
## DOCUMENTATION OF THE FORMAT IN JkMain javadoc.
 
# Override the default port for the socketChannel
# channelSocket.port=8019
# Default: 
# channelUnix.file=${jkHome}/work/jk2.socket
# Just to check if the the config  is working
shm.file=Apache-Dir/logs/jk.shm
 
# In order to enable jni use any channelJni directive
channelJni.disabled = 0
# And one of the following directives:
 
# apr.jniModeSo=/opt/apache2/modules/mod_jk2.so
 
# If set to inprocess the mod_jk2 will Register natives itself
# This will enable the starting of the Tomcat from mod_jk2
apr.jniModeSo=inprocess

Configure Apache

Add the following to your Apache-Dir/conf/httpd.conf:

Loadmodule jk_module modules/mod_jk.so
JkWorkersFile Apache-Dir/conf/workers2.properties
JkLogFile Apache-Dir/logs/mod_jk.log
JkLogLevel info
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "

# serve all java server pages from Tomcat
JkMount /*.jsp ajp13

NameVirtualHost *:9000
Listen 9000

<VirtualHost *:9000>
  Servername jabber.myserver.com
  DocumentRoot WebRoot/jwchat
  AddDefaultCharset UTF-8

  JkMount /JHB/* ajp13
</VirtualHost>

This configuration will let you access your JWChat client through http://jabber.myserver.com:9000. In your setup, you might not use virtual hosts.

Configure JWChat

Edit WebRoot\jwchat\config.js:

var SITENAME = "jabber.myserver.com"
var DEFAULTCONFERENCESERVER = "conference.jabber.myserver.com";
var DEBUGJID = "admin@jabber.myserver.com"; // which user get's debug messages

Finishing

Start Apache, Tomcat and Jabberd.

Test your installation through http://jabber.myserver.com:9000.

Helpful links

If you encounter any problems when installing Apache for the first time, be sure to check the Apache website.
Jakarta Tomcat site
jabberd project
JWChat
ejabberd
Windows Jabber 2 modification & builds page
Jabber SoftwareFoundation
JabberHTTPBind
Jakarta Tomcat Wiki
Jakarta Tomcat Connector (mod_jk)
Module mod_jk for HTTP Server (powered by Apache)
Proxy Support HOW-TO for Tomcat (if you don't want to use mod_jk)
Tomcat workers.properties
Working with mod_jk (for Tomcat 3.3)
Public chatroom where you can ask for help with the setup:
server: conference.jabber.org
room: jdev or jabber
Html-Kit (editor that can display/save files in UNIX format, also has syntax highlightning, free for personal use)