root/HelpIM3_chi/README.txt

HelpIM3 README

1) Introduction
HelpIM3 is the development version of the next generation of HelpIM. Targets for its development are:
- improved stability
- improved scalability
- improved support for non-western languages
- improved configuration

HelpIM3 will come in three flavours: HelpIM-light, HelpIM-embedded and HelpIM-full. Each of these flavours share the same codebase, but are different sets of configurations.
- HelpIM-light is a light-weight subset of HelpIM3 that should pretty much work out of the box. Its configuration is suitable for simple applications of HelpIM.
- If you want more features or other configuration options, HelpIM-full is your thing. HelpIM-full is very adaptable to your needs, because of its modulair setup, but you have to do the configuration yourself. An demo configuration is included.
- HelpIM-embedded is an other set of configurations of HelpIM, designed to be integrated in an other CMS. In this flavour, it is possible to configure HelpIM fromout an CMS. Integrating HelpIM-embedded with your site, will need some configuration and probably a little programming.

2) Prerequisites
We develop and test HelpIM on both Debian stable and Debian tesing, with Tigase as jabber server, Apache2 as webserver and MySQL as database engine.

HelpIM3 needs:
- Python 2.5 or an higher version of Python 2
- The following non-standard Python modules:
  - crypto
  - pyxmpp 1.0.1 or later
  - sqlalchmey
  - the database driver for the database you wish to use.
  On a Debian system with MySQL these can be installed with the following command:
    sudo aptitude install python python-crypto python-pyxmpp python-sqlalchemy python-mysqldb
  Note for Debian: the pyxmpp version of Lenny is too old, you must install the debs of
  python-pyxmpp and python-support from a later version by hand with dpkg -i.
- An Python WSGI-enabled web server, with the possibility to proxy requests on a certain URL to
  another server. For the development of HelpIM we use:
  - Apache2 with the following modules:
    - mod_proxy
    - mod_proxy_http
    - mod_proxy_connect
    - mod_wsgi
  On a Debian system these can be installed with the following command:
    sudo aptitude install apache2-mpm-prefork libapache2-mod-proxy-html libapache2-mod-wsgi
  the module proxy_connect will be installed, but not be enabled. To enable it, run:
    sudo a2enmod proxy_connect
- An database engine. MySQL is tested, but PostgreSQL should work too.
- An jabber server that supports:
  - SASL Anonymous login
  - BOSH
  - MUC
  - Chat state notifications in the MUC
  Currently only the Tigase jabber server versions 4.3.1 and up supports all of these. Don't use
  Tigase 4.2.0: it contains a bug in the BOSH connection manager that delays closing the chat for
  5 minutes.
  Tigase needs SUN JDK (not JRE!) version 1.6.
  The jabber server only needs to listen on the localhost. The connection with external clients is
  done through the proxy-component of the webserver.

3) Configuration setting up the light variant:
3a) Install and configure Tigase:
- Make sure 'java' defaults to your SUN JDK 1.6:
    java -version
  On Debian based systems you can install it with:
    sudo aptitude --without-recommends install sun-java6-jdk
  Note 1: You need the non-free repository to be enabled for this.
  Note 2: sun-java6-jdk recommends libnss-mdns, which in turn pulls in avahi. I suppose you
          don't want to run avahi on a server. So install it with the --without-recommends
          option. This also saves you from some X11-libs.
  If you have it installed and 'java' points to a wrong version, you can change
  the defaults with the command:
    sudo update-alternatives java

- Start the tigase installer for the basic installation:
    sudo java -jar tigase-server-x.x.x-bxxxx.jar -console
    - when installing on a computer with a grafical environment, it is easier to leave away the '-console'
    - use the wizzards for a first installation
    - at the 'target path': /usr/local/tigase should be a reasonable sane choice
    - at the start of the configuration, choose: "Default plus extra components"
    - make sure you include 'localhost' in the list of jabberdomains
    - make an admin account for localhost (eg: admin@localhost)
    - you can leave the advanced configuration options off

- To further configure Tigase, you have two options:
  Option 1:
    Automatic setup for HelpIM3:
      sudo ./tigase_setup.sh
    This script assumes tigase is in /usr/local/tigase. It will:
       - create the user and group 'tigase'
       - move logging to /var/log/tigase
       - move the runfile to /var/run/tigase
       - move tigase.xml to /var/lib/tigase
       - move the configuration files to /etc/tigase
       - automaticly change the configuration files to settings suitable for HelpIM3
       - create /etc/init.d/tigase and symlinks to it in the rc.d dirs
  Option 2:
    Manually configure tigase to your wishes.
    - Make sure that in init.properties the following lines are present:
      --comp-name-1=muc
      --comp-class-1=tigase.muc.MUCComponent
      muc/muc-allow-chat-states[B]=true
      muc/muc-lock-new-room[B]=false
      message-router/components/msg-receivers/s2s.active[B]=false
      basic-conf/logging/java.util.logging.FileHandler.pattern=/var/log/tigase/tigase.log
    - You might want to comment out the line "--debug = server" in init.properties: Tigase debug logging is extremely
      verbose and might contain privacy sensitive data when using it with HelpIM3.
- Start tigase. If you used the automatic setup for HelpIM3 you can do this
  with:
    sudo /etc/init.d/tigase start
- Note: When changing the init.properties of Tigase, make sure you delete the 
  active tigase.xml before starting tigase again else your changes won't have
  any effect.
- To add users (e.g. helpimbot) manually (you might also connect with an jabber client to it and use the
  clients register function):
  - edit in the tigase base directory the file scripts/repo.sh to reflect your database
  - create a file with, for every user you want to add a line like this:
     helpimbot@localhost,<password>,,,,
  - import the users with:
     ./scripts/repo.sh -import import-file.txt

3b) Configuring Apache2
Apache2 has two functions: it serves the HelpIM webapplication and it proxies the XMPP-BOSH connections HelpIM makes to Tigase. Both need to be setup in Apache2.

- Proxying BOSH:
  - enable mod_proxy, mod_proxy_connect and mod_proxy_http (if not already done:
      #/etc/apache2/mods-enabled# ln -s ../mods-available/proxy.load
      #/etc/apache2/mods-enabled# ln -s ../mods-available/proxy_connect.load
      #/etc/apache2/mods-enabled# ln -s ../mods-available/proxy_html.load
      #/etc/apache2/mods-enabled# ln -s ../mods-available/wsgi.load
  - In some some configs, Debian Lenny for example, there is the file
    /etc/apache2/mods-enabled/proxy.conf loaded. If so, you need to change
    the "Deny from all" into "Allow from all".
    Warning: if you use apache also as a forward proxy (if you have anywhere
    in your config "ProxyRequests on"), then you must implement a more fine
    grained access control to your proxy. Otherwise you create an open proxy.
  - Add to the definition of the virtual host HelpIM is going to run in
    the following:
      ProxyRequests Off
      ProxyPass /http-bind/ http://localhost:5280/http-bind/
      ProxyPassReverse /http-bind/ http://localhost:5280/http-bind/
    this creates a reverse proxy to Tigase, while denying all other proxy
    requests.
  - Increase in apache2.conf the connection timeout a little:
      Timeout 360
    This timeout sets the time a request can take without responding before it
    is killed off by apache. Unfortunately the default for this timeout (300)
    is exactly the same as the BOSH 'wait' value used by HelpIM (and many other
    BOSH clients). That means the proxy kills the request just at the moment
    the client wants to refresh the connection. Increasing this timeout a
    little avoids this.
- Setup the webapplication. When HelpIM is installed in:
  /home/winfried/werk/HelpIM/svn/HelpIM3/htdocs/ and you want to run HelpIM on
  the location [www.virtual-host.example]/chi then you need to add the
  following directives to your definition of www.virtual-host.example:
        # make sure utf-8 is the default (if it isn't already)
        <Location /chat/chat>
                AddDefaultCharset utf-8
        </Location>

        # Directory for the static files
        Alias /chat/chat/htdocs/ /usr/local/share/HelpIM/htdocs/
        <Directory /usr/local/share/HelpIM/htdocs/>
                Options None
                AllowOverride None
                Order allow,deny
                Allow from all
        </Directory>

        # Webapp
        # Note: do not use a trailing slash here, seems to be a bug in mod_wsgi!
        WSGIScriptAlias /chat/chat /usr/local/lib/python2.5/site-packages/HelpIM/web/HelpIM.wsgi
        <Directory /usr/local/lib/python2.5/site-packages/HelpIM/web/>
                Order allow,deny
                Allow from all
                # Use one interpreter for all of HelpIM
                WSGIApplicationGroup HelpIM3
        </Directory>
  Based on the hostname of the request, HelpIM wil automaticly look for the
  correct configuration file in its own configs. It will adjust its paths to
  path defined in the WSGIScriptAlias directive.
- Generic performance settings:
  - Consider raising the 'MaxClients' value in apache2.conf: for each chat,
    one connection is permanently used and a second (and sometimes even a
    third) needs to be available. So a MaxClients of 150 is only safe for up to
    appr. 75 to 100 active chats.
  - Consider increasing the SSL cache timeout in mods-available/ssl.conf:
      SSLSessionCacheTimeout 3600
    Because HelpIM clients generate a lot of subsequential seperate requests,
    increasing this setting from its default of 300 to something like 3600,
    saves the server (and the browser) from a lot of extra SSL negotiating.
- Restart apache2


3c) Setting up the database:
HelpIM uses for each site a separate database. When it detects an empty
database, it sets up the tables automaticly. To create the database for
HelpIM:
- log in to MySQL with enough permissions (probably as root)
- execute the following SQL:
    CREATE DATABASE <database_name>;
    GRANT all ON <database_name>.* TO <username>@localhost IDENTIFIED BY '<password>';

3d) Building pyxmpp for performance  (optional)
If you don't install pyxmpp from package but from a n other source, you might
compile it for extra performance. In that case download the sources of pyxmpp
and make sure you have gcc, python-dev en libxml-dev installed. On a Debian
system you can do:
  sudo aptitude install gcc python-dev libxml2-dev
Then download and unpack pyxmpp and cd to its base directory and do:
  python configure.py
  python setup.py build
  sudo python setup.py install
And if you don't like to have gcc floating around on your server, purge it
again. On a Debian system:
  sudo aptitude purge gcc

3e) Install / configure HelpIM
The easiest way to do this, is to edit the helpim_setup.sh script to your
taste and run it as root. It does the following:
- make and fill /etc/HelpIM
- place HelpIM in pythonpath, in /usr/local/.../site-packages
- precompiles HelpIM
- places the htdocs in /usr/local/share/HelpIM
- link /usr/local/bin/helpim to bot.py and make it executable
- place & link /etc/init.d/helpim
- create /var/log/HelpIM
- make helpim user & group
- make www-data member of helpim group

If you placed the configs in an other location then /etc/HelpIM, you must
also adjust the paths in: HelpIM/paths.py

Next is to adjust the configs. There are two kind of configuration files to
take care of:
- The file /etc/HelpIM/config.xml
  This file contains generic settings for the bot. You must adjust the username
  and the password to the extra (non-admin) user you created in Tigase. If you
  changed the paths, you also have to adjust the 'destination' of the <logging>
  section. Usually the other settings will be ok.
- The xml files in /etc/HelpIM/sites/
  For each request HelpIM determines the servername requested. It then looks
  for a file with the name [servername].xml and loads the configuration for
  that site from it. When creating a site, you should at least adapt the
  databaseuri in the '<site>' section. The databaseuri has the form:
    driver://username:password@host:port/database
  Allowable drivers are: sqlite, mysql, postgres, oracle, mssql, and firebird.
  Note you need to have the corresponding Python database driver installed,
  for the database to function.

If you want, later on, to upgrade HelpIM from the subversion repository, you
can run the update_HelpIM_from_svn.sh script.

ToDo: default super-user when HelpIM-light is operational

3f) Start the bot:
  /etc/init.d/helpim start
Or, if you did al the configuration your self:
  ./bot.py
will do too.

3g) Login and chat
ToDo: to be added when HelpIM-light is operational

4) Where to go from here
ToDo!
- embedded
- full