How to set up a shared Wonderland server

This week we’ve been doing final testing before our Wonderland 0.4 release (the last few bugs are always the hardest).  To test the binary releases, I’ve been setting up the Wonderland server every day for our group.  I feel like I have a decent recipe going, which I thought I’d share with anyone else out there who wants to set up a Wonderland server.

What you need

The goal is to install the Wonderland server and web administration on my local Solaris server. (Note: the instructions for Linux should be identical, except using the Linux binaries instead of the Solaris ones). Once I do that, everyone on the team will be able to launch the client via Java Web Start.  No installation required!

If you’d like to try it yourself, you’ll need a Linux or Solaris server, a remote login to the server, and about 1GB of free disk space.

Download the software

I start out by logging in to my server (dstar3) and creating a directory to put the Wonderland code in.  Since this particular setup is for a demo, I’ll call the directory "demo":

[laptop ~]$ ssh
[dstar3 ~]$ su
[dstar3 ~]# mkdir -p /export/home/wonderland/demo
[dstar3 ~]# chown -R jkaplan /export/home/wonderland
[dstar3 ~]# exit
[dstar3 ~]$ cd /export/home/wonderland/demo

 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 Wonderland, and do the installation as that user.  In either case, you can install in any directory you have write permissions to.  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 done as root with a call to "sudo", for example: "sudo mkdir -p …").

Next, I download the three pieces of software I will need.  First, I get the latest nightly build of the Wonderland server for Solaris:

[dstar3 demo]$ wget
13:08:16 (419.82 KB/s) - `' saved [145567905/145567905]

Note that these directions assume a very recent build, preferably 20080730 or later.

Next I download the Wonderland.war file for web administration:

[dstar3 demo]$ wget
13:16:40 (411.92 KB/s) - `Wonderland.war' saved [202958941/202958941]

I chose the bigger one (with local artwork) so I can be sure everyone will get the same art:

Download Wonderland

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

[dstar3 demo]$ wget

Now I have all the pieces I need:

[dstar3 demo]$ ls -l
-rw-r--r--   1 wonderland other    202974858 Jul 30 13:52 Wonderland.war
-rw-r--r--   1 wonderland other    64375686 Apr 11 23:10 glassfish-installer-v2ur2-b04-sunos_x86.jar
-rw-r--r--   1 wonderland other    145567905 Jul 30 04:54

Install the Wonderland server

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

[dstar3 demo]$ unzip
creating: lg3d-wonderland/

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

[dstar3 demo]$ cd lg3d-wonderland
[dstar3 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.
  • wfs.root – the location of wfs files to load in this world. The demo world is a cleaned up version of the MPK20 space, with content like PDFs loaded off the internet. It also has two additional spaces: a lecture hall with PDF and video and a playground for the world builder. You can change the settings for this world by editing the wfs file in the demo-wfs directory.
  • art.url.base  – where the clients will download artwork from.  In this setup, clients download the artwork from the deployed Wonderland.war file.  This enables advanced features like art upload.

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

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

[dstar3 lg3d-wonderland]$ chmod +x ./bin/
[dstar3 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:

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

Configure Wonderland.war

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 the latest version of Wonderland. To do this, I need to deploy Wonderland.war to a web container. Before I do that, though, I want to make a few quick changes to the .war file to configure it the way I want.

To make changes to the .war, I am going to uncompress the config files I want to change, modify them, and then update the war with the new file. The three things I want to change are to change the location of the WFS files to match the value I setup in the server above, to add new default placemarks for the lecture hall and world builder area, and also to enable developer features so users can reload the world after we make changes with the world builder.

First, I unpack the files we want to change from the war file I downloaded into a temporary directory:

[dstar3 lg3d-wonderland]$ cd ..
[dstar3 demo]$ mkdir war
[dstar3 demo]$ cd war
[dstar3 war]$ jar xvf ../Wonderland.war WEB-INF/web.xml app/config-webstart/PlacemarkConfig.xml app/Wonderland.jnlp
inflated: WEB-INF/web.xml
inflated: app/Wonderland.jnlp
inflated: app/config-webstart/PlacemarkConfig.xml

Then I edit the web.xml file to put in a WFS path that matches the one I put in to the  file: 

[dstar3 war]$ vi WEB-INF/web.xml

Now I copy over the placemarks file with the placemarks for the default world.  If you want to change placemarks the user will see, this is the time to do it.  Just edit that PlacemarkConfig.xml file after you copy it:

[dstar3 war]$ cp ../lg3d-wonderland/worlds/demo-wfs/PlacemarkConfig.xml app/config-webstart/

Next I edit the Wonderland.jnlp file to enable developer features:

[dstar3 war]$ vi app/Wonderland.jnlp
<property name="sun.java2d.noddraw" value="true"/>
<property name="wonderland.experimentalfeatures" value="false"/>
<property name="wonderland.developerfeatures" value="true"/>

Then I can update the war file with the updated configuration files:

[dstar3 war]$ jar uvf ../Wonderland.war .
adding: app/(in = 0) (out= 0)(stored 0%)
adding: app/config-webstart/(in = 0) (out= 0)(stored 0%)
adding: app/Wonderland.jnlp(in = 4223) (out= 1157)(deflated 72%)
adding: app/config-webstart/PlacemarkConfig.xml(in = 3118) (out= 501)(deflated 83%)

And finally clean up my temporary directory:

[jkaplan@dstar3 war]$ cd ..
[jkaplan@dstar3 demo]$ rm -rf war

There are lots more things you can configure in Wonderland.war, like the directories it uses to store artwork and WFS. To see a full list, see the web administration docs.

Install Wonderland Web Admin in Glassfish

Finally, I need to deploy the newly configured Wonderland.war file 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:

[dstar3 demo]$ 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:

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

Now I start up Glassfish:

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

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

[dstar3 glassfish]$ ./bin/asadmin deploy ../Wonderland.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:

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

Running the Wonderland Client

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

And I should get the Wonderland launch page:

Wonderland front page

Now that it’s up, what can I do with this demo?  Check out our latest video to see some of the cool new features in Wonderland 0.4!

(Updated 8/2 to remove bad characters )


7 Responses to How to set up a shared Wonderland server

  1. Mikael Gueck says:

    Non-UTF8 characters in this blog post seem to be breaking the RSS/Atom feeds.

  2. James Council says:

    Thank you for the procedure. I am up and running in just a few minutes.
    One question. How is the id/pw handled? I have tried local ids and pws from the solaris server that I set it up on with no luck.
    Your thoughts.

  3. Jonathan Kaplan says:

    James, glad to hear it’s working! By default, Wonderland doesn’t use authentication — you can use any unique username, and the password isn’t checked. This wiki page describes how to set up different authentication types (file or LDAP):

  4. Robert Lancashire says:

    I have still not completely managed to get it running properly on a solaris sparc server since the instructions here appear to be for solaris on PC. The client messages show only that the username and password do not work.
    The logs on the server provide some details to try to fix the platform issues.
    The smc is not working and I wonder where I am to configure to get Xvfb executed.
    Will keep searching for clues but this was certainly a great help in getting started.

  5. Mark says:

    [java] WARNING: Couldn’t start listener
    [java] /.wonderland-smc/.localControl. (No such file or directory)
    [java] at Method)
    [java] at<init>(
    [java] at<init>(
    [java] at<init>(
    [java] at org.jdesktop.lg3d.wonderland.LocalControl$LocalControlListener.<init>(
    [java] at org.jdesktop.lg3d.wonderland.LocalControl.startListener(
    [java] at org.jdesktop.lg3d.wonderland.Main.setupLocalControl(
    [java] at org.jdesktop.lg3d.wonderland.Main.main(
    [java] ******* Forcing voicebridge.enabled to false
    wonderland-smc not able to start. what do i do?

  6. Hi Jon:
    Great HOWTO. Found a typo though: There should be line break after setup.xml and before Buildfile in the following line:
    ./lib/ant/bin/ant -f setup.xml Buildfile: setup.xml

  7. Courtney says:

    I managed to install everything sucessfully, thanks.
    Got a problem though, once the jnlp file is downloaded and ran the default port used is 1139 it says connecting after i click log in but nothing else and it stays like that.
    Not sure if it has anything to do with it but i set all the settings to use but in the log in it has, even if i change the domain to it still only says connecting and never connects.
    Tried changing port to a random one which i know isn;t opened and it returns an error if i use 8080 it gets login failed.
    Any ideas on what i’ve done wrong?
    thanks in advance….

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: