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 Password: [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 http://download.java.net/lg3d/wonderland/release+voice/2008-0_4_0/wonderland-0-4-0-solaris-i86pc.zip 13:58:56 (256.45 KB/s) - `wonderland-0-4-0-solaris-i86pc.zip' saved [145402562/145402562]
Next I download the MiRTLE.war file from the wonderland-incubator web site (and rename it):
[opensolaris mirtle]$ wget "https://wonderland-incubator.dev.java.net/source/browse/*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 "https://wonderland-incubator.dev.java.net/files/documents/7166/132565/mirtle-wfs.zip" 14:18:57 (65.56 KB/s) - `mirtle-wfs.zip' saved [23269/23269]
Next I download the zipped files that provide the MiRTLE shared applications:
[opensolaris mirtle]$ wget "https://wonderland-incubator.dev.java.net/files/documents/7166/132699/MiRTLE-sharedApps.zip" 14:20:09 (234.06 KB/s) - `MiRTLE-sharedApps.zip' saved [2752564/2752564]
Finally, I downloaded the Glassfish application server, which I will use to host the web administration:
[opensolaris mirtle]$ wget http://java.net/download/javaee5/v2ur2/promoted/SunOS_X86/glassfish-installer-v2ur2-b04-sunos_x86.jar 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 MiRTLE-sharedApps.zip -rw-r--r-- 1 bh37721 staff 23269 2009-04-17 17:44 mirtle-wfs.zip -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 wonderland-0-4-0-solaris-i86pc.zip
Install the Wonderland server
Next step is to set up the Wonderland server. First I unzip it:
[opensolaris mirtle]$ unzip wonderland-0-4-0-solaris-i86pc.zip Archive: wonderland-0-4-0-solaris-i86pc.zip 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 MiRTLE-sharedApps.zip Archive: MiRTLE-sharedApps.zip 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 "https://wonderland-incubator.dev.java.net/source/browse/*checkout*/wonderland-incubator/MiRTLE/audio/mirtle/MiRTLEoverview.au?rev=HEAD" 15:04:21 (200.26 KB/s) - `MiRTLEoverview.au?rev=HEAD' saved [61034424] [opensolaris mirtle]$ mv MiRTLEoverview.au?rev=HEAD MiRTLEoverview.au
The next step is to unzip the MiRTLE WFS files:
[opensolaris mirtle] cd ../../.. [opensolaris mirtle]$ unzip mirtle-wfs.zip Archive: mirtle-wfs.zip creating: mirtle-wfs/ ...
The next step is to edit the my.run.properties files with the right values for my server:
[opensolaris mirtle]$ cd lg3d-wonderland [opensolaris lg3d-wonderland]$ vi my.run.properties ... # # 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. # wonderland.local.hostAddress=192.168.254.12 wonderland.wfs.root=file:/export/home/wonderland/mirtle/mirtle-wfs wonderland.art.url.base=http://192.168.254.12:8080/MiRTLE/art
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/wonderland-all.sh #!/bin/bash echo "Starting Voice Bridge" ./bin/wonderland-bridge.sh > wonderland-bridge.log 2>&1 & sleep 15 echo "Starting Wonderland Server" ./bin/wonderland-server.sh > wonderland-server.log 2>&1 & sleep 15 echo "Starting Server Master Client" ./bin/wonderland-smc.sh > 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/wonderland-all.sh [opensolaris lg3d-wonderland]$ ./bin/wonderland-all.sh 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 wonderland-server.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 ... BUILD SUCCESSFUL 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
http://192.168.254.12:8080/MiRTLE
And I should get the MiRTLE launch page:
Take a look at our original video to see how MiRTLE is being used.
