Installing BELTS

This section describes how to install BELTS.

Before Installing

The Basic E-Learning Tool Set is a sophisticated web-based application. The software should be installed and configured by an experienced technician. Technicians should be experienced in securing and administering web and database servers. These instructions only relate to the installation of the BELTS application onto an existing preconfigured operating system. Failure to properly configure the host machine could result in an unsecured device on your network.

Education institutions should be aware of the software distributions they are using. All software should be tested and control of distributions maintained.



Upgrading from Version 1.0 of BELTS requires an intermediate upgrade to Version 1.0.1 if you wish to preserve any data stored in your original setup. Please refer to the BELTS Development Site for instructions on obtaining and installing the 1.0.1 release of BELTS.

Before upgrading BELTS under Windows, please ensure that you uninstall the service first, as described in the section called “Running as a Windows service”.

Procedure 1. Upgrade from Version 1.0.1 of BELTS

  1. On the Version 1.0.1 installation, log in as the “bootstrap” user and export your system data, as outlined in Exporting Data .

  2. Back up your Version 1.0.1 installation. This includes any data files in /var/lib/belts.

  3. Install Version 1.2 of BELTS, as outlined in Installation .

  4. Start your Version 1.2 installation as outlined in Start the BELTS server and wait for the server to do a complete update from the Exchange.

    You can tell when a complete Exchange update has been performed by watching the file BELTS_HOME/server/default/log/wrapper.log for a line that looks like

    INFO   | jvm 2    | 2003/08/28 15:07:07 | 15:07:07,187 INFO
      [ScheduledUpdate] Update on provider exchange finished

  5. Stop your Version 1.2 server as outlined in Running as a service .

  6. In BELTS_HOME/bin, run the “upgrade” program, with the following parameters:

    • the name of your Exchange provider (“exchange”)

    • the location of the exported XML file from above

    • the location of your Version 1.0.1 BELTS data directory (/var/lib/belts)

    • the location of an output directory for the upgraded data (not your Version 1.2 BELTS data directory)


    $ ./ exchange /tmp/belts-1.0-export.xml /var/lib/belts


    C:\belts-1.2.0\bin> upgrade exchange \tmp\belts-1.0-export.xml
     \var\lib\belts %TEMP%\belts-1.2

    This process could take up to 10 minutes depending on the amount of data in your Version 1.0.1 installation.

  7. Copy your newly-generated data directory over the Version 1.2 data directory


    $ cp -R /tmp/belts-1.2/* $BELTS_HOME/server/default/data/belts


    C:\belts-1.2.0\bin>xcopy %TEMP%\belts-1.2 ..\server\default\data\belts /s /e

    When asked whether to overwrite files, select “All”.

  8. Restart your Version 1.2 installation.

  9. Using the file generated during the upgrade process, import your system data, as outlined in Importing Data . The file name to import will be import-1.2.xml and it will be in BELTS_HOME/server/default/data/belts.

  10. Login as a Content Manager and perform the Regenerate XML Cache function. This will ensure that the content cache is up-to-date.

Procedure 2. Upgrade from an earlier (not Version 1.0.1) installation of BELTS

  1. Back up your earlier installation. In particular, you will need to have a copy of any data files in BELTS_HOME/server/default/data/belts/contentdir.

  2. Install the latest version of BELTS, as outlined in Installation .

  3. Copy your old data back into BELTS_HOME/server/default/data/belts.


    $ cp -R /tmp/belts/* $BELTS_HOME/server/default/data/belts


    C:\belts-1.2.0\bin>xcopy %TEMP%\belts ..\server\default\data\belts /s /e
  4. Start your new installation as outlined in Start the BELTS server .

  5. Login as a Content Manager and perform the Regenerate XML Cache function. This will ensure that the content cache is up-to-date.



BELTS comes in two downloadable versions: the “full” version, which provides its own copy of JBoss Version 4.0.1, and a “minimal” version, which is designed to be copied over an existing JBoss Version 4.0.1 installation.

Before installing the minimal version, you need to be aware that there are two JBoss system files that are required to be modified for BELTS. These files are:

  • BELTS_HOME/server/default/conf/jboss-service.xml and

  • BELTS_HOME/server/default/conf/login-config.xml

If you are already running other JBoss applications, you will need to ensure that you merge the changes in these files across, so that you don't overwrite changes that have been made for other applications.

In addition, the dom4j jar file in the JBoss Version 4.0.1 installation, needs to be replaced due to an incompatibility in the way that classes from this package are serialised.

After installation, copy dom4.jar from JBOSS_HOME/server/default/deploy\belts-services.sar to JBOSS_HOME/lib.

JDK Installation

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

Create your BELTS User

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


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

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


$ 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*


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.


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


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.


$ 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:





Setup your database

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

Postgres Installation


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 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 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


    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


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


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

Web Server Port Setup

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.


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.

HTTP Proxy Setup

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 -->
  <attribute name="JndiName">belts/httpclient-pool</attribute>
  <attribute name="Configuration">
    <! [ CDATA [
      <client-pool pool-size="4">
        <!-- proxy port="" host="" username="" password=""/ -->
    ] ] >

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="" username="" password=""/>

Mail Dispatcher Service

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"
<attribute name="Sender"></attribute>
<attribute name="Prefix">Belts</attribute>
<attribute name="ServerName">localhost</attribute>

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

Provider Setup

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.

Learning Exchange Provider

In BELTS_HOME/server/default/deploy/belts-services.sar/META-INF/jboss-service.xml, find the configuration lines describing the belts:service=Provider,name=exchange, remove the lines containing “<!--” and “-->” and set your username and password. The default values for these are set to “changeme”.

<mbean code=""
  <attribute name="JndiName">belts/content/provider/exchange</attribute>
  <attribute name="Configuration">
    < ! [ CDATA[<lorax id="exchange"
      username="changeme" password="changeme"
      autoload="false" autopublish="false"/> ] ]>

BELTS Provider

In BELTS_HOME/server/default/deploy/belts-services.sar/META-INF/jboss-service.xml, find the configuration lines describing the belts:service=Provider,name=belts, remove the lines containing “<!--” and “-->” and set your server URL, username and password. The default values for these are set to “” for the host name and “changeme” for the username and password. Note that the URL for the BELTS provider is the BELTS server name, plus the string “/provide”. For example, if your upstream BELTS is accessed as “”, then your BELTS provider should be set to “”. If you upstream BELTS is accessed as “”, then your BELTS provider should be set to “”.

<mbean code=""
  <attribute name="JndiName">belts/content/provider/belts</attribute>
  <attribute name="Configuration">
    <! [ CDATA[<belts id="belts"
      username="changeme" password="changeme"
      autoload="false" autopublish="false"/> ] ]>

Scheduled Update Setup

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.

Schedule PeriodSchedulePeriod Setting
1 minute60000
2 minutes120000
60 minutes3600000
2 hours7200000
8 hours28800000
12 hours43200000
24 hours86400000

Table 1. SchedulePeriod Attribute settings

<mbean code="org.jboss.varia.scheduler.Scheduler"
  <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>

Setup your Curriculum Organiser

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="" name="belts:service=CurriculumOrganiser">
    <attribute name="JndiName">belts/content/organiser</attribute>
	<attribute name="OrganiserPath">sample-organiser.xml</attribute>

Setup your EdNA Searcher

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 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="" name="belts:service=Searcher,name=edna">
    <attribute name="JndiName">belts/content/searcher/edna</attribute>
    <attribute name="SearcherClass"></attribute>
    <attribute name="Configuration">
            <![ CDATA [<edna id="edna" url="" user="changeme" strategy="waitall" sort="relevance" dupes="false" max-results="200" username="" password=""/> ] ]>

Setup your Privacy Statement

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"?>


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

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

	<!-- Do not touch anything below this line -->

Setup your Terms and Conditions

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: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 -->

Start the BELTS server


$ cd $BELTS_HOME/bin
$ ./belts console


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.

Running as a service

Running as a Windows service

If you wish to have the server started as a Windows service, run the install batch file in %BELTS_HOME%\bin. The service will be started automatically the next time the machine is booted or you can run net start belts to start it immediately. To remove the service, run the uninstall batch file.

Install the service:

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

Start the service:

C:\belts-1.2.0\bin> net start belts

Stop the service:

C:\belts-1.2.0\bin> net stop belts

Uninstall the service:

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

Running as a Linux service

Under Linux, the BELTS service can be installed in /etc/init.d by copying the file from the $BELTS_HOME/bin directory. Use chkconfig to make BELTS start on startup.

$ cp $BELTS_HOME/bin/ /etc/init.d/belts
$ chkconfig --add belts

Start the service:

$ service belts start

Stop the service:

$ service belts stop

Note that the BELTS init script checks for the BELTS_HOME environment variable and, if not set, assumes /usr/local/belts.

Accessing BELTS

BELTS can be accessed by loading a web browser and going to http://localhost:8080/ if you are accessing it from the machine it is running on. If it is running on another machine, replace localhost with the name of that machine.

Importing Data

When BELTS is first installed, there is a single user defined (the “bootstrap” user). At the login screen, enter “bootstrap” as both the username and password and press the Login button. You will then be presented with a simple home screen. Select the Bootstrap link on the left of the screen to have the opportunity to import some basic data into the system.


For security reasons, you should change the password of your bootstrap user once you have imported your initial data. This can be done by editing BELTS_HOME/server/default/conf/belts.users and changing the line:

where “newpassword” is the desired password.

Importing Core Data

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.

Importing Test Data

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

  • System Administrators

    • test-administrator-1

    • test-administrator-2

  • Content Manager

    • test-manager-1

    • test-manager-2

  • Users from test-school-1

    • test-school-admin-1 - a school administrator

    • test-teacher-1 - a teacher

    • test-student-1 - a student

  • Users from test-school-2

    • test-school-admin-2 - a school administrator

    • test-teacher-2 - a teacher

    • test-student-2 - a student

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

Exporting Data

If you wish to export your existing data, log in as the bootstrap user, go to the Bootstrap link and select Export. This will display the current database contents in an XML format that can be saved and used as an import file later on.


For security reasons, your bootstrap user may have had its password changed during installation. The password can be determined by looking at BELTS_HOME/server/default/conf/belts.users and finding the line with the username and password. It will look something like:


Miscellaneous Installation Tips

Configuring The Viewing Area for Netscape 6

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:


The current settings are as follows:

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

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.

Potential Problems

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 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.

Increasing the allowed size for uploaded content

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

This is the value (in bytes) of the maximum allowable uploaded file size.

Safari browser 60-second timeout

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 (, a free extension that will increase the 60-second timeout to 10 minutes.

How to make BELTS listen on a particular IP address

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

by the IP address you want BELTS to listen on.

Restart the BELTS service

Configuring The Maximum Heap Space Used by the Java Virtual Machine

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:


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

# Maximum Java Heap Size (in MB)

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.

Setting up Jetty instead of Tomcat

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 and follow the installation instructions available from that site.