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 firstname.lastname@example.org [dstar3 ~]$ su Password: [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 http://download.java.net/lg3d/wonderland/daily+voice/2008-07-30/lg3d-wonderland+voice-0-4-0-daily-solaris-i86pc-20080730.zip 13:08:16 (419.82 KB/s) - `lg3d-wonderland+voice-0-4-0-daily-solaris-i86pc-20080730.zip' 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 http://download.java.net/lg3d/wonderland/daily+voice/2008-07-30/web+art/Wonderland.war 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:
Finally, I downloaded the Glassfish application server, which I will use to host the web administration:
[dstar3 demo]$ wget http://java.net/download/javaee5/v2ur2/promoted/SunOS_X86/glassfish-installer-v2ur2-b04-sunos_x86.jar
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 lg3d-wonderland+voice-0-4-0-daily-solaris-i86pc-20080730.zip
Install the Wonderland server
Next step is to set up the Wonderland server. First I unzip it:
[dstar3 demo]$ unzip lg3d-wonderland+voice-0-4-0-daily-solaris-i86pc-20080730.zip Archive: lg3d-wonderland+voice-0-4-0-daily-solaris-i86pc-20080730.zip creating: lg3d-wonderland/ ...
The next step is to edit the my.run.properties files with the right values for my server:
[dstar3 demo]$ cd lg3d-wonderland [dstar3 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=dstar3.east.sun.com wonderland.wfs.root=file:/export/home/wonderland/demo/lg3d-wonderland/worlds/demo-wfs wonderland.art.url.base=http://dstar3.east.sun.com:8080/Wonderland/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.
- 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/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:
[dstar3 lg3d-wonderland]$ chmod +x ./bin/wonderland-all.sh [dstar3 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:
[dstar3 lg3d-wonderland]$ ls *.log wonderland-bridge.log wonderland-smc.log wonderland-server.log
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 my.run.properties file:
[dstar3 war]$ vi WEB-INF/web.xml <context-param> <param-name>wonderland.wfs.root</param-name> <param-value>file:/export/home/wonderland/demo/lg3d-wonderland/worlds/demo/wonderland-wfs</param-value> </context-param>
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 ... BUILD SUCCESSFUL 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:
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 )