Funambol with Mysql: how to install

I’m installing and configuring a funambol server on linux (Debian 64bit squeeze).

After some days playing with its services I decided to move funambol database from the built in Hypersonic database to Mysql, mainly because I already have backup procedures for Mysql and I find comfortable to use a well-known database.

References:

• Funambol Mobile Open Source – ebook
• Funambol and LDAP

Funambol installation

Preliminary checks:

Funambol is java based.
If no JAVA_HOME is defined, (type env to verify it) Funambol defaults to the one distributed with the package, which is $FUNAMBOL_HOME/tool/jre-1.x.y

Some of the next steps (like the LDAP module) require a full JDK, not a JRE so a small work might be necessary to setup a new java environment.

apt-get install default-jdk

java -version

java version “1.6.0_18″
OpenJDK Runtime Environment (IcedTea6 1.8.10) (6b18-1.8.10-0+squeeze2)
OpenJDK 64-Bit Server VM (build 14.0-b16, mixed mode)

export JAVA_HOME=/usr/lib/jvm/java-6-openjdk
export MEM_OPTS="-Xmx512M" #sets the maximum Java heap size to 512MB

For a production server it might be better to set a higher size => let’s say 3GB => MEM_OPTS=”-Xmx3G”.

Make java settings global
To make global and permanent these settings, execute this command and restart the system. At the next login, launch env and you should see the variable JAVA_HOME

echo '
 > #exports JAVA Settings globally
 > export JAVA_HOME=/usr/lib/jvm/java-6-openjdk
 > export PATH=$PATH:$JAVA_HOME
 > export MEM_OPTS="-Xmx512M" #sets the maximum Java heap size to 512MB
 > ' > /etc/profile.d/java.sh

Reboot the system to make the modification effective.

Prepare the environment:

mkdir  -p /opt/Funambol/Downloads
cd /opt/Funambol/Downloads

Download and install the Funambol Server v. 10.0.3 :

wget -c http://ignum.dl.sourceforge.net/project/funambol/bundle/v10/funambol-10.0.3-x64.bin
chmod +x funambol-10.0.3-x64.bin

Now, as root let’s install the Funambol services

./funambol-10.0.3-x64.bin

Configure the service to run as user funambol

Running funambol services as root is not a good idea as for any other service, so let’s create the funambol user.

groupadd funambol
useradd  -g funambol -m -d /opt/Funambol -s /bin/sh funambol
chown funambol:funambol -fR /opt/Funambol

Java settings for user funambol

Since the user funambol has to deal only with the funambol service it’s better to configure, for this user, a particular JAVA environment specifically thought for the funambol service unrelated to the system global java settings. In this way all the settings needed to run Funambol will be set in the /opt/Funambol directory.

cat <<'EOF' > /opt/Funambol/.profile
# ~/.profile: executed by the command interpreter for login shells.
# This file is not read by bash(1), if ~/.bash_profile or ~/.bash_login
# exists.
# see /usr/share/doc/bash/examples/startup-files for examples.
# the files are located in the bash-doc package.

# the default umask is set in /etc/profile; for setting the umask
# for ssh logins, install and configure the libpam-umask package.
#umask 022

# include .bashrc if it exists
if [ -f "$HOME/.bashrc" ]; then
        . "$HOME/.bashrc"
fi

# set PATH so it includes user's private bin if it exists
if [ -d "$HOME/bin" ] ; then
    PATH="$HOME/bin:$PATH"
fi
EOF

cat <<'EOF' > /opt/Funambol/.bashrc
#exports JAVA Settings for user funambol
export JAVA_HOME=/opt/Funambol/tools/jre-1.6.0
export PATH=$PATH:$JAVA_HOME

#sets the maximum Java heap size to 512MB
export MEM_OPTS="-Xmx512M"
EOF

Configure init.d script
Here I found a clever way to start the services as funambol user and I made some slight modifications: this command will create an init script

cat <<'EOF' > /etc/init.d/funambol
#! /bin/bash
#
# funambol Start the funambol services
#
NAME="Funambol Server"
FUNAMBOL_HOME=/opt/Funambol/bin
FUNAMBOL_USER=funambol
FUNAMBOL_BIN=$FUNAMBOL_HOME"/funambol"

if [ -f /lib/lsb/init-functions ]; then
 . /lib/lsb/init-functions
fi

#cd $FUNAMBOL_HOME
case "$1" in
  start)
    echo "Starting $NAME"
    /bin/su -s /bin/bash -l $FUNAMBOL_USER $FUNAMBOL_BIN start
    ;;
  stop)
    echo "Stopping $NAME"
    /bin/su -s /bin/bash -l $FUNAMBOL_USER $FUNAMBOL_BIN stop
    ;;
  restart)
    echo "Restarting $NAME"
    /bin/su -s /bin/bash -l $FUNAMBOL_USER $FUNAMBOL_BIN stop && \
    /bin/su -s /bin/bash -l $FUNAMBOL_USER $FUNAMBOL_BIN start
    ;;
  *)
    echo "Usage: /etc/init.d/funambol {start|stop|restart}"
    exit 1
    ;;
esac
exit 0
EOF

chmod 755 /etc/init.d/funambol

update-rc.d funambol defaults

From now on, funambol should be started and stopped with the command: /etc/init.d/funambol [ start | stop | restart ]

Start the service:

/etc/init.d/funambol start

Now the user interface should be accessible with a browser at  http://server_ip:8080  with these credentials: guest guest

Funambol documentation

Funambol provides an interesting quick start guide funambol-test-drive-guide-v7.1

Funambol Administration Tool

The admin interface is already included in the funambol v.10.0.xx package and can be started launching:

/opt/Funambol/admin/bin/funamboladmin

The Admin interface is a java application runnig in X so if you are running the server on a remote server than you have to enable X-forward on ssh and it’s convenient to access the server with the command:

ssh -X user@ip

If you are running an older installation it can be installed in this way:

 wget -c http://ignum.dl.sourceforge.net/project/funambol/admin-tool/v10/funambol-admin-10.0.0.tgz
cd /opt/Funambol
tar zxf Downloads/funambol-admin-10.0.0.tgz

The Admin interface allows the configuration of the ServerURI field, generally left blank after the installation, which is supposed to be the public URL to access Funambol synchronization services and used by the server in the SyncML replies (useful for load balancing).
The same configuration can be set by hand in this way:

<void property="serverURI">
 <string>http://ip_server:8080/funambol/ds</string>
 </void>

Note:
1) the default username and password for the Administration Tool are: admin sa
2) to access the Administration Tool Funambol must be running
3) changes to configuration files are usually picked up automatically by Funambol services. No restart or reinitialization of the services is required after a change is made.

At this point Funambol is completely installed

Using Mysql as database

The Hypersonic database used by Funambol out of the box has nothing wrong. I just prefer to use Mysql if it’s possible because it fits better my backup policies and because I know it better. Fortunately Funambol support Postgre-sql and Mysql but the configuration of the database can’t be done using the Administration Tool.

/etc/init.d/funambol stop
ps aux | grep funambol #should return no process running

Create the database and user “syncuser”

mysql -h localhost -uroot -p

create database funambol character set 'UTF8';
create user syncuser identified by 'test';
GRANT ALL PRIVILEGES ON funambol.* TO
'syncuser'@'localhost' IDENTIFIED BY '<choose a password>';
FLUSH PRIVILEGES;

Configure Funambol

This tells to Funambol which is the database server to connect to:

cd /opt/Funambol
vim config/com/funambol/server/db/db.xml

Update the content in this way:

<string>jdbc:mysql:hsql://localhost/funambol</string>
...
<string>username</string>
<string>syncuser</string>
...
<string>password</string>
<string>SYNCUSER's PASSWORD</string>

This downloads and installs the java connector for mysql:

mkdir /tmp/java_connector
cd /tmp/java_connector
wget -c http://it.mysql.contactlab.it/Downloads/Connector-J/mysql-connector-java-5.1.18.tar.gz
tar zxf mysql-connector-java-5.1.18.tar.gz
mv mysql-connector-java-5.1.18/mysql-connector-java-5.1.18-bin.jar  /opt/Funambol/tools/jre-1.6.0/jre/lib
cd /opt/Funambol/
rm -fR /tmp/java_connector

This tells to Funambol which is the kind of the database backend and where to find the connector for it.
Edit file /opt/Funambol/ds-server/install.properties and change

dbms=mysql

Comment all the lines starting with jdbc. and add these lines:

jdbc.classpath=/opt/Funambol/tools/jre-1.6.0/jre/lib/mysql-connector-java-5.1.18-bin.jar
jdbc.driver=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://localhost/funambol?characterEncoding=UTF-8
jdbc.user=syncuser
jdbc.password=SYNCUSER's password

This disables the Hypersonic driver

sed -i -e "s/COMED=.*/COMED=false/" /opt/Funambol/bin/funambol

Now it’s the time to launch the Funambol installation process which will setup the mysql database:

/opt/Funambol/bin/install

answer ‘y’ to every question.

/etc/init.d/funambol start

Testing

Let’s check that everything is working as supposed:

ps aux | grep funambol

Administration Tool

/opt/Funambol/admin/bin/funamboladmin

Funambol web interface:

http://ip_server:8080

Use guest guest to login and add a test contact

Funambol Client synchronization
If you have Microsoft Outlook installed somewhere this is the best way to check the ds-server capabilities. On Funambol website I saw several sync-clients but most of them are in development or not available for the most updated version of the software, like the thunderbird add-on available only for version 2. So the Windows client is the best option for test as far as I know.

The client can be downloaded from here. Once installed go to Tools->Option and set the server path http://ip_server:8080/funambol/ds and the user (guest, guest).

Launch the synchronization process for contacts and, after few seconds, you’ll see in Outlook the test contact made in the web site.