System Requirements
Browser |
Chrome or Safari |
Java Runtime Environment |
version 7 or higher |
Java Runtime Environment |
version 7 or higher |
Apache Tomcat |
version 6 or higher |
MySQL Server |
version 5 or higher |
Installation
Prerequisites
-
This guide assumes Debian 6.0.0 (Squeeze). 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.
Prepare database
-
Install MySQL
$ sudo apt-get install mysql-server
-
login to MySQL
$ mysql -u root -p
-
Create databases
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';
Dedicated Tomcat instance
-
Install Tomcat.
$ aptitude install tomcat6
-
Install package to install user-instances of Tomcat.
$ aptitude install tomcat6-user
-
Create new instance
$ cd /opt $ tomcat6-instance-create -p 18080 -c 18005 webanno $ chown -R www-data /opt/webanno
Now we have the /opt/webanno/ apache tomcat installation. You will put the <font color="red"> webanno.war</font> file in the /opt/webanno/webapps/ folder. If you get the war file in different name, such as Webanno-1.1-beta-10.war, PLEASE RE-NAME IT TO <font color="red">*webanno.war*</font>
* Configure the startup script. Edit /etc/init.d/webanno
and add the following contents:
#!/bin/sh export JAVA_OPTS="-Djava.awt.headless=true -Xmx750m -XX:+UseConcMarkSweepGC -Dwebanno.home=/srv/webanno" case "$1" in start) su -c "sh /opt/webanno/bin/startup.sh" www-data ;; stop) su -c "sh /opt/webanno/bin/shutdown.sh" www-data ;; restart) su -c "sh /opt/webanno/bin/shutdown.sh" www-data su -c "sh /opt/webanno/bin/startup.sh" www-data ;; esac exit 0
-
Make the script executable and register it to run during system start:
$ chmod +x /etc/init.d/webanno $ update-rc.d webanno defaults
Deploy WAR file
-
Place the WebAnno WAR into the Tomcat
webapps
folder:
$ cp webanno.war /opt/webanno/webapps/webanno.war
-
Create WebAnno home folder. This is the directory wher webanno settings files and projects (Serialized Cases, Source documents…) are stored
$ mkdir /srv/webanno
-
Optional If you want to test WebAnno with some sample data, skip the Users and permissions section and follow the instruction at [Sampledata], then come back here.
-
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
-
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 usehttp://localhost/webanno
. The first time, it will create a username admin with password admin. login with this username and proceed.
You can start with the SampleProjects to explore some of the functionalities.
Running behind Apache HTTPD
These are optional instructions if you want to run WebAnno behind an Apache web-server instead of accessing it directly. This assumes that you already have the following packages installed:
-
Apache Web Server
-
mod_proxy
-
mod_proxy_ajp
-
Edit
/opt/webanno/conf/server.xml
-
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
$ sudo /etc/init.d/apache2 restart
Database
WebAnno uses an SQL database to store project and user data.
We test MySQL using a MySQL server. WebAnno uses by default an embedded HSQLDB database. However, we recommend using the embedded database only for testing purposes. For production use, we recomment using a MySQL server. The reason for this is, that:
-
we do more testing on the MySQL server and
-
in the past, we had cases where we described in-place upgrade procedures that required performing SQL commands to change the data model as part of the upgrade. We promise to try avoiding this in the future. However, in case we offer advice on fixing anything directly in the database, this advice will refer to a MySQL database.
We try to keep the data model simple, so there should be no significant requirements to the database
being used. Theoretically, it should be possible to use any JDBC-compatible database after adding a
corresponding driver to the classpath and configuring WebAnno to use the driver in the
settings.properties
file.
Using HSQLDB in production
WebAnno displays a warning in the user interface when an embedded database is being used. In case
that you really want to run WebAnno with an embedded database in production, you probably want to
disable this warning. To do so, please add the following entry to the settings.properties
file:
warnings.embeddedDatabase=false
Upgrade
Exporting/importing
-
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
-
If you are using MySQL
-
create a new database for the new WebAnno version and update the settings.properties accordingly
-
use mysqldump to dump the tables
users
andauthorities
from the old database and load it back into the new database
-
-
If you are not using MySQL, you have to recreate the users manually
-
-
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
In-place update
This method should work when updating only a bugfix version, e.g. from 2.0.9 to 2.0.10. When performing a minor or major update, better use the exporting/importing method above.
-
Make a backup of your data before upgrading to a new version:
-
Make a copy of your WebAnno home folder
-
If you are using MySQL, make a backup of your WebAnno database, e.g. using the mysqldump command.
-
-
Standalone version
-
clean up the temporary installation before running the new version:
-
On OS X:
rm -R "$TMPDIR/winstoneEmbeddedWAR"
-
On Linux:
rm -R /tmp/winstoneEmbeddedWAR
-
On Windows: remove the
winstoneEmbeddedWAR
that should be somewhere underC:\Users\<username>\AppData\Local\Temp
-
-
start the new version
-
-
WAR version
-
while Tomcat is running, delete the old WAR from your
webapps
folder -
wait until Tomcat has automatically deleted the WebAnno folder
-
stop Tomcat
-
place the new WAR file into your
webapps
folder -
start Tomcat
-
System Properties
Setting | Description | Default | Example |
---|---|---|---|
webanno.home |
WebAnno home folder |
~/.webanno |
/srv/webanno |
javamelody.disabled |
Disable JavaMelody |
true |
false |
Settings
Setting | Description | Default | Example |
---|---|---|---|
database.dialect |
Database dialect |
org.hibernate.dialect.HSQLDialect |
org.hibernate.dialect.MySQL5InnoDBDialect |
database.driver |
Database driver |
org.hsqldb.jdbc.JDBCDriver |
com.mysql.jdbc.Driver |
database.url |
JDBC connection string |
location in WebAnno home |
jdbc:mysql://localhost:3306/weblab |
database.username |
Database username |
sa |
user |
database.password |
Database password |
sa |
pass |
database.initial-pool-size |
Initial database connection pool size |
4 |
|
database.min-pool-size |
Minimum database connection pool size |
4 |
|
database.max-pool-size |
Maximum database connection pool size |
10 |
|
backup.interval |
Time between backups (seconds) |
0 |
300 (60 * 5 = 5 minutes) |
backup.keep.number |
Maximum number of backups to keep |
0 |
5 |
backup.keep.time |
Maximum age of backups to keep (seconds) |
0 |
2592000 (60 * 60 * 24 * 30 = 30 days) |
crowdsource.enabled |
Enable crowdsourcing |
0 |
1 |
style.logo |
Logo image displayed in the upper-right corner |
unset |
path to an image file |
warnings.embeddedDatabase |
Warn about using an embedded database |
true |
false |
warnings.unsupportedBrowser |
Warn about unsupported browser |
true |
false |