Installing BELTS

Installation of this release requires Version 1.4.2 of the Java Development Kit, available from http://java.sun.com/. The JAVA_HOME environment variable should be set to the home directory of your JDK installation in a manner appropriate to your operating system.

Using the tools appropriate to your environment, create a “belts” user, giving the user a password appropriate to your organisation.

	Note
	Under Windows, the user needs to be a member of the local computer Administrators group. All of the following commands should be performed while logged in as this user.

Unpack BELTS into a directory of your choosing using the appropriate tool for your platform.

Linux:

$ cd /usr/local
$ tar xvzf /mnt/cdrom/belts-1.2.0.tgz [substitute actual file location]
$ ln -s belts-1.2.0 belts
$ chown -R belts.belts belts*

Windows:

Use Winzip or similar program to unzip the BELTS distribution into the desired directory

The belts-1.2.0 directory created above will be known as BELTS_HOME for the rest of this procedure. It is helpful to add this variable to your platform's environment for ease of navigation, as follows.

Linux:

$ export BELTS_HOME=/usr/local/belts-1.2.0

Windows:

C:\> set BELTS_HOME=c:\belts-1.2.0

If you downloaded the minimal installation package, you will need to copy the unpacked files over a JBoss Version 4.0.1 installation.

Linux:

$ cd /usr/local/jboss [substitute actual location]
$ cp -R /usr/local/belts-1.2.0/* .

Under Windows use Windows Explorer to copy the belts-1.2.0 directory contents over the contents of your jboss-4.0.1 directory, electing to overwrite files if they already exist.

You now need to set BELTS_HOME to point to your JBOSS_HOME directory, as follows:

Linux:

$ export BELTS_HOME=$JBOSS_HOME

Windows:

C:\> set BELTS_HOME=%JBOSS_HOME%

BELTS Version 1.2.0 supports PostgreSQL only. Please refer to the following instructions to prepare your system to run BELTS.

Postgres Installation

	Note
	BELTS is currently setup to work with PostgreSQL Version 7.4 since that is the most common version out there at the moment. If you are running a different version, you will need to download a JDBC2 jar file for your version from http://jdbc.postgresql.org/download.html and use it to replace BELTS_HOME/server/default/lib/postgresql.jar.

Linux Installation

Ensure postgres is installed in your Linux environment by using the appropriate tool for your distribution to install it. Once installed, there is often no need to change anything to get BELTS to work successfully.

Once postgres is installed, BELTS can be installed by extracting the downloaded file and performing the steps outlined in the the section called “BELTS Database Creation”.

Windows Installation

A Windows executable for postgres may be downloaded from http://www.postgresql.org/download/. Once downloaded, install the package as per the documentation.

Once postgres is installed, BELTS can be installed by extracting the downloaded file and performing the steps outlined in the the section called “BELTS Database Creation”.

BELTS Database Creation

Once postgres is installed, create the BELTS user, database and tables by performing the following steps:

1. Use createuser to create a postgres user called “belts”. This user does not need to be able to create databases or users. The password for the belts user is currently set to “verysecret”. If desired, this can be changed by updating BELTS_HOME/server/default/deploy/belts-ds.xml.

   createuser --username=postgres --password

2. Create the belts database

   createdb --username=belts --encoding=latin1 belts

   	Note
   	The latin1 encoding is not always supported by the postgres servers for Windows. This doesn't seem to be an issue in our testing.

3. Create the belts database tables

   Linux:

   $ cd $BELTS_HOME/server/default/setup
   $ psql belts belts < tables.sql

   Windows:

   C:\> cd %BELTS_HOME%\server\default\setup
   C:\belts-1.2.0\server\default\setup> psql belts belts < tables.sql

By default, BELTS listens on port 8080 for requests. This can be changed to any other port by editing BELTS_HOME/server/default/deploy/jbossweb-tomcat50.sar/server.xml. In this file, find the following lines:

<Connector port="8080" address="${jboss.bind.address}"
     maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
     enableLookups="false" redirectPort="8443" acceptCount="100"
     connectionTimeout="20000" disableUploadTimeout="true"/>

Change the “8080” to the desired port number.

Note

On Linux, a normal user process cannot open a server on “privileged” ports. In this environment, you should use Apache's mod_proxy or some other facility to map a call to a URL on port 80 to your BELTS server running on port 8080. On Windows, there are no restrictions on the port you use, but you should ensure that you do not have IIS or another web server running if you wish to use port 80 for your BELTS server.

If you need to use a proxy server to access the internet, you will need to change some settings. In BELTS_HOME/server/default/deploy/belts-services.sar/META-INF/jboss-service.xml, find the lines describing the HttpClientPool service and adjust them to your settings.

The default settings are as follows:

<!-- HTTP Client Pool -->
<mbean
    code="au.edu.educationau.belts.management.http.HttpClientPoolService"
    name="belts:service=HttpClientPool">
  <attribute name="JndiName">belts/httpclient-pool</attribute>
  <attribute name="Configuration">
    <! [ CDATA [
      <client-pool pool-size="4">
        <!-- proxy port="" host="" username="" password=""/ -->
      </client-pool>
    ] ] >
  </attribute>
</mbean>

To change this for your environment, remove the comments around the line describing the proxy and replace it with your own settings. For example, at TLF, the following settings are required:

<proxy port="3128"
    host="melbourne.cache.telstra.net" username="" password=""/>

BELTS needs to be able to send emails to users to notify them of events, such as content being downloaded, etc. To do this, open BELTS_HOME/server/default/deploy/belts-services.sar/META-INF/jboss-service.xml, and find the lines describing the SMTPMailDispatcherService. Adjust these lines to your settings. For example, the BELTS demo site at Jacus uses the following:

<mbean name="belts:service=SMTPMailDispatcherService"
    code="au.edu.educationau.belts.management.mail.SMTPMailDispatcherService">
<attribute name="Sender">jacus-belts@jacus.com.au</attribute>
<attribute name="Prefix">Belts</attribute>
<attribute name="ServerName">localhost</attribute>
</mbean>

In this configuration, mail is sent by localhost and comes from jacus-belts@jacus.com.au. Mail sent by this host is prefixed with “Belts” so it is obvious where the mail came from.

BELTS provides definitions of a number of Providers, used to “provide” content to the BELTS environment. Depending on whether your system is a BELTS Central server or a downstream client, you will need to setup a Learning Exchange Provider connection or a BELTS Provider connection.

BELTS offers the ability to specify that a provider should automatically download and/or publish new content as it becomes available. In the following configuration examples, changing autoload to “true” will make the provider automatically download the content, while changing autopublish to “true” will make the provider automatically publish the content once it is downloaded.

<!--
<mbean code="au.edu.educationau.belts.management.provider.ProviderService"
      name="belts:service=Provider,name=exchange">
  <depends>belts:service=ContentStore</depends>
  <depends>belts:service=HttpClientPool</depends>
  <attribute name="JndiName">belts/content/provider/exchange</attribute>
  <attribute
    name="ProviderClass">au.edu.educationau.belts.content.LoraxProvider</attribute>
  <attribute name="Configuration">
    < ! [ CDATA[<lorax id="exchange"
      url="http://lex.thelearningfederation.edu.au/webservices/LearningExchange.asmx"
      username="changeme" password="changeme"
      autoload="false" autopublish="false"/> ] ]>
  </attribute>
</mbean>
-->

<!--
<mbean code="au.edu.educationau.belts.management.provider.ProviderService"
      name="belts:service=Provider,name=belts">
  <depends>belts:service=ContentStore</depends>
  <depends>belts:service=HttpClientPool</depends>
  <attribute name="JndiName">belts/content/provider/belts</attribute>
  <attribute
    name="ProviderClass">au.edu.educationau.belts.content.BeltsProvider</attribute>
  <attribute name="Configuration">
    <! [ CDATA[<belts id="belts"
      url="http://upstream.example.com/belts/provide/"
      username="changeme" password="changeme"
      autoload="false" autopublish="false"/> ] ]>
  </attribute>
</mbean>
-->

Having specified the provider to use, it is also necessary to specify an update schedule, specifying the times at which your provider will be queried for updates. You will need to setup a schedule for the provider id that you specified earlier.

In BELTS_HOME/server/default/deploy/belts-services.sar/META-INF/jboss-service.xml, find the configuration lines containing the configuration for an mbean with the name belts:service=UpdateScheduler,provider=changeme and replace “changeme” with the name of your provider (either “exchange” or “belts”). You will also need to put the provider id in the “SchedulableArguments” attribute.

The attributes related to the actual timing of the update are the “InitialStartDate” (in the format “mm/dd/yy hh:mm am/pm” or “NOW” to perform an update on startup) and “SchedulePeriod” attributes (specified in milliseconds). The following table provides a set of useful values for the “SchedulePeriod” attribute.

<mbean code="org.jboss.varia.scheduler.Scheduler"
    name="belts:service=UpdateScheduler,provider=changeme">
  <depends>belts:service=ContentStore</depends>
  <attribute
    name="SchedulableClass">au.edu.educationau.belts.content.ScheduledUpdate</attribute>
  <attribute name="StartAtStartup">true</attribute>
  <attribute name="InitialStartDate">01/01/1970 12:00 am</attribute>
  <attribute name="SchedulePeriod">86400000</attribute>
  <attribute name="InitialRepetitions">-1</attribute>
  <attribute name="SchedulableArgumentTypes">java.lang.String</attribute>
  <attribute name="SchedulableArguments">changeme</attribute>
</mbean>

If you have been supplied with a curriculum organiser file for your installation, you can setup BELTS to use it by placing the supplied file into the directory BELTS_HOME/server/default/conf/belts.

In BELTS_HOME/server/default/deploy/belts-services.sar/META-INF/jboss-service.xml, find the configuration lines containing the configuration for an mbean with the name belts:service=CurriculumOrganiser, remove the lines containing “<!--” and “-->” and replace “sample-organiser.xml” with the name of your file.

<mbean code="au.edu.educationau.belts.management.curriculum.CurriculumOrganiserService" name="belts:service=CurriculumOrganiser">
    <attribute name="JndiName">belts/content/organiser</attribute>
<!--
	<attribute name="OrganiserPath">sample-organiser.xml</attribute>
-->
	</mbean>

The EdNA searcher requires a search user to be specified to allow the EdNA team to track usage of the service. To register and generate a user id, go to http://search.edna.edu.au/ and select the “Register” link.

In BELTS_HOME/server/default/deploy/belts-services.sar/META-INF/jboss-service.xml, find the configuration lines describing belts:service=Searcher,name=edna and setup your search user, by replacing “changme” with the name sent to you by EdNA.

<!-- EdNA Searcher -->
<mbean code="au.edu.educationau.belts.management.searcher.SearcherService" name="belts:service=Searcher,name=edna">
    <depends>belts:service=HttpClientPool</depends>
    <attribute name="JndiName">belts/content/searcher/edna</attribute>
    <attribute name="SearcherClass">au.edu.educationau.belts.search.edna.EdNASearcher</attribute>
    <attribute name="Configuration">
            <![ CDATA [<edna id="edna" url="http://search.edna.edu.au/dsm/xml/search" user="changeme" strategy="waitall" sort="relevance" dupes="false" max-results="200" username="" password=""/> ] ]>
    </attribute>
</mbean>

BELTS displays a Privacy Statement for your site, which is linked from the front page. It comes with a default privacy statement, but this can be modified to have the content required by your organisation.

Edit the file BELTS_HOME/server/default/deploy/belts.ear/belts-web.war/static/privacy.ihtml and enter the HTML for your privacy page between the marked lines.

<?xml version="1.0" encoding="iso-8859-1"?>
<belts:page
	xmlns:belts="http://thelearningfederation.edu.au/ns/belts/page/2003/01"
	xmlns="http://www.w3.org/1999/xhtml"

	<belts:title>Privacy</belts:title>

	<!-- Replace the following text with your privacy statement -->

	<p>Insert your privacy statement here</p>

	<!-- Do not touch anything below this line -->
</belts:page>

BELTS displays a set of terms and conditions for your site, which is linked from the front page. BELTS provides a standard set of terms and conditions, but allows you to modify these as required to suit your organisation.

Edit the file BELTS_HOME/server/default/deploy/belts.ear/belts-web.war/static/terms-and-conditions.ihtml and enter the HTML for your terms and conditions between the marked lines.

<belts:page
	xmlns:belts="http://thelearningfederation.edu.au/ns/belts/page/2003/01"
	xmlns="http://www.w3.org/1999/xhtml"
>
	<belts:title>Terms and Conditions</belts:title>
	
	<!-- Replace the following text with your terms and conditions -->

	<p>Insert your terms and conditions here</p>

	<!-- Do not touch anything below this line -->
</belts:page>

Linux:

$ cd $BELTS_HOME/bin
$ ./belts console

Windows:

C:\> cd %BELTS_HOME%\bin
C:\belts-1.2.0\bin> belts

The server takes around 1 or 2 minutes to startup depending on the hardware it is running on.

The first data to import is the core data. Press the Browse button and navigate to BELTS_HOME/server/default/bootstrap/core-data.xml, then select Import. If all goes well, you will see a message indicating that the import was successful.

You are now in a position where you have an administrative user called “beltsadmin” with a password of “beltsadmin”. You can now log in as this user to set up your schools, etc.

To import some test data, import the file BELTS_HOME/server/default/bootstrap/test-data.xml. This sample data contains the following users:

All of these users are given an initial password of “belts”.

The Viewing area for Netscape 6 is a set display area. This is due to the non-scalability of objects within this particular browser because of a browser limitation. Depending on your setup and/or preferred screen resolution then you may want to alter the display area for the objects.

The change needs to be made to an xslt file located in:

$BELTS_HOME/server/default/deploy/belts.ear/belts-web.war/xsl/object-width.xslt

The current settings are as follows:

<object data="{@data}" type="{@type}" width="790px" height="590x">
			<xsl:apply-templates select="./*"/>
		</object>

Simply modify the settings for Pixel width and height as appropriate to your needs. Any edit to this particular file should not be performed unless the user is familiar with xslt. Incorrectly editing this file will break the entire server. i.e. no pages will be served.

When attempting to view an object then nothing is displayed (A blank/white viewing area is displayed). Some browsers (eg Internet Explorer) will automatically detect that this is the case and will direct you to an install. Others (eg Netscape) will simply remain as a blank white screen.

The likely problem here is that your browser does not have the correct plug-ins installed to display the particular object you are trying to view. Resolution: Depending on the object type then the likely fix to this is to visit the website http://www.macromedia.com/downloads/. At this site you should download both the latest version of Macromedia Flash Player and Macromedia Shockwave Player. Before running each of these files it is recommended to shutdown all instances of your browser before running each install.

If you find you get errors from the web server when you try to upload extremely large files, change the following line in BELTS_HOME/server/default/deploy/belts.ear/belts-web.war/WEB-INF/web.xml

<init-param>
  <param-name>upload-max-size</param-name>
  <param-value>16777216</param-value>
</init-param>

If you use the Safari browser on Mac OS X, you may find that the 60-second browser timeout is shorter than the amount of time it takes for high end cache regeneration and synchronisation functions to be acknowledged (you may also be experiencing timeout issues with other websites using the safari browser). Repeating the submissions may not resolve the problem due to a 60 second timeout setting within Safari.

To overcome this issue you may want to install SafariNoTimeout (http://www.unsanity.com/haxies/snt), a free extension that will increase the 60-second timeout to 10 minutes.

By default, BELTS tries to listen on all ip addresses assigned to the machine, but it's quite straight-forward to change.

In BELTS_HOME/server/default/deploy/jbossweb-tomcat50.sar/server.xml, find the following lines:

<Connector port="8080" address="${jboss.bind.address}"
     maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
     enableLookups="false" redirectPort="8443" acceptCount="100"
     connectionTimeout="20000" disableUploadTimeout="true"/>

Replace the text

${jboss.bind.address}

Restart the BELTS service

BELTS is distributed with a memory configuration design for machines with 1Gb of RAM. If the machine you are installing on has more or less than this amount, you should adjust the maximum amount of memory used by the Java virtual machine.

All configuration elements for the Java virtual machine are located in:

$BELTS_HOME/conf/wrapper.conf

The current setting for maximum Java heap size is as follows:

# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=768

If you want to change the maximum memory allocation for the Java virtual machine, change this value to a number that makes sense for your configuration.

In recent JBoss versions, Tomcat has replaced Jetty as the web server. Under some conditions, it may be desired to put Jetty back in as the web server engine.

In order to do this, download the release of Jetty for JBoss Version 4.0.1 from http://www.mortbay.org/jetty/jboss/index.html and follow the installation instructions available from that site.