History

Configuration Guide

This configuration guide tackles adaptation needs that typically arise when fine-tuning your docendo installation. Please drop us a note if you miss anything here.

Running Apache Tomcat on Port 80

Tomcat starts on Port 8080 by default. This implies inconvenient looking URLs to the application at best and firewall/access issues at worst. So if you don't already have a web server or another application running on port 80, you may want to start Tomcat on that port to resolve these issues. In case you do have an Apache web server running, you may also use it as a proxy to Tomcat instead.

There is a nice How-to written by Holger Klawitter that explains a couple of configuration variants to achieve this. The recommendations for Tomcat 5.x on that page also apply to Tomcat 6.x. To summarize, the recommended steps to configure Tomcat on Linux systems are:

  1. Compile jsvc on your system: 
    cd [tomcat-home]/bin
tar xzvf jsvc.tar.gz
cd jsvc-src
sh configure
make
cp jsvc ..
  2. Configure Tomcat to launch on port 80 by editing [tomcat-home]/conf/server.xml, changing the setting <Connector port="8080"... to <Connector port="80"...
  3. Create a system user that will be used to run Tomcat: 
    useradd -r tomcat
  4. Create a start script /etc/init.d/tomcat.sh. The following is an example for the script - you probably have to adapt some variables to your system, especially JAVA_HOME and CATALINA_HOME. 
    #!/bin/sh
# Note: Adapt the following lines to your configuration
JAVA_HOME=/usr/lib/jvm/java-6-openjdk
CATALINA_HOME=/srv/apache-tomcat-6.0.20
TOMCAT_USER=tomcat
TMP_DIR=/var/tmp
CATALINA_OPTS=
CLASSPATH=$CATALINA_HOME/bin/commons-daemon.jar:$CATALINA_HOME/bin/bootstrap.jar

case "$1" in
  start)
    $CATALINA_HOME/bin/jsvc \
    -user $TOMCAT_USER \
    -home $JAVA_HOME \
    -Dcatalina.home=$CATALINA_HOME \
    -Djava.io.tmpdir=$TMP_DIR \
    -outfile $CATALINA_HOME/logs/catalina.out \
    -errfile '&1' \
    $CATALINA_OPTS \
    -cp $CLASSPATH \
    org.apache.catalina.startup.Bootstrap
    ;;

  stop)
    PID=`cat /var/run/jsvc.pid`
    kill $PID
    ;;

  *)
    echo "Usage: tomcat.sh start/stop" 
    exit 1;;
esac
  5. Tomcat can now be started by user root entering: 
    /etc/init.d/tomcat.sh start
  6. You may also want to add the new init script to "some" runlevels (typically 3 and 5) so that Tomcat starts when the system is booted. The way to do this depends on your Linux distribution. For Debian it is: 
    update-rc.d tomcat.sh defaults

Using Apache web server as proxy to Tomcat

Letting the Apache web server proxy requests to Tomcat is especially suitable when using a sub-domain to access docendo (e.g. http://docendo.your-site.com). The recommended way to achieve this is to proxy incoming HTTP requests via AJP (Apache JServ Protocol) from the Apache web server (Version >= 2.2) to Tomcat.

  1. Enable the "proxy" module of Apache web server. This is distribution specific, for Debian this is: 
    a2enmod proxy
a2enmod proxy_ajp
  2. Configure Apache web server to proxy HTTP via AJP to Tomcat. An example how to do this for a specific sub-domain "your-sub-domain" is to create a file /etc/apache2/sites-available/your-sub-domain (on Debian) with the following content: 
    <VirtualHost *:80>
    ServerName your-sub-domain.your-domain.com
    ProxyRequests Off
    <Proxy *>
        Order deny,allow
        Allow from all
    </Proxy>
    ProxyPass         /  ajp://localhost:8009/
    ProxyPassReverse  /  ajp://localhost:8009/
    <Location />
        Order allow,deny
        Allow from all
    </Location>
    ErrorLog /var/log/apache2/your-sub-domain_error.log
    LogLevel warn
    CustomLog /var/log/apache2/your-sub-domain.log combined
</VirtualHost>
  3. In its default configuration, Tomcat opens the port 8009 for AJP connections, so there is no need to configure anything there. If you want to change it, you will find the port definition in the file [tomcat-home]/conf/server.xml. Look for the line "<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />".

Now you should be able to access docendo with the URL http://your-sub-domain.your-domain.com/docendo.

Using other DBMS (MySQL, Oracle etc.)

docendo is by default configured to use HypersonicSQL for its database backend. This is very convenient since it does not require any database services to be installed on your server. If this for some reason is not what you want, you can configure docendo to use a variety of other database backends. docendo uses JPA (Java Persistence API) to access its database. Since JPA is only a specification, an implementation of that is needed and docendo uses the Hibernate Entity Manager for that. So basically all DBMS supported by Hibernate can be used for docendo. The list of supported DBMS includes e.g.
  • Oracle 8i, 9i, 10g
  • DB2 7.1, 7.2, 8.1, 9.1
  • Microsoft SQL Server 2000
  • MySQL 3.23, 4.0, 4.1, 5.0
  • PostgreSQL 7.1.2, 7.2, 7.3, 7.4, 8.0, 8.1
  • HypersonicSQL 1.61, 1.7.0, 1.7.2, 1.7.3, 1.8
  • SAP DB 7.3

The DBMS for docendo is set by the application server as a data source via JNDI. If you use Tomcat, this setting can be found in the deployment descriptor of the docendo web application, which is the file [tomcat-home]/conf/Catalina/localhost/docendo.xml.

Here is an example configuration for Tomcat + MySQL:

...
    <Resource name="jdbc/docendo" auth="Container" 
        type="javax.sql.DataSource" username="[your-database-user]" password="[your-database-password]" 
        driverClassName="com.mysql.jdbc.Driver" 
        url="jdbc:mysql://[your-database-server]/[database-name-for-docendo]" 
        maxActive="99" maxIdle="4" maxWait="10000" validationQuery="SELECT 1" 
    />
...

Cronjob for regular automatic backup creation

One way to create automatic backups is to regularly run a backup script on a host other than your docendo server. This can be achieved by a cronjob.

Create a script that exports a backup ZIP file by calling the corresponding URL in docendo:

#! /bin/sh
HOST=docendo.example.org

USER=your-docendo-admin-userid
PASS=your-docendo-admin-password
HOSTURL=http://$HOST
HOSTBACKUPURL=$HOSTURL/admin/export.do
BACKUPBASE=/path/to/backup-dir/$HOST
BACKUPFILE=backup-`date +%Y%m%d-%H%M`.zip
COOKIEFILE=cookies.txt
MAILADRESS=your-email-address

senderror()
{
  # argument 1: message body
  sendmessage "Warning: auto-backup FAILED on $HOST" $1
}

sendmessage()
{
  # argument 1: message subject
  # argument 2: message body
  echo -e "Subject:${1}\n\n${2}\n" | msmtp $MAILADRESS
}

# if backup directory does not exit, try to create it
if [ ! -d $BACKUPBASE ]
then
    mkdir -p $BACKUPBASE 
fi
if [ ! -d $BACKUPBASE ]
then
        senderror "Backup base directory couldn't be created: $BACKUPBASE -> Exiting." 
        exit 1 
fi

cd $BACKUPBASE

# request some password protected page so we get the login page and a session cookie as result
wget -q --keep-session-cookies --save-cookies $COOKIEFILE $HOSTBACKUPURL -O - &>/dev/null

# login
wget -q --load-cookies $COOKIEFILE --post-data "j_username=$USER&j_password=$PASS" $HOSTURL/authenticate -O - &>/dev/null

# get the backup file
wget -q --load-cookies $COOKIEFILE $HOSTURL/admin/export.do -O $BACKUPFILE &>/dev/null
# Was export successful? If not -> warning
if [ ! -s $BACKUPFILE ]
then
    senderror "Export file couldn't be downloaded. -> Exiting." 
        exit 2
fi

# remove cookie file
rm $COOKIEFILE

# test zip file integrity
unzip -tqq $BACKUPFILE &>/dev/null
if [ $? -ne 0 ]
then
        senderror "Downloaded export file ist not a valid zip file. -> Exiting." 
        exit 3
fi

# send success message
SIZE=`du -ms $BACKUPBASE/$BACKUPFILE | awk '{print $1}'`
sendmessage "backup of $HOSTURL successful" "Backup created in $BACKUPBASE/$BACKUPFILE. Backup size is $SIZE MB."

Configure the script in /etc/crontab:

# run docendo backup at 2.30 every saturday
30 2    * * 6   your-user-id  /path/to/backup/script.sh