Installation of the Software for Discovery Partners

    1. Installation of the Software for Discovery Partners
    2. Prerequisites
      1. mySQL database
      2. Java and JRuby + Ruby packages
      3. Web and Java Application server
      4. Vips and the IIP server
    3. Download the Talia platform
      1. Entering the Talia Shell
    4. Configuring the Platform
    5. Importing the data
      1. Import of Hyper-formatted data
      2. Import of "Sophiavision" CSV data
    6. Creating Simple Editions
    7. Testing the installation
    8. Deploying to the Java Application server
      1. Setting up the proxy forwarding
      2. Setting up static data
      3. File Permissions
      4. Deploying
    9. Manually creating the WAR file
    10. Helpful stuff
      1. Sample apache config for proxy forwarding

(There is also an installation Guide for the CMS that you may (optionally) want to use. If you want the eXist-based search service, you will have to install some additional servlets: ExistAndServletsInstallation)

This page tells you how to set up the software that you will need to run your library. This guide is specific for the customized version that is deployed by the partners of the Discovery Project. It assumes that you run a Mac OS 10.5 (Leopard) Server in the most recent version.

You can download the Talia installer packages from our server. In most cases you should avoid the "discovery_full" installer. It may not contain the most recent version of Talia, and may attempt to install packages that are unnecessary for your system.

Prerequisites

These are the prerequisites for installing the Talia platform. To enable this service:

mySQL database

The mySQL database is already installed on the Leopard Server. To enable this service:

  • Open the "Server Admin" Application
  • Select your "local" server in the list on the left
  • Select "Settings" and then "Services"
  • Check the "MySQL" checkbox and click "Save"
  • The "MySQL" service will now show up for your server
  • Select the service, and click "Settings"
  • Check the "Allow network connections" checkbox
  • Click the "Set MySQL Root Password" button to create a password for the MySQL root user
  • Now click the "Start MySQL" button to start the database

If you're not running the Leopard server, you will have download a package or install it in another way.

Java and JRuby + Ruby packages

This version of Talia is running in the Java virtual machine, using JRuby. Java 1.5 should be installed on your system, which it is by default on all recent version of MacOS. An appropriate version of JRuby and all necessary ruby packages is "bundled" with the Talia distribution.

Web and Java Application server

Talia needs to run in a Java Application server, such as Apache Tomcat or the new Glassfish server. For best performance it also needs a "normal" web server that acts as a frontend and serves static pages.

On the Mac OS server, Tomcat and the Apache 2.0 web server are already installed. To enable them:

  • Use the Server Admin tool to add the "Web" service to your local server, in the same way as the MySQL service.
  • Select the "Web" service and click "General". Check the "Enable Tomcat" checkbox.
  • You can also click on "Sites" and disable all the web service you do not need (such as Webmail)
  • If you're done with the configuration, click the "Start Web" button

If you don't run the Mac OS server, you'll need to install the web servers yourself. Apache will be pre-installed for almost all systems, and our download section contains a Glassfish package that will work with Mac OS Leopard (client or server). If you use the IIP image server (see below), your web server must support running fastcgi binaries.

Vips and the IIP server

These things are only needed if you want to show facsimiles on your site. The IIP image server is a server that lets you display, view and zoom large images. It runs as a fastcgi binary inside Apache (or another fastcgi-enabled web server). To prepare the facsimile images, you will need the image processing tools VIPS and ImageMagick.

For MacOS 10.5., we provide packages for those (these packages are compiled for Mac OS 10.5. with Intel Processors only. They will not work for other systems or architectures!):

The IIP server will not run without the Vips package installed, since it depends on some libraries in there. If you're not running Mac OS 10.5. you'll have to download and compile the packages yourself.

Download the Talia platform

The preferred method of installing the Talia platform is to directly download it from Github. From the command line, do the following: 

git clone git://github.com/net7/talia.git discovery_app
cd discovery_app
git checkout --track -f -b discovery origin/discovery
git submodule init
git submodule update
./fetch-jruby.sh

The fetch-jruby script will download a prepackaged JRuby distribution with all packages that are necessary for running Talia.

Entering the Talia Shell

Instead of setting all environment variables for JRuby and Talia, you can just open a new shell using 

./talia.sh shell

in the Talia directory.

Configuring the Platform

In order to configure the platform, you can use the configuration script included with the distribution: 

jruby lib/scripts/configure_talia


Talia Configuration Tool for Discovery

This script will assist you in setting up your Talia instance for deployment

Enter the location of the mysql sock file.
For the self-installed mySQL version on MacOS enter /tmp/mysql.sock
Keep the default if you use the builtin mySQL of MacOS X Server.
MySQL sock file (/var/mysql/mysql.sock):

If you're using Mac OS Leopard (Server) and you use the built-in mySQL server, you can just hit <Return>. Otherwise you need to enter the path to the mySQL "sock file". The default file for the mySQL Mac OS distribution is /tmp/mysql.sock.

In the next step you have to enter the root password for mySQL. On the Mac server, just enter the password that you created using the "Server Admin" Utility. For the Mac OS distribution from mysql.com, you just hit <Return> (empty password) - this is also the default in many other cases.

If you hit <Return> for an empty password, the tool will ask if you'd like to change the root password for added security. 

Enter the mySQL root pasword: 

Your root password is empty. This is not good.
Do you want to set a new one? (yn)

Enter the mySQL username for your application. This account will be created automatically.
mySQL account for the application: xxxx
Enter the password for this account: xxxx

You will then be prompted for a user name and password for the SQL database that is used by Talia. You can just select any user/password, it will be created together with the databases. 

Do you want to create the databases now? (yn)

Enter 'y' in order to let the script create the databases for your application. Note: If you need multiple applications on one machine, you can use the configuration script for the first installation, but you should create the subsequent ones manually. 

Loading the configuration templates... done.

Enter the URI for your site: http://fobar.com/

Enter the URL of your site. This should be the exact URL that is used to access your site. The site URL will also be part of the URL of the digital resources. Enter a trailing / (Example: http://www.hypernietzsche.org/) 

Enter the URL of your IIP server, or the port number (for default URL on localhost): 
Setting IIP URL to: http://localhost:/fcgi-bin/iipsrv.fcgi

Enter the URL for the IIP server (which is the URL pointing to the iipsrv.fcgi) Note: The IIP URL must be in the same DNS domain as the site URL. Otherwise the IIP client will not be able to connect. The suggested value is <your URL>/iip/ (Example: http://www.nietzschesource.org/iip/). 

Enter the path to store the IIP image files (return for default): 
Enter the path to store all other data files (return for default):

Here you can enter the file names for the "normal" data files (XML, thumbnails, ...) and for the images that are served from the IIP server. If you hit <Return> on those questions, the will go into a default directory inside the discovery_app. Note: To deploy the application to the Java application server, please enter a absolute path to an existing directory here. The Java application will never work with "default" locations!

The suggested values for the data locations on the Mac OS server are:

  • /usr/local/talia/<prefix>_iip
  • /usr/local/talia/<prefix>_talia_data
  • /usr/local/talia/<prefix>_sesame 
Enter the path to store all other data files (return for default): http://static.mysite.org/

This allows you to select a URL from which Talia will load static data (e.g. images, thumbnails). If you press return here, it will use a build-in default handler, which will work automatically but is really slow for pages with lots of thumbnails.

Note: Remember that if you want to serve static pages, you will have to make your "normal" data directory available to apache. This setting doesn't affect data that isn't inside Talia, such as linked videos or the images served through IIP. 

Do you want to write the configuration now? (Overwrites the existing config!) (yn)

If you select 'y' this will create (or overwrite) Talia's configuration files for you. Otherwise it will save a copy of the new configuration in the config/ directory. 

Now migrating the databases
(in /Developer/Talia/discovery_app)
...

The script will now setup the environment for Talia. If the configuration is good you should see a number of messages, but no errors. 

Customize the start page. The following custom start pages are available:
0 - nietzschesource
1 - sophiavision
Enter the number of the customization: 0
Copied _start_page_nietzschesource.html.erb to custom page.

Customize the header image for the start page.
The following image combinations were found: 
0 - nietzsche
1 - sophiavision
Enter the number of the customization:

In the last step you can select some customizations, configuring the content that will show up on the home page and the images that are used for the header of the home page. You'll just have to select one of the preconfigured customizations for each of the questions.

This will conclude the interactive part of the configuration. The script will now try to build a .war file of the application that can be used for deployment.

Attention: When deploying the application to a production server, make sure that the ontology autoloading is not enabled in the configuration file. Delete the respective line if it exists. To load the ontologies manually you should: 

rake talia_core:rdf_import files=ontologies/*.owl rdf_syntax=rdfxml
rake talia_core:owl_to_rdfs_update

before the deployment.

Importing the data

Talia has different methods of importing data. The most used will be this one:

Import of Hyper-formatted data

# rake discovery:hyper_import base_url= list_path=<path to index xml> doc_path=<path to data xml> extension=.xml

You can use this task to download data directly from a Hyper installation, but it's usually more reliable if you download the data using the hyper_downloader script.

The list_path should point to an XML document listing the sigla of all elements you want to import and the doc_path to the directory containing the XML files for the sigla (and a data subdirectory with all attached data).

Data created with the Fabrica2 tool can also be imported in this way.

Import of "Sophiavision" CSV data

This is only used to import the Sophivision data. The data should be exported in the CSV format as produced from the Mac OS Excel 2004 (\r for linebreaks, ; as separator sign, Mac encoding), though you can choose the character encoding for the task. 

# rake discovery:sophia_csv csvfile=<data from sophiavision> thumbnail_directory=<directory with thumbnail images>

The thumbnail directory is assumed to contain a jpg file for each video with the same name as the video's MP4 stream (only with a .jpg extension). The thumbnails should have a size of 96x72 pixels.

Creating Simple Editions

The initial release of Talia supports two types of "simple" editions: Facsimile and Critical. You can create the from the command line using 

# rake discovery:create_color_facsimile_edition nick=edition name="My Edition" \
  description="Some text for my edition" header=nietzsche_blue \
  catalog=CAT

or 

rake discovery:create_critical_edition nick=edition name="My Edition" \
  description=desc.html header=nietzsche_yellow \
  catalog=CAT

respectively. The main difference is that the critical edition will take the path to an html file as a description.

  • nick - This is the "siglum" of the edition an will also be the last part of it's URL. Best to use only plain characters and no spaces.
  • name - A human readable name that will be used in the interface to refer to this simple edition
  • description - Descriptive text about this edition
  • header - This must be the exact name of a subfolder of customization_files/header_images. The new edition will use the header image contained in that folder.
  • catalog - This is optional. If given, it will only put things from the given catalog into the new simple edition

Testing the installation

Before you attempt to deploy Talia on the Java application server, you should try if everything runs correctly by starting the builtin server. 

jruby script/server -p <port number>

This start the server, see if you get any error messages and if you can browse the site now.

Deploying to the Java Application server

The following assumes - again - that you're running Mac OS Leopard Server; the instructions should apply to other server too, though. Tomcat on Mac OS X (the preinstalled version) seems to run into memory problems. It's possible to set the heap size and perm size in /Library/Tomcat/bin/setenv.sh: 

#!/bin/sh
export CATALINA_OPTS="-Xms1512m -Xmx1512m -XX:MaxPermSize=256m"

Setting up the proxy forwarding

The suggested solution is to not use Tomcat directly, but use Apache as a front-end server that will also serve the static content. Apache will also have to host the IIP server, if you use this.

The suggested setup is to use mod_proxy to forward your site to the tomcat web application that hosts Talia. You should also add a rule for IIP that will make it available at <yourhost>/iip

A sample configuration from nietzschesource.org is attached at the end of this guide. Very important: You need to either make the "default" virtual host /etc/apache2/sites/0000_any_80.conf (or something like that) to something that doesn't match all subdomains, or move it to 000X_any... (where X is greater than all existing numbers. Otherwise the catch-all domain will be matched first, and your other virtual hosts may not work. (You can also try to change the order in the admin interface, but not guarantee on that...)

You must make manual changes to the config files, and you must not change the sites using the config panel afterwards. Otherwise the config panel could destroy your configuration.

Setting up static data

To serve the static data, you need to make your "data" directory available on the web. During the configuration you should have entered a path to the static data directory and the URL that Talia will use for the static content. Basically, the directory must be available at that URL.

File Permissions

The Tomcat server needs to have permission for the "data" directory and on the sesame databases. You'll probably have to change ownership on this files to the user that is running tomcat (most likely _appserver on Mac OS X)

Deploying

Important: When you do the proxy/Tomcat setup, the web app must be deployed to the ROOT context of Tomcat. Otherwise the app will fail to work correctly. This also means that if you want to deploy several Talia instances to the same host, you must use virtual hosts in Tomcat. If you h deave only a single instance, you may deploy to the default ROOT context, but this will probably erase default pages (such as the web admin tool).

To create a virtual host in Tomcat (see also the documentation), you should add a host definition like the following to /Library/Tomcat/conf/server.xml, directly below the "localhost" definition: 

<Host name="my.talia.host"  appBase="webapps/myhost"
  unpackWARs="true" autoDeploy="true"
  xmlValidation="false" xmlNamespaceAware="false">

</Host>

and you will have to create the directory (as root): 

cd /Library/Tomcat/webapps
mkdir myhost
chown _appserver:_appserverusr myhost

(obviously you should replace 'myhost' with something more useful).

The actual deployment should only be a matter of: 

cp my_app.war /Library/Tomcat/webapps/myhost/ROOT.war

Manually creating the WAR file

If you need to re-create the war file (e.g. after an update, or because you changed the configuration) you can do this easily from the Talia shell: 

warble war:clean
warble

Helpful stuff

Sample apache config for proxy forwarding

<VirtualHost *:80>
	ServerName www.nietzschesurce.org
  ServerAlias nietzschesource.org
	ServerAdmin admin@example.com
	DocumentRoot "/Library/WebServer/Documents/"
	DirectoryIndex "index.html" "index.php"
	CustomLog "/var/log/apache2/access_log" "%h %l %u %t \"%r\" %>s %b"
	ErrorLog "/var/log/apache2/error_log"
	ErrorDocument 404 /error.html
	
	Alias /documentation/ /Library/WebServer/Documents/cms_nietzsche/web/
	Alias /iip/ /Library/WebServer/FCGI-Executables/
	Alias /static/ /usr/local/talia/nietzschesource_data/
	
	<Directory "/usr/local/talia/nietzschesource_data/IipData">
	  DefaultType image/jpeg
	</Directory>

	<Directory "/usr/local/talia/nietzschesource_data/ImageData">
	  DefaultType image/jpeg
	</Directory>	
	
	<Directory "/usr/local/talia/nietzschesource_data/XmlData">
	  DefaultType text/xml
	</Directory>
	
	<Directory "/usr/local/talia/nietzschesource_data/PdfData">
	  DefaultType application/pdf
	</Directory>
	
	<Directory "/usr/local/talia/nietzschesource_data/SimpleText">
	  DefaultType text/plain
	</Directory>

	<IfModule mod_ssl.c>
		SSLEngine Off
		SSLCertificateFile "/etc/certificates/Default.crt"
		SSLCertificateKeyFile "/etc/certificates/Default.key"
		SSLCipherSuite "ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:!SSLv2:+EXP:+eNULL"
	</IfModule>
	<IfModule mod_dav.c>
		DAVLockDB "/var/run/davlocks/.davlock100"
		DAVMinTimeout 600
	</IfModule>
	<IfModule mod_mem_cache.c>
		CacheEnable mem /
		MCacheSize 4096
	</IfModule>
	<Directory "/Library/WebServer/nietzsche_source">
		Options All -Includes -ExecCGI +MultiViews -Indexes
		AllowOverride None
		<IfModule mod_dav.c>
			DAV Off
		</IfModule>
                AuthType Basic
                AuthName "site protected"
                AuthUserFile /Library/WebServer/nietzsche_source/.htpasswd
                Require valid-user
        </Directory>
	<IfModule mod_rewrite.c>
		RewriteEngine On
		RewriteCond %{REQUEST_METHOD} ^TRACE
		RewriteRule .* - [F]
	</IfModule>
	<IfModule mod_proxy_balancer.c>
                <Proxy http://www.nietzschesource.org:8080/>
                    BalancerMember http://www.nietzschesource.org:8080
                    AuthType Basic
                    AuthName "site protected"
                    AuthUserFile /Library/WebServer/nietzsche_source/.htpasswd
                    Require valid-user 
                </Proxy>
	  # No Proxy for these paths
		ProxyPass /iip/ !
		ProxyPass /documentation/ !
		ProxyPass /static/ !
		# Proxy to rails
		ProxyPass / http://www.nietzschesource.org:8080/
		# ProxyPass / http://127.0.0.1:3000/
	  ProxyPassReverse http://www.nietzschesource.org:8080/ /
	  # ProxyPassReverse http://127.0.0.1:3000/ /
	</IfModule>
	<IfModule mod_alias.c>
		Alias "/collaboration" "/usr/share/collaboration"
		Alias "/icons/" "/usr/share/httpd/icons/"
		Alias "/error/" "/usr/share/httpd/error/"
	</IfModule>
#	Include /etc/apache2/httpd_users.conf
#	Include /etc/apache2/httpd_directory.conf
#	Include /etc/apache2/httpd_groups.conf
#	Include /etc/apache2/httpd_teams_required.conf
	LogLevel warn
	
</VirtualHost>

</VirtualHost>

Attachments