How to set up a MiRTLE Server

One of the projects that we undertook last year was MiRTLE: it was a collaborative research project between Sun Labs and the University of Essex in the UK to develop a Mixed Reality Teaching & Learning Environment. We finished the project last autumn and I’ve been writing up a Sun Labs technical report–hopefully to be published in the near future.

One outcome of the project is that we’ve made available all the files necessary to host your own MiRTLE set up. In the instructions that follow, I assume that you’ve already taken a look at Jon’s excellent blog posting on setting up a Wonderland server on Solaris. The remainder of this blog posting is adapted from his earlier entry.

I start out by logging in to my OpenSolaris server (named ‘opensolaris’) and creating a directory to contain the Wonderland code. Since this particular setup is for MiRTLE, I’ll call the directory "mirtle":

[opensolaris ~]$ su
[opensolaris ~]# mkdir -p /export/home/wonderland/mirtle
[opensolaris ~]# chown -R bh37721 /export/home/wonderland/mirtle
[opensolaris ~]# exit
[opensolaris ~]$ cd /export/home/wonderland/mirtle

In this case, I’m creating a directory in /export/home, and changing it to be owned by my user. A better option would be to create a new user for MiRTLE, and perform the installation as that user. In either case, you can install in any directory for which you have write permissions. You’ll just need to update the paths for the WFS root in the instructions below.

(Linux note: most Linux distros don’t let you directly do "su". Instead, replace the command performed as root with a call to "sudo", for example: "sudo mkdir -p …").

Next, I download the pieces of software I will need.  First, I get the 0.4 release of the Wonderland server for Solaris:

[opensolaris mirtle]$ wget
13:58:56 (256.45 KB/s) - `' saved [145402562/145402562]

Next I download the MiRTLE.war file from the wonderland-incubator web site (and rename it):

[opensolaris mirtle]$  wget "*checkout*/wonderland-incubator/MiRTLE/MiRTLE.war?rev=HEAD"
14:14:13 (208.04 KB/s) - `MiRTLE.war?rev=HEAD' saved [163848730]
[opensolaris mirtle]$  mv MiRTLE.war\?rev\=HEAD MiRTLE.war

Next I download the zipped WFS files that provide the MiRTLE world from the same site:

[opensolaris mirtle]$ wget ""
14:18:57 (65.56 KB/s) - `' saved [23269/23269]

Next I download the zipped files that provide the MiRTLE shared applications:

[opensolaris mirtle]$ wget ""
14:20:09 (234.06 KB/s) - `' saved [2752564/2752564]

Finally, I downloaded the Glassfish application server, which I will use to host the web administration:

[opensolaris mirtle]$ wget
14:25:23 (257.37 KB/s) - `glassfish-installer-v2ur2-b04-sunos_x86.jar' saved [64375686/64375686]

Now I have all the pieces I need:

[opensolaris mirtle]$ ls -l
-rw-r--r-- 1 bh37721 staff  64375686 2008-04-12 04:10 glassfish-installer-v2ur2-b04-sunos_x86.jar
-rw-r--r-- 1 bh37721 staff   2752564 2009-04-20 09:10
-rw-r--r-- 1 bh37721 staff     23269 2009-04-17 17:44
-rw-r--r-- 1 bh37721 staff 163848730 2009-03-03 14:14 MiRTLE.war
-rw-r--r-- 1 bh37721 staff 145402562 2008-08-16 00:26

Install the Wonderland server

Next step is to set up the Wonderland server. First I unzip it:

[opensolaris mirtle]$ unzip
creating: lg3d-wonderland/

The next step is to include the MiRTLE shared applications. I unzip the additional MiRTLE files and copy them into the appropriate directories in the Wonderland server directories:

[opensolaris mirtle]$ unzip
creating: MiRTLE-sharedApps/
[opensolaris demo]$ cd MiRTLE-sharedApps
[opensolaris MiRTLE-sharedApps]$ cp -r apps-linux/ ../lg3d-wonderland/config/
[opensolaris MiRTLE-sharedApps]$ cp -r apps-solaris/ ../lg3d-wonderland/config/
[opensolaris MiRTLE-sharedApps]$ cp *.zip ../lg3d-wonderland/data/Wonderland/test/appshare/
[opensolaris MiRTLE-sharedApps]$ cp ffsetup ../lg3d-wonderland/bin

This setup relies on installations of FireFox and OpenOffice being in their "usual" places, i.e.

  • /usr/bin/firefox
  • /usr/bin/soffice

If their paths are different , then you’ll have to edit lg3d-wonderland/config/apps-solaris/apps-smc.xml.

I also download the MiRTLE overview audio file into the correct directory (and rename it):

[opensolaris MiRTLE-sharedApps]$  cd ../lg3d-wonderland/audio/
[opensolaris audio]$ mkdir mirtle
[opensolaris audio]$ cd mirtle
[opensolaris mirtle]$ wget "*checkout*/wonderland-incubator/MiRTLE/audio/mirtle/"
15:04:21 (200.26 KB/s) - `' saved [61034424]
[opensolaris mirtle]$ mv

The next step is to unzip the MiRTLE WFS files:

[opensolaris mirtle] cd ../../..
[opensolaris mirtle]$ unzip
creating: mirtle-wfs/

The next step is to edit the files with the right values for my server:

[opensolaris mirtle]$ cd lg3d-wonderland
[opensolaris lg3d-wonderland]$ vi
# Set the hostname to be used for outbound socket connections.
# Java finds it hard to figure this out automatically. This is used by the voice bridge
# and the X app sharing s/w for making outbound socket connections.

The values I change are:

  • local.hostaddress – the address of the Wonderland server, which is the same as the address of the web server in this case. I discovered this by using ifconfig -a. Alternatively, you can use a fully qualified host name.
  • wfs.root – the location of wfs files to load in this world. The MiRTLE world is a describes the contents of the class rooms, with content like PDFs loaded from the internet.
  • art.url.base – where the clients will download artwork from.In this setup, clients download the artwork from the deployed MiRTLE.war file.

The server is now configured! To make life easier, Jon wrote a little script to launch all the separate pieces of the server. I put this in the lg3d-wonderland/bin directory:

[opensolaris lg3d-wonderland]$ vi bin/
echo "Starting Voice Bridge"
./bin/ > wonderland-bridge.log 2>&1 &
sleep 15
echo "Starting Wonderland Server"
./bin/ > wonderland-server.log 2>&1 &
sleep 15
echo "Starting Server Master Client"
./bin/ > wonderland-smc.log 2>&1 &
echo "Wonderland started"

To run the server, I just need to make the script executable, and then run it. It will automatically put all the Wonderland server processes in the background:

[opensolaris lg3d-wonderland]$ chmod +x ./bin/
[opensolaris lg3d-wonderland]$ ./bin/
Starting Voice Bridge
Starting Wonderland Server
Starting Server Master Client
Wonderland started

Once the server is running, you can check the log files in the lg3d-wonderland directory if anything doesn’t work right:

[opensolaris lg3d-wonderland]$ ls *.log
wonderland-bridge.log  wonderland-smc.log

Install Wonderland Web Admin in Glassfish

Now that the server is all set, it’s time to turn to the client. I want to launch the client via Java Web Start, so users can just click on a link to run a client to MiRTLE. To do this, I need to deploy MiRTLE.war to a web container.  I’m going to use the Glassfish container I downloaded earlier, although you should be able to use Tomcat or Jetty if you prefer.

Installing Glassfish can be done in two easy steps. Step one is to unpack the distribution file:

[opensolaris mirtle]$ java -mx768M -jar glassfish-installer-v2ur2-b04-sunos_x86.jar
Accept or Decline? [A,D,a,d] A
installation complete

Step two is to run the setup script to configure Glassfish. The Glassfish site has great docs about all the settings you can change (like directories and port numbers) in the setup.xml file. Make these changes before running the next step. I just use the default, which will put the web server on port 8080:

[opensolaris mirtle]$ cd glassfish
[opensolaris glassfish]$ chmod -R +x lib/ant/bin
[opensolaris glassfish]$ ./lib/ant/bin/ant -f setup.xml
Buildfile: setup.xml
Total time: 31 seconds

Now I start up Glassfish:

[opensolaris glassfish]$ ./bin/asadmin start-domain
Starting Domain domain1, please wait.

And finally, I deploy the updated MiRTLE.war file:

[opensolaris glassfish]$ ./bin/asadmin deploy ../MiRTLE.war
Command deploy executed successfully.

Now the Wonderland client code is installed in the Glassfish server. If there are any problems, you can check the Glassfish server log:

[opensolaris glassfish]$ ls domains/domain1/logs/
jvm.log     server.log

Running the MiRTLE Client

OK, everything should be up and running at this point.  From my browser, I can go to

And I should get the MiRTLE launch page:

Setting up a MiRTLE Server

Take a look at our original video to see how MiRTLE is being used.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: