WebAnno Administrator Guide

This guide assumes Debian 8.0.0 (Jessie). It may also work on Ubuntu with some modifications, but we do not test this. Instructions for other Linux distributions likely deviate significantly.

It is further assumed that the user "www-data" already exists on the system and that it shall be used to run WebAnno. Finally, it is expected that you have set up a MySQL database that WebAnno can use.

All commands assume that you are logged in as the root user.

Install MySQL

$ sudo apt-get install mysql-server

make sure your MySQL server is configured for UTF-8. Check the following line is present in /etc/mysql/my.cnf:

character-set-server = utf8

login to MySQL

$ mysql -u root -p

create a database

mysql> CREATE DATABASE webanno DEFAULT CHARACTER SET utf8 COLLATE utf8_bin ;

create a database user called webanno with the password t0t4llYSecreT which is later used by the application to access the database (instructions for settings.properties file below).

mysql> CREATE USER 'webanno'@'localhost' IDENTIFIED BY 't0t4llYSecreT';
mysql> GRANT ALL PRIVILEGES ON webanno.* TO 'webanno'@'localhost';

Install package to install user-instances of Tomcat.

$ aptitude install tomcat8-user authbind

Create new instance

$ cd /opt
$ tomcat8-instance-create -p 18080 -c 18005 webanno
$ chown -R www-data /opt/webanno

Configure the startup script. Edit /etc/init.d/webanno and add the following contents or just download the file from here and place it in /etc/init.d.

#!/bin/sh

# Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

# kFreeBSD do not accept scripts as interpreters, using #!/bin/sh and sourcing.
if [ true != "$INIT_D_SCRIPT_SOURCED" ] ; then
    set "$0" "$@"; INIT_D_SCRIPT_SOURCED=true . /lib/init/init-d-script
fi
### BEGIN INIT INFO
# Provides:          webanno
# Required-Start:    $remote_fs $syslog
# Required-Stop:     $remote_fs $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: WebAnno init script
# Description:       This file should be placed in /etc/init.d. It
#                    allows starting/stopping WebAnno using the
#                    "service" command and ensures that WebAnno starts
#                    when the system is booted.
### END INIT INFO

# Author: Richard Eckart de Castilho

NAME="WebAnno"
DAEMON=none
WEBANNO_HOME="/srv/webanno"
WEBANNO_PORT="18080"
WEBANNO_USER="www-data"
CATALINA_BASE="/opt/webanno"
AUTHBIND=""
JAVA_OPTS="-Djava.awt.headless=true -Xmx750m -XX:+UseConcMarkSweepGC -Dwebanno.home=$WEBANNO_HOME"

setup_authbind() {
  # log_action_msg "Setting up authbind configuration for $DESC on port $WEBANNO_PORT"
  touch /etc/authbind/byport/$WEBANNO_PORT
  chmod 500 /etc/authbind/byport/$WEBANNO_PORT
  chown $WEBANNO_USER /etc/authbind/byport/$WEBANNO_PORT
  AUTHBIND="authbind --deep"
}

tomcat_pid() {
  echo `ps -fe | grep -- "-Dcatalina.base=$CATALINA_BASE" | grep -v grep | tr -s " "|cut -d" " -f2`
}

do_start_cmd_override() {
  if [ $WEBANNO_PORT -lt 1024 ]
  then
    setup_authbind
  fi

  su - www-data -s "/bin/bash" -c "JAVA_OPTS=\"$JAVA_OPTS\" $AUTHBIND $CATALINA_BASE/bin/startup.sh" > /dev/null 2>&1
}

do_stop_cmd_override() {
  su - www-data -s "/bin/bash" -c "$CATALINA_BASE/bin/shutdown.sh" > /dev/null 2>&1
}

do_status() {
  local pid
  pid=$(tomcat_pid)
  if [ -n "$pid" ]
  then
    log_action_msg "Status $DESC: running"
    return 0
  else
    log_action_msg "Status $DESC: stopped"
    return 1
  fi
}

Make the script executable and register it to run during system start:

$ chmod +x /etc/init.d/webanno
$ update-rc.d webanno defaults

Place the WebAnno WAR into the Tomcat webapps folder:

$ cp webanno-webapp-3.0.0.war /opt/webanno/webapps/webanno.war

Create WebAnno home folder. This is the directory where webanno settings files and projects (Serialized Cases, Source documents…​) are stored

$ mkdir /srv/webanno

Edit /srv/webanno/settings.properties to define the database connection as well as internal backup properties and enable/disable crowd sourcing component:

database.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
database.driver=com.mysql.jdbc.Driver
database.url=jdbc:mysql://localhost:3306/webanno
database.username=webanno
database.password=t0t4llYSecreT

# 60 * 60 * 24 * 30 = 30 days
backup.keep.time=1000000

# 60 * 5 = 5 minutes
backup.interval=1000

backup.keep.number=10

ui.brat.sentences.number = 5

Fix permissions in WebAnno home folder

$ chown -R www-data /srv/webanno

Start WebAnno

$ service webanno start

Open it with your browser at http://localhost:18080/webanno. If you chose to run WebAnno behind the Apache web-server use http://localhost/webanno. The first time, it will create a username admin with password admin. login with this username and proceed.

Apache Web Server

mod_proxy

mod_proxy_ajp

Edit /opt/webanno/conf/server.xml and enable AJP Connector on localhost (comment in, add address, and change port

<Connector port="18009" protocol="AJP/1.3" redirectPort="8443" address="127.0.0.1"/>

Disable HTTP Connector (just comment it out)

<!--Connector port="8080" protocol="HTTP/1.1".
           connectionTimeout="20000".
           URIEncoding="UTF-8"
           redirectPort="8443" /-->

Edit /etc/apache2/conf.d/webanno.local

ProxyPreserveHost On

<Proxy ajp://localhost/webanno >
  Order Deny,Allow
  Deny from none
  Allow from all
</Proxy>

<Location /webanno >
  ProxyPass ajp://localhost:18009/webanno timeout=1200
  ProxyPassReverse http://localhost/webanno
</Location>

Restart Apache web server

$ service apache2 restart

Log into WebAnno and export all the projects that you wish to migrate using the Export pane in the project settings

Move your WebAnno home folder to a safe location so that WebAnno and create a new home folder in the old location

Copy the settings.properties and formats.properties (if present) back from your moved folder

Start the new WebAnno version to initialize the database

Recreate the users

When upgrading to WebAnno 2.x from a pre 2.x version, remove the format.properties file from the WebAnno home folder

Restart WebAnno and import the previously exported projects

Make a backup of your data before upgrading to a new version:

Standalone version

WAR version

Stop the current WebAnno Tomcat 6 instance

Move your old Tomcat instance out of the way

Install tomcat7-user package (this will automatically uninstall Tomcat 6)

Create new instance

Copy the WAR file over to the new instance

Stop the new WebAnno Tomcat 7 instance

The access permissions of the super admin have changed. Super admins can no longer access annotation, curation, and monitoring pages for all projects. They can only access them if they are annotators, admins, or curators in the respective projects. However, they still have full access to the project settings of all projects and can simply give themselves the missing permissions. After an upgrade to 3.0.0, all super admins who require project permissions on existing projects should assign these permissions to themselves. This also applies when importing old projects. For new projects, the creator of the project always starts with annotator, curator, and project admin permissions. If these permissions are not required by the project creator, they should be removed after project creation.