Archive 1.x:StructWSF Installation Guide

From OSF Wiki
Jump to: navigation, search

Manual - 17 December 2012

Latest version
structWSF Logo
Last update
$Date: 2012/12/17 12:32:43 $
Revision
Revision: 0.6.1
Author
conStruct Logo
Frédérick Giasson - Structured Dynamics
Deepak Sahasrabudhe - Soma TV
Editors
Frédérick Giasson - Structured Dynamics
Michael Bergman - Structured Dynamics
Software versions
structWSF - 1.1
conStruct - 6.x-1.x-dev-9 (latest dev version)
Copyright © 2009-2012 by Structured Dynamics LLC; Soma TV.
Structured Dynamics LLC
Creative Commons License
This installation guide for structWSF & OSF-Drupal by Structured Dynamics LLC is licensed under a Creative Commons Attribution-Share Alike 3.0 license. The structWSF & OSF-Drupal software is separately available under the Apache License, Version 2.0.




Contents

Open Semantic Framework Installer

If you simply want to proceed to install the Open Semantic Framework. We would suggest you to use the OSF Installer.

Osf installer.png

About structWSF

structWSF is a platform-independent Web services framework for accessing and exposing structured RDF data. Its central organizing perspective is that of the dataset. These datasets contain instance records, with the structural relationships amongst the data and their attributes and concepts defined via ontologies (schema with accompanying vocabularies).

The structWSF middleware framework is generally RESTful in design and is based on HTTP and Web protocols and open standards. The initial structWSF framework comes packaged with a baseline set of about a dozen Web services in CRUD, browse, search and export and import. All Web services are exposed via APIs and SPARQL endpoints. Each request to an individual Web service returns an HTTP status and optionally a document of resultsets. Each results document can be serialized in many ways, and may be expressed as either RDF or pure XML.

In initial release, structWSF has direct interfaces to the Virtuoso RDF triple store (via ODBC, and later HTTP) and the Solr faceted, full-text search engine(via HTTP). However, structWSF has been designed to be fully platform-independent. Support for additional datastores and engines are planned. The design also allows other specialized systems to be included, such as analysis or advanced inference engines

About OSF-Drupal

OSF-Drupal [1] is a structured content system built on the structWSF framework [2] that extends the basic Drupal content management framework. OSF-Drupal enables structured data and its controlling vocabularies (ontologies) to drive applications and user interfaces.

Users and groups can flexibly access and manage any or all datasets exposed by the system depending on roles and permissions. Report and presentation templates are easily defined, styled or modified based on the underlying datasets and structure. Collaboration networks can readily be established across multiple installations and non-Drupal endpoints. Powerful linked data integration can be included to embrace data anywhere on the Web.

OSF-Drupal provides Drupal-level CRUD, data display templating, faceted browsing, full-text search, and import and export over structured data stores based on RDF.

Pre-Installation Considerations

IPv6 Not Supported

The IP version 6 protocol is not currently supported for structWSF. In order to make sure that structWSF is working on your server instance, you have to make sure that no IPv6 queries are used to query the Apache2 instance that is used for structWSF. This means that your Apache2 server can be configured to use IPv6 for other websites, but you have to make sure that all queries sent to a structWSF page are using IPv4.

You can test if your Apache2 server is listening using IPv6 by using this command:

netstat -tulpn

If you can see something like:

tcp6 0 0 :::80  :::* LISTEN 1016/apache2

It probably means that your server is using IPv6 for structWSF (except if you took care to listed specifically using IPv4 for the structWSF virtual host).

By default, Apache 2 will listen on IPv6 (and mapped IPv4) if the system it operates on is enabled for IPv6. If this is the case, we are not recommending to disable IPv6 on your server. Instead, we recommend to properly setup the Apache2 configs such that all queries sent against structWSF are necessary IPv4 queries. Read the Binding section of the Apache2 documentation for the options you have to properly setup your web server for using IPv4 for structWSF only.

INTRODUCTION

This guide is designed for the Ubuntu Linux distro (Server Edition) version 10.04 32bits (code named: Lucid). Also, this guide may not apply, or may need modifications, in specific areas related to other Linux packages (e.g., Debian, CentOS, Red Hat, etc.).

This installation guide is intentionally detailed - our purpose is to provide someone with limited technical skills with the actual commands necessary to create a working semantic processor. Some explanations have been provided with the intention of illuminating what the commands actually do.

This command set has been verified to work with Ubuntu 10.04. These commands will work on most Linux distributions based on Debian Linux (such as Ubuntu).

These directions include downloading and installation of some additional open-source packages that you may find useful during installation and beyond:

  • PhpMyAdmin which allows you to create and manage MySQL databases.

The following conventions are used in this document:

  • Black text is used for information and directions.
  • Magenta text represents commands that should be copied and pasted in Terminal
  • Green text is text to be cut and paste into a text editor (vim, vi, pico, etc.)
  • Orange text represents responses from the computer
  • Red text represents text in a command that you may wish to change to reflect your own names
  • Purple text represents something to notice.

STEP 1: INSTALL LINUX UBUNTU AND ITS UPDATES

Downoad and Install

  • Ubuntu is the Linux operating system and associated packages used for hosting this version of the system
  • For instructions on how to get and install Ubuntu Server Edition go to http://Ubuntu.com.

Refresh the Program Repository Access

When you have Ubuntu installed, you will have to update your Ubuntu installation with the latest program updates. The following command will update its list of all software available:

sudo apt-get update

Install Updates for Ubuntu

The following command will upgrade all software that have enhancement or security patches that can be applied:

sudo apt-get upgrade

Follow the steps that some of the upgraded software will prompt you to do in the terminal.


STEP 2: INSTALL PROGRAM DEPENDENCIES

Ubuntu is a version of the Linux operating system and associated packages used for hosting this version of the system. The latest version of Ubuntu should work. But it has been tested with hardy, jaunty and karmic.

Install System Dependencies

When Ubuntu has been installed and updated, you are ready install the system dependencies:

sudo apt-get install curl gcc iodbc libssl-dev openssl unzip gawk vim default-jdk

Install PHP

Install PHP and a few connector modules.

Note: For 64 Bit Ubuntu installations, there is a bug in the unixodbc libraries compiled in the default php packages. This causes apache to core dump when connecting to the virtuoso triplestore. Please use the following alternative installation strategy as a work around. Recompile PHP with iodbc
  • Copy / paste the following command into terminal:
sudo apt-get install php5 php5-mysql php5-odbc php5-cli libapache2-mod-php5 php5-curl php5-json
Note: make sure that you have PHP version 5.3.* or above installed from your packages

Configure PHP

Some default PHP configurations have to be changed in order to make it work properly.

  • Gnome-commander is a fast and powerful file manager. It is strongly suggested to not start without it (or use an equivalent!):
sudo vim /etc/php5/apache2/php.ini
  • Go to the line #462 (or thereabouts), and replace "magic_quotes_gpc = On" by:
magic_quotes_gpc = Off

STEP 3: INSTALL APACHE HTTP SERVER

Apache 2 is the Web server that provides the interface for external browsers to access Web pages for your structWSF and OSF-Drupal installation.

Install Apache

By default, Apache 2 is installed in Ubuntu Server. However, if it is not, you have to cut and paste the command below in Terminal:

sudo apt-get install apache2

When the installation is complete, check if Apache is working properly by running this command:

sudo curl http://localhost

If you see some HTML text and read the text “It works!”, it means Apache is working correctly, and you can proceed to the next step.

If you need it, a good reference manual for Apache setup can be found at this Web site:

Enable Clean URLs

The default “unclean” URLs that Drupal provides with question marks is annoying and interferes with search engines. To fix this problem, you should enable the mod-rewrite module in Apache 2.

First, check whether the rewrite module for your Apache is enabled:

sudo ls /etc/apache2/mods-enabled/

If you see rewrite.load in the list, skip the next steps and go directly to Step 4.

If you don’t find rewrite.load, it means that the rewrite module is not enabled. Drupal’s clean URLs feature requires this module to be enabled.

Paste this command into Terminal:

sudo a2enmod

The command returns a lot of text providing a list of options available to enable, and ends with the question: Which module would you like to enable?

At the blinking cursor in Terminal, type in:

rewrite

Terminal will confirm rewrite installed and tell you to restart Apache. But there's more to do first.

Check again to confirm that rewrite is enabled. Copy the command below into Terminal:

sudo ls /etc/apache2/mods-enabled/

This time you should see that the rewrite module (rewrite.load) is in the list.

You should then restart Apache:

sudo /etc/init.d/apache2 restart

Apache should now be installed and prepared for the software that will be served by it, including Drupal.


STEP 4: INSTALL AND PREPARE MySQL & phpMyAdmin

MySQL provides the database support for the Drupal portion of OSF-Drupal, and phpMyAdmin provides a user interface for managing MySQL.

Install MySQL

Copy the following command into Terminal:

sudo apt-get install mysql-server

You will be asked to provide a password for user: root. Note the password for future reference.

To configure MySQL, enter this command in Terminal to open /etc/php5/apache2/php.ini in your text editor:

sudo vim /etc/php5/apache2/php.ini

When php.ini opens, search for a line in php.ini that looks like:

 ; extension=msql.so

Note: that line does misspell "mysql" as "msql".

Uncomment the line by removing the ; and fix the spelling so that the line reads:

extension=mysql.so

Fnd the line (we're still in /etc/php5/apache2/php.ini):

memory_limit = 16M ; Maximum amount of...

And change 16M to 32M to increase memory limit to 32 megabytes:

memory_limit = 32M ;

Then, save and close the file.

You should then restart Apache:

sudo /etc/init.d/apache2 restart

Install phpMyAdmin

phpMyAdmin is a graphical user interface manager for MySQL. It is used to create and manage your MySQL databases.

To install it, copy the following command into Terminal:

sudo apt-get install phpmyadmin

You will be asked several questions:

  • The usual install and password questions should be answered as you have previously.
  • You will be asked a question about which server to use:
    • The red marker should be on the first choice (apache2) ... leave it there and
    • Use Tab to move cursor to “ok” and press enter.
    • It is all right that the red marker moves away from apache2 in the process.
  • You will be asked whether to use dbconfig-common; use tab to move cursor to yes and hit enter
  • Lastly, phpMyAdmin needs an administrive account password – you may want to use the same password as your MySQL password.

Check phpMyAdmin Installation

Open http://mysite_address.com/phpmyadmin in a Web browser.

  • If you get the phpMyAdmin welcome page, PHP and MySQL are installed correctly.
  • If you see error message “Cookies must be enabled past this point.”, reload the browser (by using the refresh button on the browser)
  • If the error persists, check your work.

If you get any error after installing phpMyAdmin, you can always refers to the phpMyAdmin Ubuntu manual to make sure it is properly set up.

Create Database and Test

Create a database that you will use later in this process for Drupal.

  • Login using your MySQL user name (root) and password that you have set when installing MySQL server.
  • You will be taken to a Web page with three columns. In the center column, the middle block has a textfield with the label "Create a Database".
  • Type in your database name. In this example, I would use something like drupal.
  • Click create and you are done.
  • Note the name you have given the new database. Your username is "root" if you used the default settings during installation, and the password is the password you used to enter phpMyAdmin. Note these as you will need them later in the installation.
  • Close the browser.

STEP 5: INSTALL AND TEST VIRTUOSO SERVER

The Virtuoso datastore is the host for the triple-store database and it indexes the RDF information used by structWSF. It also provides inferencing capabilities over that information.

Although you won't need the Virtuoso install manual if you are doing a default install, as described in these instructions, it can be helpful if you need to make configuration modifications for your installation. The manual can be found at:

Download Virtuoso

The first step is to go to the temporary folder where we will download and extract all Virtuoso files:

cd /tmp

Then we download Virtuoso 6.1.6:

sudo wget http://downloads.sourceforge.net/project/virtuoso/virtuoso/6.1.6/virtuoso-opensource-6.1.6.tar.gz

Extract and Install Virtuoso

Using the Terminal, extract compressed files in the current directory (/tmp/ ):

sudo tar -xzvf virtuoso-opensource-6.1.6.tar.gz

Configure Initial Virtuoso

Move Terminal to extracted virtuoso folder:

cd virtuoso-opensource-6.1.6

Copy, paste and run each of the following lines one at a time in Terminal:

CFLAGS="-O2"
export CFLAGS
sudo ./configure --program-transform-name="s/isql/isql-v/" --enable-openssl=/usr --enable-openldap=/usr --disable-hslookup --enable-wbxml2=/usr --enable-imagemagick=/usr --enable-bpel-vad --with-iodbc=/usr --with-layout=debian --with-xml-prefix=/usr --with-xml-exec-prefix=/usr --without-internal-zlib --with-readline=/usr --disable-maintainer-mode

When it completes, Terminal will give you a message that looks like:

Virtuoso Open Source Edition 6.1.6configuration summary
============================================
Installation variables
layout default
prefix /usr/local/virtuoso-opensource
exec_prefix ${prefix}
Installation paths
programs ${exec_prefix}/bin
include files ${prefix}/include
libraries ${exec_prefix}/lib
manual pages ${datarootdir}/man
vad packages ${datarootdir}/virtuoso/vad
database ${prefix}/var/lib/virtuoso/db
hosting ${exec_prefix}/lib/virtuoso/hosting
Options
BUILD_OPTS xml ssl ldap imsg pldebug pthreads

Next, compile the Installation file (this will take about 30 min to 1 hour):

sudo make

Check the compiled program (this will take over an hour, but it can run unattended – it will abort on an error). If it completes successfully it will not report errors. It also appears to stop for long periods of time as it processes..., don't abort hastily... it is likely working away!:

sudo make check

You will get a report when it is done. If you get errors, you will need to review the log files to find the error. If you do, check out Tech Support for Virtuoso, at Open Link Software may be able to help.

If the make check reports no errors, proceed to install the program. This one only takes about a minute or so to execute. Copy paste and run the following command in Terminal:

sudo make install

When it completes successfully, you will get a report that ends like this :

make[3]: Nothing to be done for `install-exec-am'.
make[3]: Nothing to be done for `install-data-am'.
make[3]: Leaving directory `virtuoso-opensource-6.1.6/appsrc'
make[2]: Leaving directory `virtuoso-opensource-6.1.6/appsrc'
make[1]: Leaving directory `virtuoso-opensource-6.1.6/appsrc'

Set Up Virtuoso ODBC Connectors

Create the file /etc/odbc.ini by using the following command in Terminal to open a new file called /etc/odbc.ini with your text editor:

sudo vim /etc/odbc.ini

Copy and paste the text shown below into the open file /etc/odbc.ini:

[ODBC Data Sources]
structwsf-triples-store = OpenLink Virtuoso

[structwsf-triples-store]
Driver = OpenLink Virtuoso
Address = localhost:1111

Then, save and close file

Next, create the file /etc/odbcinst.ini by using the following command in Terminal to open a new file called /etc/odbcinst.ini:

sudo vim /etc/odbcinst.ini

Paste text shown below into /etc/odbcinst.ini:

[ODBC Drivers]
OpenLink Virtuoso = Installed
OpenLink Virtuoso (Unicode) = Installed

[OpenLink Virtuoso]
Driver = /usr/local/virtuoso-opensource/lib/virtodbc_r.so

[OpenLink Virtuoso (Unicode)]
Driver = /usr/local/virtuoso-opensource/lib/virtodbcu_r.so

Save and close the file.

Now, confirm that virtuoso.ini is where it should be by issuing the following command in Terminal:

sudo ls /usr/local/virtuoso-opensource/var/lib/virtuoso/db/

virtuoso.ini” should be listed in Terminal's response.

Start Virtuoso Server

The lines of text below form a single command. Copy, paste and run the command in Terminal:

sudo /usr/local/virtuoso-opensource/bin/virtuoso-t -c /usr/local/virtuoso-opensource/var/lib/virtuoso/db/virtuoso.ini -f

After 30 seconds or so, Terminal will show the server is online:

07:43:08 HTTP/WebDAV server online at 8890
07:43:08 Server online at 1111 (pid 8896)

Leave the terminal open for the next installation tests.

Note: next time you run Virtuoso, you can remove the "-f" flag so that it runs in background (so that you don't have to leave a terminal open)

Test ODBC Connection

Open a second instance of Terminal while keeping the previous terminal open (to keep iODBC server running), and then paste the command shown below into the second Terminal. The other terminal must stay open to make this iODBC test work:

sudo /usr/bin/iodbctest "DSN=structwsf-triples-store;UID=dba;PWD=dba"

If it is working correctly, it will return:

iODBC Demonstration program
This program shows an interactive SQL processor
Driver Manager: 03.52.0607.1008
Driver: 05.11.3039 OpenLink Virtuoso ODBC Driver (virtodbc.so)
SQL>

Close both instances of Terminal.

If you don't have access to iodbc (you are on a non-Ubuntu server which doesn't have an installation package for iodbc), you can always use unixODBC's isql tool to test the connection.

sudo isql -v structwsf-triples-store dba dba

If it is working correctly, it will return something like:


+---------------------------------------+
| Connected!                            |
|                                       |
| sql-statement                         |
| help [tablename]                      |
| quit                                  |
|                                       |
+---------------------------------------+

Open Virtuoso Conductor

Virtuoso Conductor is the administrative control interface for Virtuoso services. It primarily allows users to administer the server while giving access to many of the features that Virtuoso has to offer providing many conceptual demonstrations and introductions. For more information on Virtuoso A How-to guide, which also has a quick-start guide, is provided by the software's creators, OpenLink Software. It can be found at:

Point your Web browser to the link shown below:

If Virtuoso is working correctly, it will open Virtuoso Conductor.

Log in. the default login is:

Account: dba Password: dba

Take some time to wander around the facilities provided by Virtuoso Conductor. You will find many capabilities built into the software - check out the OpenLink Software how to manual at the Web site cited above.

To get back to our installation, click on the "Interactive SQL (ISQL)" link at the top of the left sidebar.

Then copy, paste and run this SQL query in the iSQL window of your browser, open on Virtuoso Conductor (NOT in Terminal!):

create procedure exst (in st varchar)
{
declare h, dta, mdta any;
set isolation='committed';

exec (st, null, null, vector (), 0, mdta, null, h);
exec_result_names (mdta[0]);

while (0 = exec_next (h, null, null, dta))
{
exec_result (dta);
}

exec_close (h);
};

Interactive SQL will report:

The statement execution did not return a result set.

Which is normal, but tells you the installation is recognized and running properly.

And then copy, paste and run this other SQL query in the iSQL window of your browser, open on Virtuoso Conductor. This will commit ("save") the procedure in Virtuoso:

exec('checkpoint');

Interactive SQL will report:

The statement execution did not return a result set.

Virtuoso Support

The Virtuoso support mailing list is located at:

also see:

Create Startup Script

The next step is to create a startup script for Solr. From this script, you will be able to easily start, stop and restart the Solr server. First, let's create a new file for this script:

sudo vim /etc/init.d/virtuoso

Then, copy and paste this code in that new file:


#! /bin/sh
#
# virtuoso	OpenLink Virtuoso Open-Source Edition
#
#		Written by OpenLink Virtuoso Maintainer 
#		<vos.admin@openlinksw.com>
#
# Version:	@(#)virtuoso  5.0.9-rc6  10-Oct-2008	vos.admin@openlinksw.com
#

### BEGIN INIT INFO
# Provides:		virtuoso
# Required-Start: 	$syslog
# Required-Stop: 	$syslog
# Default-Start:	2 3 4 5
# Default-Stop: 	0 1 6
# Short-Description:	Start Virtuoso database server on startup
# Description:		Start and stop the primary instance of Virtuoso running
# 	in /var/lib/virtuoso/db/. The first time this runs, it loads the
# 	Conductor administrative package.
###


PATH=/sbin:/bin:/usr/sbin:/usr/bin
DAEMON=/usr/local/virtuoso-opensource/bin/virtuoso-t
NAME=virtuoso
DESC="OpenLink Virtuoso Open-Source Edition"
DBBASE=/usr/local/virtuoso-opensource/var/lib/virtuoso/db  

test -x $DAEMON || exit 0

LOGDIR=/var/log/virtuoso-opensource
PIDFILE=$DBBASE/$NAME.lck
DODTIME=1                   # Time to wait for the server to die, in seconds
                            # If this value is set too low you might not
                            # let some servers to die gracefully and
                            # 'restart' will not work

# Include virtuoso-opensource defaults if available
if [ -f /etc/default/virtuoso-opensource ] ; then
	. /etc/default/virtuoso-opensource
fi

set -e

running_pid()
{
    # Check if a given process pid's cmdline matches a given name
    pid=$1
    name=$2
    [ -z "$pid" ] && return 1
    [ ! -d /proc/$pid ] &&  return 1
    cmd=`cat /proc/$pid/cmdline | tr "\000" "\n"|head -n 1 |cut -d : -f 1`
    # Is this the expected child?
    [ "$cmd" != "$name" ] &&  return 1
    return 0
}

running()
{
# Check if the process is running looking at /proc
# (works for all users)

    # No pidfile, probably no daemon present
    [ ! -f "$PIDFILE" ] && return 1
    # Obtain the pid and check it against the binary name
    . $PIDFILE
    pid="$VIRT_PID"
    running_pid $pid $DAEMON || return 1
    return 0
}

force_stop() {
# Forcefully kill the process
    [ ! -f "$PIDFILE" ] && return
    if running ; then
        kill -15 $pid
        # Is it really dead?
        [ -n "$DODTIME" ] && sleep "$DODTIME"s
        if running ; then
            kill -9 $pid
            [ -n "$DODTIME" ] && sleep "$DODTIME"s
            if running ; then
                echo "Cannot kill $LABEL (pid=$pid)!"
                exit 1
            fi
        fi
    fi
    rm -f $PIDFILE
    return 0
}

case "$1" in
  start)
	echo -n "Starting $DESC: "
	cd "$DBBASE" || exit -1
	$DAEMON -c $NAME +wait
        if running ; then
            echo "$NAME."
        else
            echo " ERROR."
        fi
	;;
  stop)
	echo -n "Stopping $DESC: "
	cd "$DBBASE" || exit -1
	. ./virtuoso.lck
	if running ; then
	    kill $VIRT_PID
	fi
	echo "$NAME."
	;;
  force-stop)
	echo -n "Forcefully stopping $DESC: "
        force_stop
        if ! running ; then
            echo "$NAME."
        else
            echo " ERROR."
        fi
	;;
  #reload)
	#
	#	If the daemon can reload its config files on the fly
	#	for example by sending it SIGHUP, do it here.
	#
	#	If the daemon responds to changes in its config file
	#	directly anyway, make this a do-nothing entry.
	#
	# echo "Reloading $DESC configuration files."
	# start-stop-daemon --stop --signal 1 --quiet --pidfile \
	#	/var/run/$NAME.pid --exec $DAEMON
  #;;
  force-reload)
	#
	#	If the "reload" option is implemented, move the "force-reload"
	#	option to the "reload" entry above. If not, "force-reload" is
	#	just the same as "restart" except that it does nothing if the
	#   daemon isn't already running.
	# check wether $DAEMON is running. If so, restart
	start-stop-daemon --stop --test --quiet --pidfile \
		/var/run/$NAME.pid --exec $DAEMON \
	&& $0 restart \
	|| exit 0
	;;
  status)
    echo -n "$LABEL is "
    if running ;  then
        echo "running"
    else
        echo " not running."
        exit 1
    fi
    ;;
  *)
	N=/etc/init.d/$NAME
	# echo "Usage: $N {start|stop|restart|reload|force-reload}" >&2
	echo "Usage: $N {start|stop|restart|force-reload|status|force-stop}" >&2
	exit 1
	;;
esac

exit 0



Note: by default, Virtuoso is installed in the folder "/usr/local/virtuoso-opensource/", if you specified another location where to install virtuoso, you have to modify that path in the script above for these two variables: DAEMON and DBBASE.

Then, save and close the file, and let's change its permission so that we can run it:

sudo chmod 744 /etc/init.d/virtuoso

Now, let's test this new startup file:

sudo /etc/init.d/virtuoso stop

sudo /etc/init.d/virtuoso start

Make sure that Virtuoso is properly running by running this command:

ps -elf | grep virtuoso

If Virtuoso is running, you should see this returned by the previous command:

1 S root 11007 1 0 80 0 - 219870 futex_ Jan19 ? 03:50:23 /usr/local/virtuoso-opensource/bin/virtuoso-t -c virtuoso +wait
0 R root 25507 25484 0 80 0 - 764 - 21:56 pts/0 00:00:00 grep virtuoso

Note: if nothing appears, it is because the startup script is not properly running. Please check to make sure your paths are properly set.

Optionally, you can change the system so that Virtuoso starts and stops automatically at server boot and shutdown time:

sudo update-rc.d virtuoso defaults

STEP 6: INSTALL AND TEST APACHE SOLR

Solr provides the full-text and faceted search capabilities used by structWSF. We will install Solr to its default location, and we will use Jetty to run the Solr server.

Download

First, download Solr 1.4 from one of these sources http://www.apache.org/dyn/closer.cgi/lucene/solr/:

sudo mkdir /usr/share/apachesolr/
cd /usr/share/apachesolr/
sudo wget http://apache.mirror.iweb.ca/lucene/solr/1.4.0/apache-solr-1.4.0.tgz

Install and Configure

Install Solr on the server:

sudo tar -xvf apache-solr-1.4.0.tgz
cd apache-solr-1.4.0
sudo mv * ../

Confirm and Test for Use

To confirm that Solr-Jetty is working correctly, enter the following command into Terminal so that it will start the server application:

cd /usr/share/apachesolr/example/
sudo java -Xms64M -Xmx512M -jar start.jar

It should return the following in Terminal:

...
Jan 14, 2010 6:55:50 PM org.apache.solr.servlet.SolrUpdateServlet init
INFO: SolrUpdateServlet.init() done
2010-01-14 18:55:50.163::INFO: Started SocketConnector @ 0.0.0.0:8983

Change the "schema.xml" file to the one needed for structWSF:

  • Download the new schema.xml file from (double click on this text to point your Web browser to the download site:
  • Copy & paste the content of that file into the Solr instance using Terminal:
sudo vim /usr/share/apachesolr/example/solr/conf/schema.xml

Test the installation by pointing a Web browser to the Solr test page:

http://mysite_address.com:8983/solr/admin/

You will see a Solr welcome page if it is installed correctly.

Create Startup Script

The next step is to create a startup script for Solr. From this script, you will be able to easily start, stop and restart the Solr server. First, let's create a new file for this script:

sudo vim /etc/init.d/solr

Then, copy and paste this code in that new file:

#!/bin/bash
# description: Starts and stops Solr production
set -e
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
SOLR_DIR=/usr/share/apachesolr/example/
#JAVA_OPTIONS="-Dsolr.solr.home=./solr -Djava.util.logging.config.file=logging.properties -server -DSTOP.PORT=8079 -DSTOP.KEY=stopkey -Xmx512M -Xms64M -jar start.jar"
JAVA_OPTIONS="-Dsolr.solr.home=./solr -server -DSTOP.PORT=8079 -DSTOP.KEY=stopkey -Xmx512M -Xms64M -jar start.jar"

JAVA="/usr/bin/java"
LOG_FILE="/var/log/solr/console.log"
case $1 in
start)
echo "Starting Solr"
cd $SOLR_DIR
#su - solr -c "cd $SOLR_DIR && nohup $JAVA $JAVA_OPTIONS 2> $LOG_FILE &"	
#TEST="cd $SOLR_DIR && nohup $JAVA $JAVA_OPTIONS 2> $LOG_FILE &"
cd $SOLR_DIR

EXEC="$JAVA $JAVA_OPTIONS"
nohup $EXEC &

echo "ok - remember it may take a minute or two before Solr responds on requests"
exit
;;
stop)
echo "Stopping Solr"
cd $SOLR_DIR
$JAVA $JAVA_OPTIONS --stop	
    echo "ok"
;;
restart)
$0 stop
sleep 3
$0 start	
;;
*)
echo "Usage: $0 {start|stop|restart}" >&2exit 1
;;
esac

Then, save and close the file, and let's change its permission so that we can run it:

sudo chmod 744 /etc/init.d/solr

Now, let's test this new startup file:

sudo /etc/init.d/solr restart

Optionally, you can change the system so that Solr starts and stops automatically at server boot and shutdown time:

sudo update-rc.d solr defaults

STEP 7: INSTALL the OWLAPI

The OWLAPI is the library used to manage everything related to ontologies in a structWSF instance. The OWLAPI is a Java library, and is hosted in a Tomcat6 server that is used as a servlet container. structWSF will communicate with the OWLAPI by using the PHP/Java bridge software that makes the link between the Java OWLAPI and the PHP structWSF endpoints.

Install Tomcat6

The first step is to install the Tomcat6 server.

sudo apt-get install tomcat6

Install OWLAPI

The OWLAPI is bundled into a WAR file with the PHP/Java bridge. A WAR (Web Archive) file is a tomcat deployment file that is used as an installation file.

Download the OWLAPI.war file. If you download the file directly into the webapps folder, make sure to stop Tomcat so that it doesn't start to process the file in the middle of the download:

sudo /etc/init.d/tomcat6 stop

Then go to tomcat's webapp folder:

cd /var/lib/tomcat6/webapps/

Upload the OWLAPI.war file into that folder.

If you previously stopped Tomcat6, or if it was not started, now start it:

sudo /etc/init.d/tomcat6 start

Now that Tomcat6 is running, it will automatically install what is in the OWLAPI.war file. It may take a few seconds to a minute, so wait until the OWLAPI folder gets created into the that folder:

ls

You should eventually see appearing a "OWLAPI" folder. It means that the OWLAPI is installed, along with the PHP/Java bridge.

Once these installation steps are done, the new tomcat6 instance that hosts the OWLAPI will be accessible at that address: http://localhost:8080/OWLAPI/java/Java.inc

To test the installation, you should run this command in the console:

curl http://localhost:8080/OWLAPI/java/Java.inc

If you see some PHP code appearing in the console, it means that the tomcat6 server is properly running and that the OWLAPI webapp is properly installed, loaded and running.

Configure Tomcat6's Policy Files

Properly setup the 50local.policy file on your server.

Edit the file using:

vim /etc/tomcat6/policy.d/50local.policy

The more liberal permissions would be to add that line to that file. You can tweak the permission policies as needed for your project. The most permissive code to add to the end of this file is:

grant codeBase "file:/var/lib/tomcat6/webapps/OWLAPI/WEB-INF/-" { permission java.security.AllPermission; };

Configuring PHP

Note 1: If your PHP library is running SUHOSIN, then you will have to properly configure it, or to simply disable it. Otherwise, your PHP scripts that tries to use the PHP/Java bridge will terminate their execution without sending any kind of errors or exceptions.
Note 2: If you are experiencing issues with PHP/Java Bridge, reports you to the first section of the FAQ in order to debug what could be the problem.

The next step relates to the OWLAPI is to properly configure PHP such that it can load the PHP/Java Bridge by communicating with the Tomcat6 server.

Edit the php.ini file:

sudo vim /etc/php5/apache2/php.ini

Go to the line #894 (or thereabouts), and replace "allow_url_include = Off" by:

allow_url_include = On

This will enable the communication between the two systems.

Add Default Class and Properties Hierarchies Files

The next step is to add the default classHierarchySerialized.srz and propertyHierarchySerialized.srz files to your structWSF setup.

You have to download these files into your ontologies structure folder. Check the ontological_structure_folder setting of your data.ini configuration file to know the location where to upload this file.

Add Default Template

The last step is to create a "new.owl" file into your ontologies files folder. Check the ontologies_files_folder setting of your data.ini configuration file to know the location where to upload this file.

You can download the new.owl here.

This is the file used to create an empty, new, ontology via structOntology. If this file is not existing, structOntology will throw an error.

STEP 8: INSTALL structWSF

structWSF is the platform-independent Web services framework that drives all of the user interface capabilities within OSF-Drupal. It is the pivotal middleware of the entire system.

Prepare and Download

Set Folder Permissions

  • Make sure that the Web server instance has read and write access to the "/tmp/" folder of your system. (default 777 will work).
  • If you want your Web server to have access to another temporary folder, then change the line 22 of the file '../structwsf/index.php' to point to that folder and make sure the folder has Permissions set to 777.

Download StructWSF

Click on the link below to point your Web browser to the download site:

Choose the file which has the most recent date and download to your server:

sudo mkdir /usr/share/structwsf/
cd /usr/share/structwsf/
sudo wget http://structwsf.googlecode.com/files/structwsf-1.0a71.zip

Install structWSF

In Terminal, extract the structWSF package in the current directory:

sudo unzip structwsf-1.0a71.zip

Move all files into the proper folder:

cd structwsf-v1.0a7
sudo mv * ../

Setup Access

We now want to make access to the structWSF instance via the URL http://mysite_address.com/ws/. We have to add one Apache configuration file to enable this access.

sudo vim /etc/apache2/sites-available/structwsf
Alias /ws /usr/share/structwsf

<Directory /usr/share/structwsf/>
Options +FollowSymLinks
AllowOverride All
order allow,deny
allow from all
</Directory>

Now we enable this new access:

sudo ln -s /etc/apache2/sites-available/structwsf /etc/apache2/sites-enabled/structwsf

Finally we restart Apache:

sudo /etc/init.d/apache2 restart

Add and Configure Database

First, make a backup of WebService.php by pasting this text into Terminal:

cp /usr/share/structwsf/framework/WebService.php /usr/share/structwsf/framework/WebService.php.bak


Make sure that the folder specificed here is the one in which you can find the data.ini and network.ini files:

sudo vim /usr/share/structwsf/framework/WebService.php

Check lines 32 and 35 (or thereabouts) for:

public static $data_ini = "/usr/share/structwsf/";
public static $network_ini = "/usr/share/structwsf/";

Now let's configure the access to the structWSF instance in the data.ini file:

sudo vim /usr/share/structwsf/data.ini

Change the "datasets" section of the file to specify the address used to access the structWSF instance:

[datasets]

;The base URI of the graph where the structWSF structure description get indexed
wsf_graph = "http://mysite_address.com/wsf/";

;DTD base URL where to resolve DTD used to share data
dtd_base = "http://mysite_address.com/ws/dtd/" 

You also have to configure the [triplestore] and the [solr] sections of the data.ini file to properly configure the structWSF access to the Virtuoso and Solr server instances:

[triplestore]

; Username used to connect to the triple store instance
username = "dba"

; Password used to connect to the triple store instance
password = "dba"

; DSN used to connect to the triple store instance
dsn = "structwsf-triples-store"

; Host used to connect to the triple store instance
host = "localhost"

; Name of the logging table on the Virtuoso instance
log_table = "SD.WSF.ws_queries_log"

; Port number where the triple store server is reachable
port = "8890"

[solr]

; The core to use for Solr;  Use "" (double, double-quotes) when the "multicore"
; mode is not used
wsf_solr_core = ""

; Host used to connect to the solr instance
host = "localhost"

; Auto commit handled by the Solr data management systems. If this parameter is true, 
; then this means Solr will handle the commit operation by itself. If it is false, then the 
; web services will trigger the commit operations. Usually, Auto-commit should be handled 
; by Solr when the size of the dataset is too big, otherwise operation such as delete could 
; take much time.			
solr_auto_commit = "FALSE"

; Port number where the Solr store server is reachable
port = "8983"

; This is the folder there the file of the index where all the fields defined in Solr
; are indexed. You have to make sure that the web server has write access to this folder.
; This folder path has to end with a slash "/".
fields_index_folder = "/tmp/"

Now let's configure the access to the structWSF instance in the network.ini file:

sudo vim /usr/share/structwsf/network.ini
[network]

; Base URL used to access the structWSF instance
; Note: *WITHOUT* ending slash
wsf_base_url = "http://mysite_address.com"    

; Local server path of the structWSF instance
wsf_base_path = "/usr/share/structwsf/"

; Local server IP address of the structWSF instance
wsf_local_ip = "127.0.0.1"

[tracking]

; Enable the tracking of records changes from the Crud Create web service endpoint
; If the record was not existing in the target dataset before the Crud Create
; call, then there won't be any ChangeState record created.
track_create = "false"

; Enable the tracking of records changes from the Crud Update web service endpoint
track_update = "false"

; Enable the tracking of records changes from the Crud Delete web service endpoint
track_delete = "false"


; Specifies a specific WSF tracking web service endpoint URL to access the
; tracking endpoint. This is useful to put all the record changes tracking
; on a different, dedicated purposes, WSF server. If this parameter is
; commented, we will use the wsf_base_url to access the tracking endpoints.
; If it is uncommented, then we will use the endpoint specified by this
; parameter.
; Note: *WITH* ending slash
; tracking_endpoint = "http://new-tracking-wsf-server/ws/tracker/"

[owlapi]

; Number of sessions (threads) to use in parallel
nb_sessions = "1"

; URL where the Java Bridge can be accessed from this server
bridge_uri = "http://localhost:8080/OWLAPI/java/Java.inc"

[geo]

; Specifies if this instance is geo-enabled. To have a geo-enabled instance
; you have to make sure that you have Solr-Locale installed on your instance.
geoenabled = "true"
	

Setup and Configure Server

Check For The SID (Server ID)

Lets make sure that the unique server ID is defined for your structWSF instance.

Put that URL into your web browser:

http://mysite_address.com/ws/

You should see a MD5 checksum that looks like: 5c0d183ed006bd1a041c0dd8696cdb0d

If you see an empty white page, this probably means that your web server doesn't have the permission to write any file into your structwsf folder.

If the user and group under which your apache web service is running is apache:apache, then you have to make sure that this user has write rights on that folder:

chown apache:apache structwsf
chmod 755 structwsf

Configure Logger

To configure the Logger, open Virtuoso in a Web browser by clicking on this link, which will open Virtuoso Conductor:

Log in. The default login is:

Account: dba Password: dba

Click on the "Interactive SQL (ISQL)" link at the top of the left sidebar. Then copy, paste and run this SQL query in the iSQL window:

create table "SD"."WSF"."ws_queries_log"
(
"id" INTEGER IDENTITY,
"requested_Web_service" VARCHAR,
"requester_ip" VARCHAR,
"request_parameters" VARCHAR,
"requested_mime" VARCHAR,
"request_datetime" DATETIME,
"request_processing_time" DECIMAL,
"request_http_response_status" VARCHAR,
"requester_user_agent" VARCHAR,
PRIMARY KEY ("id")
);
create index sd_wsf_requested_Web_service_index on SD.WSF.ws_queries_log (requested_Web_service);
create index sd_wsf_requester_ip_index on SD.WSF.ws_queries_log (requester_ip);
create index sd_wsf_requested_mime_index on SD.WSF.ws_queries_log (requested_mime);
create index sd_wsf_request_datetime_index on SD.WSF.ws_queries_log (request_datetime);
create index sd_wsf_request_http_response_status_index on SD.WSF.ws_queries_log (request_http_response_status);
create index sd_wsf_requester_user_agent_index on SD.WSF.ws_queries_log (requester_user_agent);

Interactive SQL will report:

The statement execution did not return a result set.
The statement execution did not return a result set.
The statement execution did not return a result set.
The statement execution did not return a result set.
The statement execution did not return a result set.
The statement execution did not return a result set.
The statement execution did not return a result set.

STEP 9: INSTALL ARC2

The ARC2 php-rdf library is needed by the structWSF 'create' Web services for some offline RDF processing activities.

Download

Download and extract the ARC2 libraries from:

And choose the latest release (its a tar.gz file) and download it.

Or can use the following command lines instructions:

cd /usr/share/structwsf/framework
sudo wget http://code.semsol.org/source/arc.tar.gz

Install

To install ARC2, we have to untar the package in the "framework" folder, and rename it to "arc2":

sudo tar -xvf arc.tar.gz
sudo mv arc arc2

STEP 10: INITIATE THE WEB SERVICES FRAMEWORK

Once installated, you are now ready to create the WSF framework, its internal structure and to initiate the WSF system.

First, using a Web browser, enter the link below to run a setup program with the parameters specified in the URL (of course, change mysite_address.com to your Web site's name):

http://mysite_address.com/ws/auth/wsf_indexer.php?action=create_wsf&server_address=http://mysite_address.com

This command creates a full access user.

Next, specify that user's IP and site name. As the local user, enter the link below in your Web browser (change mysite_address.com to your Web site's name). It will run a setup program with the parameters specified in the URL:

http://mysite_address.com/ws/auth/wsf_indexer.php?action=create_user_full_access&user_address=127.0.0.1&server_address=http://mysite_address.com

To enable remote access for a full user, you need to issue a similar command, but with different parameters. For example, change the ip address shown to the IP address you wish to grant access and change mysite_address.com to your Web site's name. It will run a setup program with the parameters specified in the URL:

http://mysite_address.com/ws/auth/wsf_indexer.php?action=create_user_full_access&user_address=24.200.138.116&server_address=http://mysite_address.com

Finally, you will have to make the dataset registry World readable. This is to ensure that everybody can at least read the names of the datasets. However, if you have a particular usecase, you may manage the permissions to that dataset differently.

http://mysite_address.com/ws/auth/wsf_indexer.php?action=create_world_readable_dataset_read&server_address=http://mysite_address.com


Now, create a new dataset using Terminal (Note: do not use your Web browser!). To do so, copy and paste the following lines into Terminal. Make sure you change mysite_address.com before you run the command:

curl -H "Accept: text/xml" "http://mysite_address.com/ws/dataset/create/" -d "uri=http://mysite_address.com/test/&title=Test&description=test&creator=http://mysite_address.com/drupal/user/1/" -v


Make sure that Virtuoso commit this newly created structWSF network. Copy, paste and run this SQL query in the iSQL window of your browser, open on Virtuoso Conductor:

exec('checkpoint');
Warning: now, you have to delete/move/rename the wsf_indexer.php script so that nobody else can perform these actions. Eventually this script will be replaced by something more secure to setup an instance.

Confirm Set-up

To confirm that the dataset was correctly created, copy and paste the following code into a Web brower. Remember to change mysite_address.com to the correct domain.

http://mysite_address.com:8890/sparql/?default-graph-uri=&query=select+*+from+%3Chttp%3A%2F%2Fmysite_address.com%2Fwsf%2Fdatasets%2F%3E+where+{%3Fs+%3Fp+%3Fo}&format=text%2Fhtml&debug=on

If you see a table with three columns ("s" "p" "o") with the title and the description of the dataset, it means that the steps above worked and it confirms that everything has been properly setuped so far.

StructWSF Ontological Structure Setup

First, make sure you have "allow_call_time_pass_reference" On in your php.ini file. Until the ontological structure services get updated, this setting has to be defined for the PHP parser.

sudo vim /etc/php5/apache2/php.ini

Then make sure you have this setting enabled:

allow_call_time_pass_reference = "On"

Then make sure that you properly configure the [ontologies] section of the data.ini file. You have to setup two things: the folder path where the ontologies files are located, and the folder path where the ontologies structure files will be saved.

[ontologies]

; Ontologies description files (in RDFS and OWL)
ontologies_files_folder = "/data/ontologies/files/"

; structWSF ontological structure
ontological_structure_folder = "/data/ontologies/structure/"

Note: the web server has to have write writes on the ontological_structure_folder folder.

Now, we have to create a folder where all ontologies used by structWSF will be uploaded:

sudo chmod 777 /data/ontologies/structure/
sudo mkdir -p /data/ontologies/files/

The next step will be to load ontologies into the structWSF. This will be discussed below in the Drupal section since we will be using the structOntology Drupal module to load them into the instance.


STEP 11: INSTALL DRUPAL

Drupal and selected add-in modules provide the user interface, user and group management, and overall content management system (CMS) hosting framework for a OSF-Drupal installation. They are the most visible portions of the system to users.

Besides Drupal itself and the OSF-Drupal modules, other key necessary modules include Organic Groups (OG), the Content Construction Kit (CCK) and Views.

Download & Install

Download the latest versions of the modules from Drupal Download site. You should select the Recommended Releases for Drupal 6 (usually the top-most green block in the Official releases section.

Download the latest modules from Drupal to the server from each of the URLs below, one at a time:

http://drupal.org/project/drupal
http://drupal.org/project/construct
http://drupal.org/project/og
http://drupal.org/project/og_user_roles
http://drupal.org/project/cck
http://drupal.org/project/views

First we have to download and install the Drupal package:

sudo mkdir /var/www/drupal
cd /var/www/drupal
sudo wget http://ftp.drupal.org/files/projects/drupal-6.15.tar.gz
sudo tar -xvf drupal-6.15.tar.gz
cd drupal-6.15
sudo mv * ../

Now let's fix the default Apache site folder:

sudo vim /etc/apache2/sites-available/default

Change the file such as:

<VirtualHost *:80>
        ServerAdmin webmaster@localhost

        DocumentRoot /var/www/drupal
        <Directory />
          Options FollowSymLinks
          AllowOverride None
        </Directory>
        <Directory /var/www/drupal/>
          Options Indexes FollowSymLinks MultiViews
          AllowOverride All
          Order allow,deny
          allow from all
        </Directory>         
        
        
        ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
        <Directory "/usr/lib/cgi-bin">
                AllowOverride None
                Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
                Order allow,deny
                Allow from all
        </Directory>

        ErrorLog /var/log/apache2/error.log

        # Possible values include: debug, info, notice, warn, error, crit,
        # alert, emerg.
        LogLevel warn

        CustomLog /var/log/apache2/access.log combined

    Alias /doc/ "/usr/share/doc/"
    <Directory "/usr/share/doc/">
        Options Indexes MultiViews FollowSymLinks
        AllowOverride None
        Order deny,allow
        Deny from all
        Allow from 127.0.0.0/255.0.0.0 ::1/128
    </Directory>

</VirtualHost>

Note: you have to change three things in this file: DocumentRoot, Directory and AllowOverride.

Then the next step is to create a ".htaccess" file for Drupal. First, let's open the .htaccess file in your Terminal with this command:

sudo vim /var/www/drupal/.htaccess

Then, copy and paste the content of this file in the Vim (or other editor) window, save and close the file:

Finally, save the .htaccess file and restart the Apache server:

sudo /etc/init.d/apache2 restart

Now let's download and install all needed modules by OSF-Drupal:

sudo mkdir /var/www/drupal/sites/all/modules
cd /var/www/drupal/sites/all/modules
sudo wget http://ftp.drupal.org/files/projects/og-6.x-2.0.tar.gz

sudo wget http://ftp.drupal.org/files/projects/og_user_roles-6.x-4.0.tar.gz

sudo wget http://ftp.drupal.org/files/projects/cck-6.x-2.6.tar.gz

sudo wget http://ftp.drupal.org/files/projects/views-6.x-2.8.tar.gz

sudo wget http://ftp.drupal.org/files/projects/construct-6.x-1.x-dev.tar.gz

sudo tar -xvf og-6.x-2.0.tar.gz

sudo tar -xvf og_user_roles-6.x-4.0.tar.gz

sudo tar -xvf cck-6.x-2.6.tar.gz

sudo tar -xvf views-6.x-2.8.tar.gz

sudo tar -xvf construct-6.x-1.x-dev.tar.gz

If the package "construct-6.x-1.x-dev.tar.gz" as been untar in the folder "/construct" (check for the capital 'S'), then you should rename it to make it consistent with this installation manual to:

sudo mv construct conStruct

Setup

To setup Drupal first make a copy of default.settings.php file as settings.php. Copy both lines of the command and paste into Terminal:

sudo cp /var/www/drupal/sites/default/default.settings.php /var/www/drupal/sites/default/settings.php

Make the settings.php as writable:

sudo chmod a+w /var/www/drupal/sites/default/settings.php

Make the sites/default directory as writable:

sudo chmod a+w /var/www/drupal/sites/default

You then must configure Drupal's settings.php. To begin, open Drupal's /sites/default/settings.php file in a text editor:

sudo vim /var/www/drupal/sites/default/settings.php

Add the following line to the group of ini_set commands:

ini_set("memory_limit","32M");

Copy the classes and properties structure files generated by sturctWSF into OSF-Drupal:

sudo cp /data/ontologies/structure/classHierarchySerialized.srz /var/www/drupal/sites/all/modules/conStruct/framework/ontologies/classHierarchySerialized.srz
sudo cp /data/ontologies/structure/propertyHierarchySerialized.srz /var/www/drupal/sites/all/modules/conStruct/framework/ontologies/propertyHierarchySerialized.srz

Alternatively you can create a symlink:

sudo
ln -s /data/ontologies/structure/ /var/www/drupal/sites/all/modules/conStruct/framework/ontologies


And, then, restart the Apache server to ensure the changes:

sudo /etc/init.d/apache2 restart

Starting Drupal for the First Time

You are now ready to go to http://mysite_address.com/ in a Web browser. You will see the Drupal install page. Click on Install Drupal in English. Enter database information -- our example entries are:

Database Name: (assigned in MySQL installation Step 4) I used "drupal"
username: root
password: (assigned in step 4)

Save the page and the Drupal install proceeds to Configure site. Before we deal with configuration, we'll deal with the warning at the top of the page. Put the Web browser aside without closing it.

In Terminal, remove write permissions to ./sites/default and ./sites/default/settings.php. Copy paste each command one line at a time into Terminal:

sudo chmod a-w /var/www/drupal/sites/default/settings.php
sudo chmod a-w /var/www/drupal/sites/default

Now go back to the Web browser, which should still be on the configure site page.

Reload the configure site page (View-> Reload in Browser). The warning is replaced with a statement of the changes you have made. Enter site name and admin email address:

Site name: the name (which will be visible on Web site's header in the default Drupal theme.
site email : (your real email address)
username: your SiteAdmin name (I used admin)
Email address: SiteAdmin's email (your real email)
password: your SiteAdmin password

You should also enable Clean URLs. (If you don't do it now you can do it later).

To do so, navigate to the administration page for clean URLs (administer-> site configuration -> clean URLs) and enable them.

Leave further Drupal configuration until next steps are completed.

Other Drupal Modules

Other useful modules, such as WYSIWYG or Content Access or Pathauto or many of the other available Drupal modules might also be useful or desirable for your specific installation. However,as these are not essential for OSF-Drupal itself, they are not set out for download in these installation notes.

Please consult the Drupal or other third-party sites for information about these possible additions.


STEP 12: INSTALL SMARTY TEMPLATE ENGINE AND YUI

The Smarty component is used by OSF-Drupal for templated data displays, with the Yahoo! User Interface (YUI) JavaScript package also providing helpful UI support. (Note: this portion is likely due to be deprecated in next versions.)

Smarty Download and Install

To download and extract Smarty, use a Web browser to go to the site below:

Choose the Latest Stable Release and download to your server. Then, extract the folder from the Smarty-x.x.x .tar.gz with the following command (Note: the Smarty version number may be different for your download):

sudo mkdir -p /var/www/drupal/sites/all/modules/conStruct/framework/smarty
cd /var/www/drupal/sites/all/modules/conStruct/framework/smarty
sudo wget http://www.smarty.net/do_download.php?download_file=Smarty-2.6.26.tar.gz

Smarty installation simply requires placing the extracted files into the correct folder in Drupal's file structure. To install Smarty's library files, extract the downloded folder to the Drupal /sites/all/modules/construct/framework folder with the name smarty – don't forget to change the command to reflect the right name for your source file:

sudo tar -xvf Smarty-2.6.26.tar.gz
cd Smarty-2.6.26
sudo mv * ../

Make this directory with the command below:

sudo mkdir /var/www/drupal/sites/all/modules/conStruct/templates/templates_c

Finally, make sure that the web server's user has Write rights on that templates_c folder. If you are operating a default Ubuntu server, you can run this command to make sure that Apache has the proper rights to write in that folder:

chown -R www-data:www-data /var/www/drupal/sites/all/modules/conStruct/templates/templates_c

YUI Download and Install

To download and install YUI in Drupal's file structure, first use a Web browser to go to the site below:

http://developer.yahoo.com/yui/download/

This will begin the download. When download is complete, extract folder from the downloaded file with this command in Terminal:

cd /var/www/drupal/sites/all/modules/conStruct/js/
sudo wget http://developer.yahoo.com/yui/download/

Install YUI by unarchiving the package in the Drupal /sites/all/modules/construct/js folder:

sudo unzip yui_2.8.0r4.zip

STEP 13: CONFIGURE DRUPAL

Configure Modules

OSF-Drupal requires a number of Drupal modules to also be activated. To do so, point a Web browser to your new Drupal Web site (i.e., mysite_address.com) and log in as an administrator.

Navigate to Administer -> Site Building -> Modules.

Enable the following modules:

CCK:

  • Content
  • Content Copy
  • Content Permissions
  • Text
  • Content Permissions
  • Option Widgets
  • User Reference

Organic Groups:

  • Organic Groups
  • Organic Groups Access control
  • OG user roles
  • Organic Groups Views integration

Views:

  • Views
  • Views UI

Save the configuration.

Note the messages from Drupal. One is likely a warning from Drupal to rebuild the content access permissions immediately .. we'll do that next, but do note the other messages. For example, you likely will see this message:

Organic Groups and OG User Roles have been enabled. A readme file is referred to that you will be able to get later at
http://mysite_address.com/sites/all/modules/og/README.txt

Also, the request to run cron is not important just now.

Rebuild content access permissions now is important. - follow the instructions from Drupal using default settings.

Now go back to the Administer Modules page by navigating to: Administer -> Site Building -> Modules.

You are now ready to enable the 11 OSF-Drupal modules listed on this page:

OSF-Drupal:

  • OSF-Drupal Core
  • Browse tool
  • Search tool
  • Dataset tool
  • Create tool
  • Update tool
  • Delete tool
  • Export tool
  • Import tool
  • Ontology tool
  • Resource tool
  • View tool

On saving, Drupal responds:

The content type Dataset has been added.
The field WSF address (field_wsf) was added to the content type Dataset.
The field Existing Dataset URI (field_existing_dataset_uri) was added to the content type Dataset.
The configuration options have been saved.

Check the 11 OSF-Drupal modules description statements (Administer -> Site Building -> Modules). All of the requirements should be enabled.

Set User Roles and Permissions

Now that the modules are enabled and registered to the system, you are ready to create OSF-Drupal user roles. Navigate to Roles - (Administer -> User Management -> Roles).

At a minimum, create the following Roles:

  • admin” - the admin role is to be assigned to the users that will administer a OSF-Drupal/structWSF instance. These users will have full access to the datasets available on the node.
  • "contributor": the contributor role is to be assigned to the users that need to contribute data to the OSF-Drupal node. These users normally just create and update data on a OSF-Drupal node.
  • "owner/curator": The owner/curator users have full data management rights on the datasets they each "own" or "curate". However, they do not have access to the administrative features of the system.

Make sure that you are setting the permissions for the following things:

  • the core OSF-Drupal module
  • all stuct*** OSF-Drupal modules
  • the permissions for the dataset content type and its related content type fields.

(As you get familiar with the system, you may add roles with differing permissions at will.)

Once roles have been defined, you are now ready to grant User Role Permissions. To do so, go to Administer -> User Management -> Permissions.

As a baseline configuration, we suggest these permissions by role:

admin – check all checkboxes to enable everything for administrator and save

contributor: check off the following:

  • block module - none
  • comment module – access, post
  • OSF-Drupal module - access
  • content module - none
  • content_permissions module – none
  • filter module – none
  • menu module - none
  • node module – access content, create dataset content, delete own dataset content, edit own dataset content, view revisions
  • og module - none
  • og_user_roles module - none
  • path module - none
  • structBrowse module - access OSF-Drupal browse,
  • structCreate module - access OSF-Drupal create,
  • structDataset module - access OSF-Drupal dataset
  • structDelete module – access OSF-Drupal delete
  • structExport module – access OSF-Drupal export
  • structImport module - access OSF-Drupal import
  • structResource module - access OSF-Drupal resource
  • structSearch module - access OSF-Drupal search
  • structUpdate module - access OSF-Drupal update
  • structView module - access OSF-Drupal view
  • system module – none
  • taxonomy module – none
  • user module – none
  • views module – none

owner/curator: check off the following:

  • block module - none
  • comment module – access, post
  • OSF-Drupal module - access
  • content module - none
  • content_permissions module – none
  • filter module – none
  • menu module - none
  • node module – access content, create dataset content, create page content, create story content, delete own dataset content, delete own page content, delete own story content, edit own dataset content, edit own page content, edit own story content, view revisions
  • og module - none
  • og_user_roles module - none
  • structBrowse module - access OSF-Drupal browse, administer OSF-Drupal browse
  • structCreate module - access OSF-Drupal create, administer OSF-Drupal create
  • structDataset module - access OSF-Drupal dataset, administer OSF-Drupal dataset
  • structDelete module – access OSF-Drupal delete, administer OSF-Drupal delete
  • structExport module – access OSF-Drupal export, administer OSF-Drupal export
  • structImport module - access OSF-Drupal import, administer OSF-Drupal import
  • structResource module - access OSF-Drupal resource, administer OSF-Drupal resource
  • structSearch module - access OSF-Drupal search, administer OSF-Drupal search
  • structUpdate module - access OSF-Drupal update, administer OSF-Drupal update
  • structView module - access OSF-Drupal view, administer OSF-Drupal view
  • system module – none
  • taxonomy module – none
  • user module – none
  • views module - access all views

anonymous user: check off the following:

  • block module - none
  • comment module – none
  • OSF-Drupal module - access
  • content module - none
  • content_permissions module – none
  • filter module – none
  • menu module - none
  • node module – access content
  • og module - none
  • og_user_roles module - none
  • structBrowse module - access OSF-Drupal browse
  • structCreate module - none
  • structDataset module - none
  • structDelete module – none
  • structExport module – access OSF-Drupal export (if you want anonymous users downloading datasets from your system)
  • structImport module - none
  • structResource module - access OSF-Drupal resource
  • structSearch module - access OSF-Drupal search
  • structUpdate module - none
  • structView module - access OSF-Drupal view
  • system module – none
  • taxonomy module – none
  • user module – none
  • views module - access all views

Configure Modules Blocks

The final step is to manage and display the links to the tools pages, in the layout of the Drupal page. Each OSF-Drupal module creates a Drupal "block". A block is a visual cluster in a Drupal user interface. To setup and display these blocks, you have to go to (Administer -> Site Building -> Blocks ). In the bottom of this page, you will see a "disabled" section, where all the OSF-Drupal blocks will appear.

Drag-and-drop all the OSF-Drupal blocks in the "Right sidebar" section of this page. Once you dragged all the blocks in that section, click the "Save blocks" button at the bottom of the page.

You will see all the tools appearing in the right sidebar of the page. You will notice that this is not that pretty. What you can do from here, is click on the "configure" link beside each OSF-Drupal block to rename their title (or remove it entirely by typing "<none>" in the title field. You can also re-order them as best fit your needs, or you can simply remove them you don't want to display on your page.

Configure structOntology Settings

In order to be able to import ontologies in your server, the first step is to configure the structOntology module that is the main user interface used to manage all the ontologies hosted on your structWSF instance.

Go to this address to access the structOntology settings page:

 /admin/settings/conStruct/structOntology

Make sure to carefully read the description of each setting in order to properly configure them.



STEP 14: Import Ontologies

The final step is to import ontologies into the instance, using the structOntology Drupal module user interface.

You can access this module by going to this path, on your Drupal instance:

 /conStruct/ontology/

If you are logged-in as an administrator, you will be able to access this module. To import, and manage, ontologies in your instance, refer to the Individual OSF-Drupal Ontology (structOntology) Tool manual.

Note: if you want to import a batch of ontologies, you will have to create a simple script that will query the /ontology/create/ structWSF web service endpoint for each ontology you want to add to your instance.

Core Ontologies to Load

The last step is to load all the core ontologies used by the Open Semantic Framework. You get the latest version of the core ontologies file to load on the instance from Structured Dynamics' GitHub Ontologies repository.

STEP 15: TEST THE INSTALLATION

The ultimate test is to be able to import a file describing record instance in RDF on the server, and then be able to search, browse, view and export records that have been imported. Once we have been able to do these steps, we will be able to confirm that the structWSF and the OSF-Drupal instances are fully operational on the server.

Import Records

The first step is to import a set of records on the server. On the server, copy and paste the RDF/XML code below in a text editor, and save the file as structwsf_test.xml:

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:ns0="http://purl.org/ontology/iron#"
xmlns:ns1="http://xmlns.com/foaf/0.1/"
xmlns:ns2="http://purl.org/ontology/cosmo#">

<rdf:Description rdf:about="http://purl.org/ontology/swt/construct_scs">
<rdf:type rdf:resource="http://purl.org/ontology/cosmo#CompositeApp_Framework"/>
<ns0:prefLabel>OSF-Drupal</ns0:prefLabel>
<ns1:page>http://constructscs.com</ns1:page>
<ns0:description>OSF-Drupal is a structured content system that extends the basic Drupal content management framework. OSF-Drupal enables structured data and its controlling vocabularies (ontologies) to drive applications and User Interfaces (semantic). OSF-Drupal provides Drupal-level CRUD (create - read - update - delete), data display templating, faceted browsing, full-text search, and import and export over structured data stores based on RDF. Depending on roles and permissions, a given user may or may not see specific datasets or tools within the Drupal interface. Collaboration networks can readily be established across multiple installations and non-Drupal endpoints.</ns0:description>
<ns2:foss>Yes</ns2:foss>
<ns2:category>Composite App/Framework</ns2:category>
<ns2:language>PHP</ns2:language>
<ns2:status>New</ns2:status>
<ns2:firstPosted>2009-10-27</ns2:firstPosted>
<ns1:thumbnail>http://www.mkbergman.com/wp-content/themes/ai3/images/swtools_thumbnails/constructscs.comb1064c04e4b5cf52b13a7c1bbc2ee4aa.jpg</ns1:thumbnail>
</rdf:Description>

<rdf:Description rdf:about="http://purl.org/ontology/swt/structwsf">
<rdf:type rdf:resource="http://purl.org/ontology/cosmo#CompositeApp_Framework"/>
<ns0:prefLabel>structWSF</ns0:prefLabel>
<ns1:page>http://openstructs.org/structwsf</ns1:page>
<ns0:description>structWSF is a platform-independent Web services framework for accessing and exposing structured RDF data. Its central organizing perspective is that of the dataset. The structWSF framework is RESTful in design and is based on HTTP and Web protocols and open standards. The initial structWSF framework comes packaged with a baseline set of about a dozen Web services in CRUD, browse, search and export and import. All Web services are exposed via APIs and SPARQL endpoints. </ns0:description>
<ns2:foss>Yes</ns2:foss>
<ns2:category>Composite App/Framework</ns2:category>
<ns2:language>PHP</ns2:language>
<ns2:status>New</ns2:status>
<ns2:firstPosted>2009-10-27</ns2:firstPosted>
<ns1:thumbnail>http://www.mkbergman.com/wp-content/themes/ai3/images/swtools_thumbnails/openstructs.orga83639af204df18df108d30c422d1389.jpg</ns1:thumbnail>
</rdf:Description>

<rdf:Description rdf:about="http://purl.org/ontology/swt/virtuoso">
<rdf:type rdf:resource="http://purl.org/ontology/cosmo#Database_Datastore"/>
<ns0:prefLabel>Virtuoso</ns0:prefLabel>
<ns1:page>http://virtuoso.openlinksw.com/wiki/main</ns1:page>
<ns0:description>OpenLink's Virtuoso is an innovative universal server platform that delivers an enterprise-level data integration and management solution for SQL, RDF, XML, Web services, and business processes. For RDF, it supports SPARQL, helpful extensions such as update, inference tables and RDFizers.</ns0:description>
<ns2:foss>Yes</ns2:foss>
<ns2:category>Database/Datastore </ns2:category>
<ns2:language>C / C++</ns2:language>
<ns2:status>Updated</ns2:status>
<ns2:firstPosted>2007-01-04</ns2:firstPosted>
<ns2:updateDate>2009-10-27</ns2:updateDate>
<ns1:thumbnail>http://www.mkbergman.com/wp-content/themes/ai3/images/swtools_thumbnails/openlinksw.comb4032b1fe4432573217a90c6cc29b9f7.jpg</ns1:thumbnail>
</rdf:Description>

</rdf:RDF>

Then, log into Drupal with your administrator account, and click on the "import" link on the right sidebar of your Drupal installation.

Note: you won't be able to go to that page if the "Clean URLs" option is not enabled on your Drupal installation. Make sure it is enabled here: (Administer -> Site configuration -> Clean URLs)

Now, let's import that file into the system:

  • Dataset file to import: Select the file you created above, from the server
  • Content type: Select "RDF+XML "
  • Dataset name: Write "Test"
  • Dataset description: Write "Test"
  • Save dataset on this network: Select "http://localhost/ws/"

Finally click on the "Import Dataset" button.

If the import is successful, you should be redirected to the "Browse tool", and see the three records that have been imported from the test file.

Note: results are not skinned with the default installation, so the results can appear crude at a first glance.

View Records

Once you see the files in the Browse tool, it means that everything got properly imported in the system. Next, you can click on one of the results to see its complete description.

At that point, you are using the default template to visualize all the information available for the given record.

Search Records

Next you can search the records using the Search tool. Click on the "search" link in the right sidebar. Then search for the "rdf" keyword. You will get results where the keyword "rdf" is found. This test ensures that the search capabilities of Solr are working.

Delete Dataset

Finally let's delete the dataset we imported. Click on the "Dataset" link in the right-sidebar. Then click on the "remove linked dataset" link for the "Test" dataset. You will be requested to confirm the deletion of the dataset. You simply have to click on the "delete group" button to delete the dataset.

Finally you will get a confirmation that the dataset has been deleted. If you try to browse or search datasets, you won't see any since the only one that was in the system as just been deleted.

If you have been able to perform all these steps without any error messages, it means that you fully and properly configured your server with structWSF and OSF-Drupal.


APPENDIX: LISTING OF COMPONENTS

This is a list of all the programs used in this installation (plus others) and their version numbers:

Component + Link Version License Install Step [1]
Open Semantic Framework (OSF)

Ubuntu Server

12.10 64 bit

Ubuntu license

1

PHP5

5.4.6

PHP License v3.01

2

iODBC

3.52.7

GPL v2 and BSD

2

cURL

7.27.0

MIT/X derivate license

2

autoconf



2

gawk



2

libssl-dev



2

openssl



2

unzip



2

php5-odbc



2

php5-cli



2

vim



2

libapache2-mod-php5



2

Java

7.25

Binary Code License (BCL)

2

MySQL

5.5.34

GPL

2,4

Apache2

2.2.22

Apache License 2

3

phpMyAdmin

GPL v2

4

Virtuoso

6.16

GPL v2

6

Solr

3.3

Apache License 2

7,8

Memcached

1.4.14

New BSD License

7,8

OSF Web Service

1.0a8

Apache License 2

8

ARC2

2.0.0 W3C Software License, GPL v2 and v3 9

Drupal

7.25

GPL v3

10

OSF for Drupal

7.x-3.0

GPL v3

10

jQuery

1.6.2

GPL v2 and MIT

---
Semantic Components

Degrafa

3.1

MIT

---

FlexToolBox

various

MIT

---

OSF Widgets

3.0

Base version: CC BY-NC-SA 2.5

---

Flare

alpha

BSD

---

Axiis

beta 1.0

MIT

---

Google Maps API (Flash)

1.20
---

ClearMaps


Sunlight Foundation License

---

FlexLib - Highlighter class


MIT

---

Scones

1.0

Apache License 2

---

GATE

6.0

LGPL

---

PHP/Java Bridge

6.2.1 LGPL, MIT ---
Ontologies Development and Maintenance

Protégé 4

4.1

Mozilla Public License

---

[http://owlapi.sourceforge.net/ OWLAPI (OWL2)

3.2.4

LGPL

---

Pellet

2.1.2

AGPL version 3

---

HermiT

1.3.4

GPL v3 +

---

Fact++

1.5.2

LGPL

---

Cytoscape

2.8

LGPL

---

Gephi

0.8 alpha
---
Ontologies and Specifications

UMBEL

1.01

Creative Commons Attribution 3.0

---

SCO - Semantic Component Ontology


Creative Commons Attribution 3.0

---

irON

0.9

Creative Commons Attribution 3.0

---



APPENDIX: SECURITY CHECK LIST

Before making a structWSF instance accessible on the Web, you should think about performing some security checks to make sure your server is not at risk. This is not a Linux server security guide, but simply points to some useful checks before making your system accessible on the Web. Please read more detailed papers or Web sites that talk about other things you should do to create a secure Linux server.

  • Make sure all software is up-to-date by running these two commands: (1) apt-get update, (2) apt-get upgrade
  • Change all default passwords for these software packages:
    • MySQL
    • Virtuoso
    • Ubuntu
  • Make sure that people cannot connect to the SSH server by using the root user account
  • Use public/private (preferably with a passphrase) keys to connect to the SSH server, and disable connection using password
  • Using the firewall, block all ports on the server. Then open the port 80 and 22 to everybody, and ports 8890 (Virtuoso) and 8983 (Solr) to the localhost only (and/or people you want them to have access to these user interfaces).
  • Make sure you deleted/moved/renamed the wsf_indexer.php script
  • Make sure that you restricted the access to the /ws/ontology/admin/ folder or that you simply removed the files on the server.

APPENDIX: AN AMAZON EC2/EBS ARCHITECTURE

At Structured Dynamics, we have developed and use a server architecture that leverages Amazon computer-in-the-clouds services such as: EC2, EBS, Elastic IP in the Cloud. Such an architecture is giving us the flexibility to easily maintain and upgrade server instances, to instantly create new structWSF instances in one click (without performing all these steps every time), etc.

You can contact us for more information about these EC2 AMIs and EBS Volumes that we developed for this purpose. Here is an overview of the architecture that is in place:

Amazon EC2/EBS architecture

There is a clear separation of concerns between three major things:

  • Software and libraries
  • Configuration files
  • Data files.

We chose to put all software and libraries needed to create a stand-alone structWSF instance in an EC2 AMI. This means that all needed software to run a structWSF instance is present on the Virtuoso server running Ubuntu server.

Then we chose to put all configuration and data files on a EBS volume that we attach, and mount, on the EC2 instance. You can think about a EBS volume as a physical hard drive: it can be mounted on a server instance, but it can't be shared between multiple instances.

By splitting the software & libraries, configuration and data files, we make sure that we can easily upgrade a structWSF server in production with the latest version of structWSF (its code base and all related software such as Virtuoso, Solr, etc). Since the configuration and data files are not on the EC2 instance, we can easily create a new EC2 instance by using the latest structWSF AMI we produced, and then to mount the configuration and data files EBS volume on the new (and upgraded) structWSF instance. That way, in a few clicks, we can fully upgrade a server in production without fear of disturbing the configuration or data files.

Additionally, we can easily create backups of configuration and data files at different intervals by using Amazon's Snapshot technology.

Finally, we chose to put all related software and configuration files needed to run a OSF-Drupal instance in another, seperate, EBS volume. That way, we have a clean structWSF AMI instance that can be upgraded at any time, and we can plug (mount) a OSF-Drupal instance (EBS instance) into a structWSF server at any time. This means that we can easily have structWSF instances with or without a OSF-Drupal instance. The same strategy can easily be used to create plug-in packages that can be mounted and unmounted to any structWSF instance at any time, depending on the needs.

All this makes the maintenance of structWSF server instances easier, simpler and faster.


REFERENCES

  1. OSF-Drupal is a structured content system that extends the basic Drupal content management framework. OSF-Drupal enables structured data and its controlling vocabularies (ontologies) to drive applications and user interfaces. OSF-Drupal has a Web site, a Google discussion group, a Drupal code distribution project, and is backed by structWSF (see next).
  2. structWSF is a platform-independent Web services framework for accessing and exposing structured RDF data, with generic tools driven by underlying data structures. Its central perspective is that of the dataset. Access and user rights are granted around these datasets, making the framework enterprise-ready and designed for collaboration. Since a structWSF layer may be placed over virtually any existing datastore with Web access -- including large instance record stores in existing relational databases -- it is also a framework for Web-wide deployments and interoperability.