root/stable/setup/README

Installation of HelpIM

1) Requirements:

HelpIM has been tested on Debian Sarge and Debian Etch.

It needs:
- python2.3 or python2.4
- apache2 with mod_python. Be aware that early versions of mod_python v 3 have lots of nasty bugs and memory-leaks. IT is advisable to use at least version 3.1.x of mod_python.
- MySQL database. Right now it supports MySQL from 3.23 up to 5.0 (5.1 should work too). In the near future support for versions before 4.1 will be dropped.
- an jabber-server, it is tested with jabberd1.4, but any jabberserver should work. 

HelpIM uses the following Python non-standard modules:

MySQLdb
    Tested with version 1.2.1
    Should be available in your distribution, source-package can be found at:
    http://sourceforge.net/project/showfiles.php?group_id=22307

PyXMPP version 1.0 build 645 (snapshot 20060819) or higher
    Note that PyXMPP versions below build 658 work with M2Crypto version 1.4, from build 659 and up it needs
    M2Crypto version 1.6. PyXMPP is available at: http://pyxmpp.jajcus.net/
    For Debian Sarge there is no package available for this, nor for some of its
    dependencies. To install on Debian Sarge:
    - install from Sarge: libxml2 libxml2-dev python2.3-libxml2 and m2crypto
    - install from Etch: python2.3-dnspython:
             download it from: http://packages.debian.org/etch/python-dnspython/all/download
             install it with: sudo dpkg -i python-dnspython_1.3.5-3.1_all.deb
    - download pyxmpp and install it according to the instructions on http://pyxmpp.jajcus.net/

Crypt
    This is available at http://www.amk.ca/python/code/crypto or at your distribution
    Tested with version 2.0.1


2) Installation of the requirements in Debian Etch:

Install servers:
 sudo aptitude install apache2-mpm-prefork mysql-server jabber

Install python libraries needed for HelpIM:
 sudo aptitude install python2.4 libapache2-mod-python python-mysqldb python-crypto

Install requirements for PyXMPP:
 sudo aptitude install python-dnspython python-libxml2 python-m2crypto python-support

If you build PyXMPP on same computer, install requirements to build PyXMPP:
 sudo aptitude install gcc python-dev libxml2-dev
 wget http://pyxmpp.jajcus.net/downloads/snapshots/pyxmpp-1.0.0.s20070831.tar.gz
 tar -xzf pyxmpp-1.0.0.s20070831.tar.gz
 cd pyxmpp-1.0.0.s20070831/
 python setup.py build
 sudo python setup.py install

And if you don't like to have gcc floating around on your server:
 sudo aptitude purge gcc


3) Configuration of jabberd1.4

Edit the file /etc/jabber/jabber.xml
Replace 'localhost' with the hostname of your server, you might do virtual hosting with jabberd. Update the ip-numbers and ports to listen to, update the location of your ssl-certificates. 

Other recommended changes to jabber.xml:

- change the register part to:
      <register notify="no">
        <instructions>Choose a username and password to register with this server.</instructions>
      </register>
- comment out the welcome-function
- comment out <vcard2jud/>
- in the browse-section, comment out:
        <service type="jud" jid="users.jabber.org" name="Jabber User Directory">
          <ns>jabber:iq:search</ns>
          <ns>jabber:iq:register</ns>
        </service>
- comment out <mod_auth_plain>./jsm/jsm.so</mod_auth_plain>
- change the 'karma' section to:
      <karma>
        <init>100</init>
        <max>1000</max>
        <inc>100</inc>
        <dec>1</dec>
        <penalty>-1</penalty>
        <restore>100</restore>
      </karma>
- comment out the External asychronous DNS resolver
- comment out the s2s communication
- change the rate-points section to:
    <rate points="1000" time="1"/>


4) Copy HelpIM to right locations:
- Download HelpIM from the svn-repository.

cd stable
sudo cp -r HelpIM /usr/local/lib/python2.4/site-packages/
sudo mkdir /usr/local/share/HelpIM/
sudo cp -r resources/ /usr/local/share/HelpIM/
sudo cp -r settings/templates/ /usr/local/share/HelpIM/
sudo mkdir /etc/HelpIM
sudo mkdir /etc/HelpIM/default
sudo cp settings/* /etc/HelpIM/default/
sudo chown root:www-data /etc/HelpIM/default/baseconfig
sudo chmod 640 /etc/HelpIM/default/baseconfig
sudo mkdir /var/log/HelpIM
sudo chown www-data:adm /var/log/HelpIM
sudo chmod 750 /var/log/HelpIM
sudo mkdir /var/run/HelpIM
sudo chown www-data:adm /var/run/HelpIM
sudo chmod 750 /var/run/HelpIM
sudo mkdir /var/cache/HelpIM
sudo mkdir /var/cache/HelpIM/default
sudo mkdir /var/cache/HelpIM/default/templates
sudo chown www-data:www-data /var/cache/HelpIM/default/templates
sudo chmod 700 /var/cache/HelpIM/default/templates
sudo cp setup/cronjob /etc/cron.daily/helpim
sudo chown root:root /etc/cron.daily/helpim
sudo chmod 755 /etc/cron.daily/helpim
sudo cp setup/HelpIM /etc/init.d/
sudo chown root:root /etc/init.d/HelpIM
sudo chmod 755 /etc/cron.daily/helpim
sudo chmod 755 /etc/init.d/HelpIM

create a file /etc/HelpIM/autostart_sites
In it there should be for each installation of HelpIM on this machine a line with the full path of the
'baseconfig' file of that installation. E.g:
/etc/HelpIM/default/baseconfig


5) Create Database
For each installation HelpIM needs an own database.

To create the database:
- 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> IDENTIFIED BY '<password>';
- log out of mysql and execute the following at your shell prompt:
    mysql -p -u <username> <database_name> < setup/skeleton.sql


6) Configuration of HelpIM

The documentation of the HelpIM configuration is, to put it mildly, inexistant. To get it
running you need to change at least:
settings/baseconfig
settings/settings_all.py
settings/settings_intranet.py
settings/settings_webchat.py
settings/templates_chatbot.py
Make shure the hostnames, http-location, en paths to files are correct.


7) Loading the HelpIM configurations in the database:

To access the database HelpIM needs to find its database configuration. To find
it checks the environment variable 'HELPIMCONFIG'. Set this variable to point to
your baseconfig file:

export HELPIMCONFIG=/etc/HelpIM/default/baseconfig

An annotated example of the baseconfig file can be found in settings/baseconfig. All other
configurations are stored in the database. These can be edited and loaded into the database
with commands like:

cd /etc/HelpIM/default
python /usr/local/lib/python2.4/site-packages/HelpIM/settings.py put settings_all_example

to load all settings at once, do:
python /usr/local/lib/python2.4/site-packages/HelpIM/settings.py put *.py


8) Activate a setup-account

Edit the file setup/setupdata.sql. You should at least change the password...
Now execute:
mysql -p -u <username> <database_name> < setup/setupdata.sql


9) Configure Apache2

First make the resources acessible:
    Alias /resources /usr/local/share/HelpIM/resources
    Alias /intranet /usr/local/share/HelpIM/resources
    <Directory /usr/local/share/HelpIM/resources>
        Options None
        AllowOverride None
        Order allow,deny
        Allow from all
    </Directory>

The webchat:

        <Location /chat>
                Options None
                Order allow,deny
                Allow from all
                AddDefaultCharset utf-8
                SetHandler python-program
                PythonHandler HelpIM.webchat.handler::handlereq
        PythonOption HelpIMconfig /etc/HelpIM/default/baseconfig
                
                # Crucial to set this one to a unique value for each site
                PythonInterpreter "default"
                
                # Should apache check for changes in HelpIM? If Off, a reload of apache
                # is needed to make the new version active, but apache should gain
                # performance. Should be set to 'Off' once in production.
                PythonAutoReload On
                
                # Should apache and HelpIM present error-messages to the client if
                # HelpIM encounters a bug? For testing this is great, but when it in
                # production it is an information-disclosure bug (and a security
                # hazard).
                PythonDebug On
                
        </Location>
        
The intranet:

    <Location /intranet>
        Options None
        Order allow,deny
        Allow from all
        AddDefaultCharset iso-8859-1
        AddCharset utf-8 .html
        ErrorDocument 404 /intranet/404
        SetHandler python-program
        PythonHandler HelpIM.intranet.handler::handlereq
        PythonOption HelpIMconfig /etc/HelpIM/default/baseconfig
                
                # Crucial to set this one to a unique value for each site
                PythonInterpreter "default"

                # Should apache check for changes in HelpIM? If Off, a reload of apache
                # is needed to make the new version active, but apache should gain
                # performance. Should be set to 'Off' once in production.
                PythonAutoReload On
                
                # Should apache and HelpIM present error-messages to the client if
                # HelpIM encounters a bug? For testing this is great, but when it in
                # production it is an information-disclosure bug (and a security
                # hazard).
                PythonDebug On
        </Location>