Integrating Tigase server with LibreSource

This document is still not finished.

Taken directly from LibreSource page:
LibreSource is a collaborative platform dedicated to both software development and community building. Based on Java/J2EE technology, LibreSource is a modular web server that users can customize online by combining resources and rights: wiki pages, forum, trackers, files, download areas, etc. All the tools are included and integrated.

Short introduction.

Integration between Tigase server and LibreSource is on database level. It is implemented in the same way as integration with Drupal but with slightly more functions available.

Basically LibreSource system maintains own database with all it's data and Tigase connects to LibreSource database to authenticate users. All users data specific to Jabber/XMPP service are kept in separate tables which can be located in the same database as LibreSource data or in different database.

Current list of features included in the integration:

• Jabber users authentication against user data stored in LibreSource database.
• Recording Jabber user on-line status in LibreSource database. This can be displayed on the Web page as additional user onfo.
• Recording user last login time and this information can also be available on Web page.
• Checking user account status. So if the user account is disabled in LibreSource system then this user will not be able to login to Jabber/XMPP service too.
• User account creation. This feature might be useful during testing time or user data transition from old Tigase installation to LibreSource system. Please note! This feature should be normally disabled on live system. All user account management should be done from LibreSource system because of data caching.
• User account deletion. Please note! This feature should be normally disabled on live system. All user account management should be done from LibreSource system because of data caching.

A few assumptions:

1. LibreSource data are kept in PostgreSQL database - libresource and database user is demo.
2. For use cases where Tigase data are stored in MySQL database name is tigase, database user is dbuser and database user password is dbpass

How to set Tigase up.

Now we will focus on setting things up to have both services up and running together. Below is example of the most complex environment to run where LibreSource is using PostgreSQL database and Tigase is using MySQL database. All basic user data needed for authentication are kept by LibreSource so Tigase has to connect to PostgreSQL database too to authenticate users.

1. First you need LibreSource system up and running. Please refer to LS documentation for details.
2. Install Tigase server in the normal way including loading Tigase database schema. Database tables used by Tigase server use different naming convention so you can simply load Tigase DB schema to the same database as LibreSource data. It is also possible and recommended to keep Tigase data in separate database.
3. Using configuration wizards generate configuration for Tigase server to connect to LibreSource database. Here is the sample file with parameters for configuration wizard assuming following setup:
   • LibreSource data are kept in PostgreSQL database: libresource, user: demo
   • Tigase data are kept in MySQL database: tigase, user: dbuser, password: dbpass
   • No external components are connected to Tigase server
   • Tigase works for domain: domain.net

   ENC="-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8"
   DRV="-Djdbc.drivers=com.mysql.jdbc.Driver:org.postgresql.Driver"
   
   JAVA_OPTIONS="${ENC} ${DRV} -server -Xms100M -Xmx100M "
   TIGASE_CONFIG="etc/tigase-mysql-libresource.xml"
   TIGASE_OPTIONS="--gen-config-def \
     --user-db mysql \
     --user-db-uri jdbc:mysql://localhost/tigase?user=dbuser&password=dbpass&autoCreateUser=true \
     --auth-db libresource \
     --auth-db-uri jdbc:postgresql://localhost/libresource?user=demo \
     --virt-hosts domain.net,localhost "

4. And simpler example where all data (LibreSource and Tigase) are stored in the same database:
   • LibreSource data are kept in PostgreSQL database: libresource, user: demo
   • Tigase data are kept also in PostgreSQL database: libresource, user: demo
   • No external components are connected to Tigase server
   • Tigase works for domain: domain.net

   ENC="-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8"
   DRV="-Djdbc.drivers=com.mysql.jdbc.Driver:org.postgresql.Driver"
   
   JAVA_OPTIONS="${ENC} ${DRV} -server -Xms100M -Xmx100M "
   TIGASE_CONFIG="etc/tigase-mysql-libresource.xml"
   TIGASE_OPTIONS="--gen-config-def \
     --user-db pgsql \
     --user-db-uri jdbc:postgresql://localhost/libresource?user=demo&autoCreateUser=true \
     --auth-db libresource \
     --auth-db-uri jdbc:postgresql://localhost/libresource?user=demo \
     --virt-hosts domain.net,localhost "

Now, you can run Tigase in usual way and all works.

Note! In any case you have to load Tigase database schema for user data. Please refer to guide for specific database: MySQL or PostgreSQL.

Migration from old Tigase installation to LibreSource

Tigase package includes additional tools to make it easier to manage and control you installation. One is used to change configuration settings - config.sh and another is used to manipulate user data in repository - repo.sh.

Depending on whether you use Tigase version built from sources or binary version these scripts might be available in either scripts/ or bin/ subdirectory. To make things simpler let's assume they are stored in scripts/ directory.

Assuming you have old Tigase server installation with number of users in MySQL database and you want to migrate all of them to LibreSource there are 2 steps involved:

1. User data migration
2. Changing your existing configuration

Data migration

First we need to migrate user data used for authentication. That data will be used by both services: LibreSource and Tigase and they normally stored in LibreSource database. Therefore we have to use LibreSource database connector to handle the data (write or read). Tigase server will be using LibreSource database for reading only but during migration time we need to write user accounts to LS database. Sample command to migrate user accounts looks like this:

./scripts/repo.sh -sc tigase.db.jdbc.JDBCRepository \
  -su "jdbc:mysql://localhost/tigase?user=dbuser&password=dbpass" \
  -dc tigase.db.jdbc.LibreSourceAuth \
  -du "jdbc:postgresql://localhost/libresource?user=demo" \
  -cp

Above command will copy all user accounts from MySQL tigase database to libresource database. Please refer to repository management tool documentation for information how to migrate single or selected user accounts.

If you want to also keep all Tigase server data in the same database you have to copy also all other user data like rosters, vCards and so on.

First thing to do we have to load database schema for Tigase data. You don't have to worry. Tigase tables have distinct names from LibreSource so there is no danger for any conflict. As in example above let's assume LibreSource data are stored in libresource database and database user name is demo:

psql -q -U demo -d libresource -f database/postgresql-schema.sql

Now we can load transfer all user data from our MySQL database to LibreSource:

./scripts/repo.sh -sc tigase.db.jdbc.JDBCRepository \
  -su "jdbc:mysql://localhost/tigase?user=dbuser&password=dbpass" \
  -dc tigase.db.jdbc.JDBCRepository \
  -du "jdbc:postgresql://localhost/libresource?user=demo" \
  -cp

This command looks almost the same as a previous one. Just Java class used for handling destination database is different.

Configuration change