Page tree
Skip to end of metadata
Go to start of metadata


Useful Contacts


These instructions describe how to install the TextVRE software on a Debian system.

There are four mains steps required for installation:

  1. Install prerequisite software
  2. Checkout TextGrid software from svn
  3. Install and configure rbac/tgauth
  4. Configure, build and install TextGrid webservices.

Where you see the URL in the installation instructions, you should replace this with the address of your own server.

These installation instructions assume that you have the following ports open on your firewall:

  • 8080
  • 8180
  • 8443
  • 8081

If you want to use an ldapbrowser to manage the ldap contents from a remote machine, then you will also need port 389 open.

On the machine where you will be building the TG-* webservices, you will need to have maven and have a Java JDK installed, at least version 1.6. On the machine where you will be installing TextGrid, you will need to have a Java JDK installed, at least version 1.6.

Install Prequisites

The following need to be installed:

  • apache httpd
  • tomcat
  • php
  • openldap
  • fedora
  • sesame
  • eXist

Apache HTTPD

Install using apt-get:

sudo apt-get install apache2 
/etc/init.d/apache2 start

Sets up httpd in /etc/apache2

Add the following aliases in /etc/apache2/httpd.conf, as they are needed to interlink between rbac and tgcrud:

Alias /rbac "/var/www/rbac/rbacSoap" 
Alias /WebAuthN "/var/www/htdocs/WebAuthN"

Note that the sesame database does not have http authentication. To protect it, we need to limit access to localhost by adding to the apache configuration: In httpd.conf add the following: (remembering to substitute the name of your own server):

<Location /openrdf-sesame/ >
  ProxyPass http://localhost:9090/openrdf-sesame/ retry=0
  ProxyPassReverse http://localhost:9090/openrdf-sesame/
  Allow from all
  <LimitExcept GET>
    Require valid-user

Apache Tomcat

sudo apt-get install tomcat6

Edit /etc/tomcat6/server.xml to listen on port 8180 (default is 8080):

<Connector port="8180" protocol="HTTP/1.1"
  redirectPort="8443" />


sudo apt-get install php5
sudo apt-get install php-soap 
sudo apt-get install php5-ldap


(install following instructions at

sudo apt-get install slapd ldap-utils libldap-2.4.2 libdb4.6

When asked for a root password, enter 'secret'. Installed as /etc/ldap (exact location may vary on your installation).


Download the latest version of the Fedora installer from (3.4.2 was used for this installation)

java -jar fcrepo-installer-3.4.2.jar
  • choose quick install
  • target /usr/local/fedora
  • when prompted for admin password, use "admin"
  • edit /usr/local/fedora/tomcat/conf/server.xml to change port number to 8081
<Connector port="8081" protocol="HTTP/1.1"
  connectionTimeout="20000" redirectPort="8443"
  enableLookups="true" acceptCount="100" maxThreads="150"
  minSpareThreads="25" maxSpareThreads="75" URIEncoding="UTF-8"/> 

Move shutdown port to 8006 otherwise this may conflict with tomcat.

To add fedora to startup sequence do

ln -s /usr/local/fedora/tomcat/bin/ /etc/init.d/fedora 
update-rc.d fedora defaults


openrdf sesame 2.6.4

  • download openrdf-sesame-2.6.4-sdk.tar.gz from
  • untar
  • copy wars to /var/lib/tomcat6/webapps
  • mkdir /usr/share/tomcat6/.aduna
  • chown tomcat6:tomcat6 /usr/share/tomcat6/.aduna
  • create textgrid repository (the dot at the end of console commands is important)
  • cd openrdf-sesame-2.6.4
  • bin/
  • connect http://localhost:8180/openrdf-sesame.
  • create native.
    • here you give the id "textgrid" and a title "textgrid native store", set indexing to spoc,posc,opsc,sopc
    •  /var/lib/tomcat/webapps/sesame/WEB-INF/web.xml, you should see that there is a security constraint for "sesame-admin".
  • To match this, create a "sesame-admin" role in tomcat-users.xml, and create a sesame user with the sesame admin role.
  • Create the user as user=workbench, password=textvre1

eXist 1.4.1


Download jar from

At the time of writing of these notes, 1.4.1 was available at

mkdir /usr/local/exist
java -jar eXist-setup-1.4.1-rev15155.jar -p /usr/local/exist

By default eXist will install with a jetty server on port 8080. This is fine and does not need to be changed.

Start the server using the following command:

./bin/ &

Set username/password by browsing to and use management interface to set admin username and password ("admin", "textvre1").

To integrate exist in the startup sequence do

ln -s /usr/local/exist/tools/wrapper/bin/ /etc/init.d/exist
update-rc.d exist defaults

To configure Memory settings look into /usr/local/exist/tools/wrapper/conf/wrapper.conf.

Using wrapper the logs go to /usr/local/exist/tools/wrapper/logs, you may add a symlink to a more convenient place, e.g.:

ln -s /usr/local/exist/tools/wrapper/logs /usr/local/exist/logs

Checkout from SVN

All files checked out from

Checkout the following modules:

  • tgconf 9856
  • tgcrud revision 11568
  • tgsearch 11582
  • tgauth 11560

Setting up RBAC / TG-auth

Set up LDAP

rbac/tgauth expects to find specific information setup in ldap. Throughout the configuration files, there are entries of the form dc=textgrid,dc=de These are used as the base for ldap operations.

I would recommend that you stick with dc=textgrid,dc=de otherwise you will need to replace all occurrences in the following configuration files with your own base This base value is not visible to users so there is little to be gained from changing it.

LDAP needs two initial configuration files, slapd.conf and rbac-data.ldif, here:

For convenience, you might also want to edit the file ldap.conf such that ldapsearch, ldapadd and further clients on this machine have the default values matching your server. Adjust the following entries:

BASE dc=textgrid,dc=de
URI ldap://	(change this to ldap//your server's address)
HOST (change this to your server's address)

Copy slapd.conf and ldap.conf into your ldap directory (e.g. /etc/ldap or /etc/openldap)

Copy the files from tgauth/info.textgrid.middleware.tgauth.rbac/ldap-schemas to your ldap's schemas directory and adjust this location in slapd.conf. (It is the only thing that you should have to edit in slapd.conf):

include /etc/ldap/schema/core.schema etc.

Check that the configuration is correct by running slaptest:

	/usr/sbin/slaptest -f slapd.conf

Start the ldap server:

    /usr/sbin/slapd -f slapd.conf

Rename rbac-data.ldif to ldap-template.ldif and add the permssions data contained in that file (replace BindDN and BindPassword with the Manager's rootdn and rootpw found in slapd.conf) as:

    ldapadd -x -f ldap-template.ldif -D BindDN -w BindPassword

Set up RBAC

copy tgauth/info.textgrid.middleware.tgauth.rbac to /var/www/rbac cd /var/www/rbac mkdir conf cd conf copy the files rbac.conf, rbacSoap.conf, system.conf into this directory from tgauth/info.textgrid.middleware.tgauth.rbac/conf-dist

In rbac.conf: --- replace all instances of with the address of your server. --- replace all instances of "XXXXXXXX" with "testing123"

In rbacSoap.conf: Where you see the following text, change "XXXXXXXX" to "secret"

		<section name="crud">
		    <var name="secret">XXXXXXXXXX</var>
		  <section name="webAuth">
		    <var name="secret">XXXXXXXXXXXXXX</var>
		  <section name="SIDcheck">
		    <var name="secret">XXXXXXXXXXXXX</var>

Change all instances of to the address of your server Change all remaining instances of "XXXXXXXXXXX" to "testing123"

		cd ../rbacSoap
		mkdir wsdl
		cd wsdl
		copy tg*.wsdl from rbacSoap/wsdl-productive into the current directory
		edit tg*.wsdl
			change soap address at end of file eg. for tgextra.wsdl:
					<soap:address location="" />	
		copy trunk/middleware/tgauth/info.textgrid.middleware.tgauth.webauth to /var/www/htdocs
		cd /var/www/htdocs
		copy config_tgwebauth-dist.xml to config_tgwebauth.xml

In config_tgwebauth.xml, your contents should look like the following

		<?xml version="1.0" encoding="UTF-8"?>
		<conf xmlns="">
		  <authn type="community">
		    <key name="host"></key> 
		    <key name="port">389</key>
		    <key name="binddn">uid=${login},ou=users,dc=textgrid,dc=de</key>
		    <key name="basedn">ou=users,dc=textgrid,dc=de</key>
		    <key name="filter">(uid=${login})</key>
		    <key name="IDattribute">eduPersonPrincipalName</key>
		    <key name="name">TextGrid Community Authentication Server</key>
		    <key name="setAttributesDN">cn=attributewriter,ou=bindaccounts,dc=textgrid,dc=de</key>
		    <key name="setAttributesPW">testing123</key>
		  <authz instance="rbac">
		  <!-- more RBAC authz instances to follow if you like -->

Make sure Apache does not serve the WebAuthN config file (PHP scripts will access it only via the file system). Add this to /etc/apache2/sites-enabled/000-default:

       <Location /htdocs/config_tgwebauth.xml>
       		 Order deny,allow
		 Deny from all

The line <text>/var/tou_en_200611.txt.html</text> identifies an html file that will be displayed when a user logs in for the first time. Replace this with content suitable for your installation.

Host should be changed to the address of your ldap server rbacbase should be set to <address of your server>/rbac/ setnamesecret specifies a token that is used to authenticate between rbac and webauth. just leave this as secret (or whatever you set at RBAC's webAuth section as secret) do not change any other values!

		cd /var/www/htdocs/WebAuthN
		edit TextGrid-WebAuth.php to use the correct configuration file, ie
			$configfile = "../config_tgwebauth.xml";
		edit authenticate.php
		edit PutAttributes.php
			$configfile = "../config_tgwebauth.xml";	

test by loading the following urls in a browser (subsituting the address of your own server):

		 "Asking for a session-ID...
			DONE: W4vhhHyGOHc8FxqE18btpLVWaPfvcAkVDVxEWJmPqKDz0n2xGuXF0Dc1318959171175494"

OpenLdap sometimes experiences problems with importing passwords. If you experience problems, use slappasswd to generate a password to a file, then use ldapbrowser to import the password. Please search online for instructions on how to do this.

Building and Installing TextGrid Services

Installing TG-crud

You need to edit tgcrud/services/tgcrudservice/tgcrud-base/src/main/webapp/WEB-INF/TGCrudService.wsdl If you have been following the instructions so far, you will need to change the port number to 8180 to match your installation

	<wsdl:service name="TGCrudService">
				<wsdl:port name="TGCrudPort" binding="tns:TGCrudServiceSOAP">
					<soap:address location="http://localhost:8180/tgcrud/TGCrudService" />

You then need to edit tgcrud/services/tgcrudservice/tgcrud-base/pom.xml

In the section <execution><id>get-services-stubs</id>, under <tasks> change the address to your host, for example:

		<get dest="./tgextra-crud.wsdl" 
			verbose="true" usetimestamp="true"/> 
		<get dest="./tgextra.wsdl" 
			verbose="true" usetimestamp="true"/> 

Note that the address specifed here must be visible at compilation time.

Edit properties in /tgcrud/services/tgcrudservice/tgcrud-base/src/main/webapp/WEB-INF/ contains a lot of properties. Most properties can be left as they are, but the following properties must be changed to match your local installation: (again, remember to substitute the address of your own server)

	TGEXTRA_URI =                       
	TGEXTRA_RBAC_SECRET = secret	(this must match the value you provided for setnamesecret in the rbac installation)
	RDFDB_USER = workbench
	RDFDB_PASS = textvre1
	XMLDB_USER = admin
	XMLDB_PASS = textvre1

	XMLDB_METADATA_PATH = db/metadata/
	XMLDB_BASELINE_PATH = db/structure/baseline/
	XMLDB_ORIGINAL_PATH = db/structure/original/
	XMLDB_AGGREGATION_PATH = db/structure/aggregation/
	XMLDB_QUERY_PATH = db/generic/query/

you will also need to add the following properties for accessing the Fedora instance:

	# access details for fedora
	fedora.username = fedoraAdmin
	fedora.userpass = admin
	fedora.url = http://localhost:8081/fedora

build the war file using maven: in a commandline, change to tgcrud\services\tgcrudservice

	export MAVEN_OPTS="-Dfile.encoding=UTF-8"
	mvn clean
	mvn install package

The war file is built as tgcrud/services/tgcrudservice/tgcrud-base/target/tgcrud.war when the war file has built, copy it to your tomcat webapps directory IMPORTANT NOTE: there is currently a minor build issue - the library xercesImpl-2.7.1.jar must be manually copied into the tgcrud lib directory once tomcat has started, then tomcat restarted. The library is needed by the jena framework within tgcrud, but causes conflicts with the build system if it is included in the build.

Note: In TEXTvre the TG-crud V1.0 is used so far, for current TG-crud V2.0 installing instructions please refer to the TG-crud documentation page!

Configuring TG-crud

To change (or move) the TG-crud configuration and logging files to the TextGrid places (now /etc/textgrid/ and /var/log/textgrid/), just use the following commands. TG-crud's config file now (since Rev. 11678) is configured via Spring in the beans.xml file located in /webapps/tgcrud/WEB-INF/.

  • tgcrud configuration
    • mkdir /etc/textgrid/
    • mkdir /etc/textgrid/tgcrud/
    • cp /usr/local/tgcrud/tgcrud.log4j /etc/textgri/tgcrud/
    • cp /usr/local/tgcrud/conf/ /etc/textgrid/tgcrud/
    • set log4j config file in /etc/textgrid/tgcrud/ to "/etc/textgrid/tgcrud/tgcrud.log4j"
    • set owner and permissions
      • chown -R tomcat6:adm /etc/textgrid/tgcrud/
      • chmod -R 750 /etc/textgrid/tgcrud/
    • set the tgcrud config file location in the beans.xml file: change constructor-arg value to "/etc/textgrid/tgcrud/"
  • logging configuration
    • set log locations in /etc/textgrid/tgcrud/tgcrud.log4j
      • log4j.appender.rolling_daily.File = /var/log/textgrid/tgcrud/rollback.log
      • log4j.appender.rolling.File = /var/log/textgrid/tgcrud/tgcrud.log
    • mkdir /var/log/textgrid/
    • mkdir /var/log/textgrid/tgcrud/
    • set owner and permissions
      • chown -R tomcat6:adm /var/log/textgrid/tgcrud/
      • chmod -R 750 /var/log/textgrid/tgcrud/
  • deleting old config and log folders
    • rm -rf /usr/local/tgcrud/

Installing TG-conf (confserv)

TODO: zip new tgconf and attach here

  mv /var/www/confserv/getAllJ.php /var/www/confserv/getAllJ
  • add following lines to /etc/apache2/sites-enabled/000-default
  <Location /confserv/getAllJ>
    SetHandler php5-script
  • Copy /tgsearch/tgsearch-webapp/src/main/webapp/WEB-INF/ to /tgsearch/tgsearch-webapp/src/main/webapp/WEB-INF/
  • Edit the following properties in
tgauth.endpoint = 
sesame.endpoint = 
exist.endpoint = 
exist.user = admin = textvre1 
sesame.user = workbench = textvre1 
	cd tgsearch/
	mvn package -Pnonpublic

builds tgsearch.war in tgsearch/tgsearch-webapp/target/tgsearch.war Copy to webapps area on tomcat server.

There is a set of scripts that need to be added to the exist installation. To do this, start the exist client as above and log into the exist instance. There is an exist sub directory in the tgsearch directory. Replicate the directory structure in exist by Tools->Create Collection and work down through the structure. Once this is complete, import all the files at the appropriate point in the structure. Note that the following files need to be edited before adding to eclipse:

  • exist/db/tgsearch/2.0.1/modules/agghelp.xqm
  • exist/db/tgsearch/2.0.2/modules/agghelp.xqm
  • exist/db/tgsearch/2.0.3/modules/agghelp.xqm

In each of these files, there are references to a openrdf-sesame repository. These references must be changed to match your local installation, for example:



Please have a look at the TG-publish documentation page. TEXTvre specific issues will be documented here.

To simplify the TEXTvre life, and if no public TG-crud instance is needed for direct ingest (and therefore no public Fedora storage location), I would recommend the following:

  • Implement the moveData() method in Fedora Storage Implementation to not throw an exception if called, just return and do nothing. So the data is not really MOVED anywherre, but TG-publish does all other things involved in publishing.
    • ...or just set up a public Fedora instance, and change TG-crud and TG-crud public configuration to write to the public Fedora instance...
  • Configure TG-publish to use the one and only TG-crud also to be used for public usage.
    • ...or use the public Fedora instance with the public TG-crud...
  • Set up a second (public) search instance, including eXist and Sesame.

Installing TG-crud public

Just do set up another instance of the tgcrud, using a tgcrud WAR file named tgcrud-public.war, and do deploy it into the tomcat. Configure it just like the other TG-crud, put the config and log files to e.g. /var/log/textgrid/tgcrud-public and /etc/textgrid/tgcrud-public, and do the following changes to the configuration:

set DEFAULT_GAT_URI and DEFAULT_GAT_URI_PUBLIC to the public storage
set all other URLs and user/password settings of eXist and Sesame to the public storage locations

Now this public TG-crud instance knows, it has to directly publish using #CREATE, and has unneeded methods disabled.

Setting up TG-search public and the TextGrid Repository website

Install second eXist instance

Install eXist into /usr/local/exist-public like described here: eXist 1.4.1 

modify /usr/local/exist-public/tools/jetty/etc/jetty.xml to use port 8999 

you may set symlinks and add to startup sequence accordingly -> eXist 1.4.1

saxon xslt needs to be used:

$ cd /usr/local/exist-public/lib/user/
$ wget -U NoSuchBrowser/1.0
$ wget -U NoSuchBrowser/1.0
$ wget -U NoSuchBrowser/1.0

edit /usr/local/exist-public/conf.xml to use saxon:

find the line

 <transformer  class="org.apache.xalan.processor.TransformerFactoryImpl" caching="yes"/>

and replace with

 <transformer class="net.sf.saxon.TransformerFactoryImpl">
   <attribute name="" value="false" type="boolean"/>

startup exist and insert contents from into the database.

Sesame public repository

Add a repository textgrid-public to sesame .

Install TG-search public

like in Install tgsearch , but build with "mvn package" (not -Pnonpublic) and install the tgsearch-public.war to tomcat

Setup TextGrid Repository website

$ cd /var/www
$ svn co tgrep

edit tgrep/js/conf.js , set sandbox to false

Add proxy config to /etc/apache/sites-enabled/000-default

 <Location /services/tgcrud-public >
   ProxyPass http://localhost:8180/tgcrud retry=0
   ProxyPassReverse http://localhost:8180/tgcrud
   Allow from all
 <Location /services/exist-public/xslt >
   ProxyPass http://localhost:8999/exist/rest/xslt retry=0
   ProxyPassReverse http://localhost:8999/exist/rest/xslt
   Allow from all
 <Location /services/exist-public/xql >
   ProxyPass http://localhost:8999/exist/rest/tgsearch/2.0.1/query retry=0
   ProxyPassReverse http://localhost:8999/exist/rest/tgsearch/2.0.1/query
   Allow from all
 <Location /services/tgsearch-public >
   ProxyPass http://localhost:8280/tgsearch-public retry=0
   ProxyPassReverse http://localhost:8280/tgsearch-public
   Allow from all
 <Location /services/sesame >
   ProxyPass http://localhost:8180/openrdf-sesame retry=0
   ProxyPassReverse http://localhost:8180/openrdf-sesame
   Allow from all
   <LimitExcept GET>
     Require valid-user
 <Location /services/tgpublish >
   ProxyPass http://localhost:8280/tgpublish retry=0
   ProxyPassReverse http://localhost:8280/tgpublish
   Allow from all
 <Location /services/tgsearch >
   ProxyPass http://localhost:8180/tgsearch retry=0
   ProxyPassReverse http://localhost:8180/tgsearch
   Allow from all
 <Location /services/tgcrud >
   ProxyPass http://localhost:8180/tgcrud retry=0
   ProxyPassReverse http://localhost:8180/tgcrud
   Allow from all

 <Location /fedora >
   ProxyPass http://localhost:8081/fedora retry=0
   ProxyPassReverse http://localhost:8081/fedora
   Allow from all

 Alias /PWchange /var/www/PWchange/htdocs
 <Directory "/var/www/PWchange/htdocs/*">
   Options +FollowSymLinks
   Order Allow,Deny
   Allow from all

now you should be able to browse published content on http://localhost/tgrep/

TODO: only some proxy forwards are necessary for tgrep, move the others to generic apache config

Adding New Users

Currently, new users have to be added directly in ldap.

	ldapsearch -x -D "cn=Manager,dc=textgrid,dc=de" -w secret -b "ou=users,dc=textgrid,dc=de" > result.ldif

then pick one user entry from the ldif file, copy it into a new file "user.ldif" (eg "Malcolm" and replace the necessary values. Add the new user using ldapadd:

	ldapadd -D "cn=Manager,dc=textgrid,dc=de" -w secret -x -f user.ldif

Publish TEI Schema to VM

Get a List of XML Schemata you might be interested in:

Download the interesting ones to your local HD, e.g:

# TEI with all modules enabled
wget -O h5fb.0
wget -O h5fb.0.meta
# TEI Lite
wget -O h5fc.0
wget -O h5fc.0.meta


Startup TextGridLab and point the confserv to your installation. Login and create a new Project "Technical Objects". Import your just downloaded files into this project using "File->Import local files" from the menu.

  • No labels