Building LAMS

Current Stable Release: LAMS 2.1 Don't want to build from source? Use the Downloads for various installers

So, you want to play with Dolly?

Just started with LAMS 2.1? Want to build the source code?

Have a minute to read LAMS license: LAMS is released under the GPL license version 2,

After that, have a look at This five minute guide to building LAMS.

Install Required software

See Development Environment

Configure JBOSS

Copy jboss-cache.jar, jgroups.jar from server/all/lib to server/default/lib.

Getting LAMS

There are two ways. One you can download LAMS as a zipped file or use CVS to get the latest code.

Downloading LAMS as a zipped file

See the Downloads page.

Getting it from CVS

The LAMS code is available for viewing via the web at http://lamscvs.melcoe.mq.edu.au/cgi-bin/viewcvs.cgi/.

Configure your cvs client as follows:

• access method: pserver
• user name: anonymous
• server name: lamscvs.melcoe.mq.edu.au
• location: /usr/local/cvsroot

The anonymous account does not require a password, so if your client asks for a password then leave it blank. If your client won't let you leave it blank then typing in some dummy password should work - our CVS should ignore it.

Checkout the following projects from CVS:

• lams_admin
• lams_build
• lams_central
• lams_common
• lams_contentrepository
• lams_learning
• lams_monitoring
• lams_tool_chat
• lams_tool_deploy
• lams_tool_forum
• lams_tool_lamc
• lams_tool_laqa
• lams_tool_larsrc
• lams_tool_nb
• lams_tool_notebook
• lams_tool_sbmt
• lams_tool_scribe
• lams_tool_survey
• lams_tool_task
• lams_tool_vote
• lams_www

To check out the current released version of LAMS 2.1, check out the code on the "lams2_1" tag. If you check out from the head, you will get the most recent code, which should run but may be partway through changes. More information about tags see CVS Repositories, Branching and TAGS.

For each release, we tag the code accordingly (i.e.: LAMS 2.0.2 has a tag lams2_0_2). If you want to see the tags, use the <a href="http://lamscvs.melcoe.mq.edu.au/cgi-bin/viewcvs.cgi/">LAMScvs server</a> or see your cvs client.

There are also four other projects (lams_documents, lams_tool_deploy, lams_tool_example, lams_flash) that are be useful for particular tasks if you are doing development of LAMS, but they aren't required to build LAMS. Lams_flash contains the files for Flash development so only check out that project if you want to use the Flash development files.

If you want to use jsmath, then you will also need the jsmath project. Don't check this out unless you really want it - it is a very large project.

If you are using Eclipse, you can check out the code by going to File, Import, open the CVS option and then select Projects from CVS. If you are going to build LAMS using Eclipse then this is the easiest way to get it out of CVS (rather than trying to use another CVS client and then copy the code into the Eclipse workspace). Just make sure you keep pressing "Next" until you are given the choice to select the Version tag.

Property Files and LAMS Configuration Table

Go through the properties files in the lams_build project and set the entries to suit your PC. In particular check common.properties and windows.properties or unix.properties as they might require some editing according to your setup.

Configure the LAMS Configuration table. This is the system configuration table - updated via System Administration - the sql to create the table is in either lams_common/db/sql/insert_windows_config_data.sql or lams_common/db/sql/insert_unix_config_data.sql (OS dependant). The main entries you will need to configure are as follows:

This is a really important data table - an invalid entry in this table and LAMS may not work.

If you are unsure of the LAMS Configuration settings then they can be changed after building. See under the section "Start JBOSS".

Database Setup

This assumes you have MySQL installed. If you want more information on the database see Database Conventions and Datasources.

Set up a user "lams" in MySQL and an empty lams database. Assign the "lams" user all rights in the "lams" database. If you are not familar with MySQL we suggest that you use a a GUI database manager such as MySQL Administrator utility (comes with MySQL 5 on Windows).

To create the database using "MySQL Administrator":
Step 1: Select "Catalogs" and click on mysql. Right mouse click to bring up the popup menu and select "Create New Schema". Enter "lams" as the name of the new schema.

If you use a different database name (other than 'lams'), you will also need to update the file lams_common\db\sql\create_lams_11_db.sql - 'lams' is hardcoded in this file. This script is called when you run the ant target 'rebuild-db'.

Step 2: Select "User Administration" and click on "root". Right mouse click to bring up the popup menu and select "Add new User". Fill in the MySQL User, Password and Confirm Password fields then switch to the privileges tab and assign all available privileges to the user for the lams database.

You will also want to change the "lams" password in the project source to match whatever you have entered as the "lams" user's password. This needs to be changed in two places:

1. lams_build/conf/[windows or unix]/jboss/service/mysql-ds.xml (look for the <password> entry - 3 entries for each of the 3 data sources)
2. lams_build/common.properties (look for the db.password entry)

For people doing development only (i.e. trying to do more than build and run LAMS):

• If you intend to run the junit tests then change lams_common/src/java/org/lamsfoundation/lams/localApplicationContext.xml (look for the password property).
• There may also be the odd entry in a Hibernate configuration file, which will need to be changed if you use the Hibernate tools.
  If you are an experienced MySQL user and you wish to create the database and user from the MySQL command line utility, then this code should work. The code is copied from lams_common\db\sql\create_lams_11_db.sql. It only allows the lams user to connect to mysql from the computer where MySQL is running. If you want to access the database directly from another machine then please see the commented out code in lams_common\db\sql\create_lams_11_db.sql or read the MySQL documentation on user administration.
  mysql> SET FOREIGN_KEY_CHECKS=0; mysql> DROP DATABASE IF EXISTS lams; mysql> CREATE DATABASE lams DEFAULT CHARACTER SET utf8; mysql> SET FOREIGN_KEY_CHECKS=1; mysql> GRANT ALL PRIVILEGES ON *.* TO lams@localhost IDENTIFIED BY 'lamsdemo'; mysql> REVOKE PROCESS,SUPER ON *.* from lams@localhost;

Build

Using Command Line Ant 

Then in lams_build project, run the following ant tasks:

• Run "rebuild-db
• Run "assemble-ear"
• Run "deploy-ear"
• Run "deploy-tools"
• Run "copyfiles"

Using Eclipse 3.2

If you are using Eclipse, then you need to make sure you have the code loaded in Eclipse.

If you are using the zip file above, or checked out Eclipse using another cvs client then you will need to get the projects set up right in Eclipse. If you checked out using Eclipse then you can go on to the next step. Copy all the project folders that you got out of CVS / from the zip file to your Eclipse workspace directory. Then go to Eclipse and for each project folder, do File, New Project, select Java Project, click Next and enter the name of the project folder. Leave the options as given in this screenshot. Then click Finished. This should create the new project in Eclipse.

When all the projects are loaded, the screen should look something like the following, except that you won't have the lams_documents, lams_tool_deploy, lams_tool_example projects. You can close all projects except lams_build as this helps reduce the memory that Eclipse needs.

 
Then in lams_build project, select the build.xml file, right mouse click to get the popup menu and select "Run As", "Ant Build...". Its about 3/4 the way down the menu. Make sure you pick "Ant Build...", not "Ant Build".

A dialog box will appear. Uncheck the usage entry (this is the default) and turn on 

• "rebuild-db"
• "assemble-ear"
• "deploy-ear"
• "deploy-tools"
• and "copyfiles" IN THAT ORDER. The order is really really important. Then click Run.

You don't have to do them all at once - you can just turn on one, run it, bring up the dialog box again and select the next one. But it must be done in the right order.

If you encounter a problem, you can rerun these tasks. Until you learn what each one does, you are probably best to start with "rebuild-db" and go through all 5 tasks again. "rebuild-db" will delete all the tables in the database so you don't need to do that manually. But the LAMS database must exist or "rebuild-db" will fail. If "rebuild-db" itself fails, it may have deleted the database, in which case you will need to "Database Setup" and set up the database again.

For people doing development only (i.e. trying to do more than build and run LAMS): The lams_common project has a task "insert-test-data". This is only used if you want to run the core projects' test cases. Do not use it for running the LAMS server.

Start JBOSS

Now that everything is deployed and the database is setup, you can now start JBOSS. Good luck!

Once JBOSS is running, you should be able to access LAMS as http:/<servername>/lams. If you are running locally on your PC, it will probably be http://localhost:8080/lams. Login in as username mmm (see Development User Organisations)

If you are having trouble accessing LAMS check http:/<servername>/ (e.g. http://localhost:8080/). This should display the main JBOSS page. If you don't get the JBOSS page then JBOSS hasn't started properly.

If JBOSS has started but LAMS doesn't seem to be working have a look at the <jboss directory>/server/default/log directory. There should be a server.log and a lams.log (along with some other logs). If there isn't a lams.log LAMS hasn't started at all. If there is a lams.log, then check it for errors.

If there isn't a lams.log check server.log. There should be an entry like "Init J2EE application: file:/D:/jboss-4.0.2/server/default/deploy/lams.ear/" when LAMS tries to start, and an entry like "Started J2EE application: file:/D:/jboss-4.0.2/server/default/deploy/lams.ear/" when LAMS has ready to run.

If you have some of the settings in LAMS Configuration table wrong, then you can change this file without rebuilding or restarting (in some instances) LAMS. Login as System Admin, go to System Administration page, select Edit Configuration Settings. Save your changes. All changes will be persisted to the database table. Note: If you rebuild the Database, this will undo changes made via System Administration.

For some tips on debugging and using the JBOSS hot deploy with Eclipse, see Debugging with JBOSS and Eclipse.

Having Problems? Still having problems to build?... Post your issues in this forum thread in the LAMS Community

Configuring the Chat Server

To use the chat tool, you will need to configure your own xmpp (jabber) server.  The server must support JEP-0045 Multi-User Chat protocol. 

At present, LAMS is only tested with Wildfire and Wildfire 2.6.2. (an older version) is the only version that seems to run without problems. Later versions require particular configurations so that they don't conflict with LAMS. See Installing Wildfire for LAMS for instructions the details on downloading Wildfire.

You must check/update the four Xmpp* entries in LAMS Configuration table. You will need to change XmppDomain and XmppConference to your own Jabber server. If you are running the Jabber server locally your settings will probably be

For Wildfire, leave XmppAdmin as "admin" and set the XmppPassword to the admin password you set up in Wildfire.

Make sure that the hostname in the Wildfire config and the LAMS Configuration table is exactly the same (and not an IP address).

In the History Settings under the Group Chat menu, set the option to 'Don't Show History'.

Rebuilding The Tools

If you have deployed the tools, then do rebuild-db and then try to deploy the tools again, you are likely to get errors due to the tool tables not being created. The tool deployment utility doesn't really support "reinstallation" of tools yet, so the db recreation bit that exists is a hack, and breaks if the lams_tool table is purged (which occurs when rebuild-db is run).

So if you do rebuild-db either delete all the tool tables (they start with tl_ or tool_) using your favourite DB manager or drop and recreate the database.

In addition, the parallel activities are created each time you you do "deploy tools". So if you do "deploy tools" twice without rebuilding the db, you will end up with two copies of the parallel activities in authoring. This will not break anything but it does look a bit odd!

Creating Your Own Users and Courses

There are a number of test users (test1, test2 and test3) and their passwords are the same as their username. They have access to authoring, starting lessons and participating in lessons in a test organisation Developers Playpen.

To create your own users/organisations, login as sysadmin (password sysadmin). You can then access the administration screens to manage users and courses.

Other References

• LAMS installation and configuration on Win XP and Solaris by Daniel Schneider 06-Dec-2006

Still having problems?

• Please don't hesitate to ask questions in the Technical Forum at the LAMS Community