Installing Wonderland Web Administration

Summary

The web-based administration features of Project Wonderland make it easy to deploy clients, as well as to build and modify the world. The administration consists of three separate applications, combined into a single .war file for easy deployment to standard web containers. The applications are:

• Java Web Start client. Launch the Project Wonderland client from a web browser. With Java Web Start, users simply click on a link in their browser to automatically download and launch the latest version of the Project Wonderland client. Web Start takes care of downloading the client binaries, launching the application, and features extensive caching so clients stay up-to-date without excessive downloads.

• Wonderland World Builder. The world builder is a simple, web-based user interface to let users quickly build worlds for use in wonderland. Several different styles of artwork are provided, so administrators can quickly and easily build spaces to add to their Wonderland worlds.

• Wonderland Art Upload. Upload artwork to the Wonderland server from within the Wonderland client. This lets users easily add new content to a Wonderland world.

Getting Started

To run Wonderland web administration, you will need:

• Wonderland server. You can download the latest server from the binary builds page. If you are building Wonderland from source, see Appendix A. Building combined Wonderland.war.

• Web Container. You will also need a web container that supports Java servlets. We have tested with a number of different containers, as listed in the appendices: Jetty, Glassfish, and Tomcat. Wonderland web admin uses standard servlet technology, so should work in most web containers.

Installing Web Administration

1. Download Wonderland.war

You can get the Wonderland.war file from here: https://lg3d-wonderland.dev.java.net/binary-builds.html. There are two different .war files, a smaller one that uses artwork from the default Wonderland servers, and a larger one that includes artwork. If you plan to install Wonderland on an intranet behind a firewall or web proxy, including local artwork will make it easier for clients to run Wonderland.

2. Install the .war file in your web container

This step is done differently on each web container. See the following appendices for information on how to install in:

• Jetty
• Glassfish
• Tomcat

3. Configure your Wonderland server for web administration.

In your Wonderland server install directory, open the my.run.properties file and add two properties:

• wonderland.wfs.root this property describes where the WFS root is. By default, Wonderland web administration assumes the WFS root is in the user's home directory, in the .wonderland/wonderland-wfs directory. The property should be in the form of a file: URL, for example on Unix:

  file:/home/jkaplan/.wonderland/wonderland-wfs

  or on Windows:

  file:C:/Documents and Settings/jkaplan/.wonderland/wonderland-wfs

• wonderland.art.url.base this property sets where Wonderland finds its artwork. For Wonderland art upload, set the art URL to:

  http://your.server.name:8080/Wonderland/art

  Replace your.server.name with the fully qualified domain name of your server. Do this no matter whether you have downloaded the Wonderland.war with local artwork or not. If you have not downloaded the artwork locally, the Wonderland art upload server will first check if the request artwork has been uploaded, and if not it will forward to the default Wonderland server.

For example, on my system I have the following settings:

wonderland.wfs.root=file:/home/jkaplan/.wonderland/wonderland-wfs
wonderland.art.url.base=http://dstar3.East.Sun.COM:8080/Wonderland/art

All these settings match the default settings within the Wonderland.war web application. You can also change the default settings in the Wonderland.war file, as detailed in Appendix E. Configuring Wonderland.war.

4. Copy WFS files (optional).

If you would like the default Wonderland world, copy the contents from one of the worlds in the worlds/ subdirectory of your Wonderland installation directory. For example I copied the contents of lg3d-wonderland/worlds/default-wfs into the .wonderland/wonderland-wfs directory in my home directory:

cd /home/jkaplan/.wonderland/wonderland-wfs
cp -R /opt/lg3d-wonderland/worlds/default-wfs/* .

5. Start Wonderland Server as usual.

6. Connect your browser.

Go to http://your.server.name:8080/Wonderland to see the main Wonderland launch page. Click on the "Launch Wonderland Client" button to start the client via Java Web Start.

Appendix A. Building combined Wonderland.war

If you build Wonderland from source, you can build your own copy of the Wonderland.war used by Wonderland web admin. To start out, you will need a building version of the lg3d-wonderland and wonderland-modules workspaces, as described here: http://wiki.java.net/bin/view/Javadesktop/DownloadAndBuildSource.

Creating a keystore

Java Web Start requires all resources to be signed with a public/private key pair. The Wonderland workspace can do this automatically, but it needs to know which keystore and key to use for signing. If you have a signing key for other Java applications, you should be able to use that. If not, you can create a self-signed certificate to use. If you use a self-signed certificate, Java Web Start will warn users that the key may not be trustworthy.

Wonderland uses standard Java tools, keytool and jarsigner, to make and using keys and keystores. Wonderland assumes you already have a keystore, and are able to supply the following information:

• keystore - the location of a Java keystore file.
• alias - the name of the key in the keystore
• password - the password to access the keystore

By default we use the following values:

wonderland.keystore=${build-webstart.dir}/wonderlandKeystore.jks
wonderland.keystore.alias=wonderlandSig
wonderland.keystore.password=wonderland

These values can be overridden by writing new values into the lg3d-wonderland/my.build.properties file.

To generate the default keystore, go to a terminal, and change to the lg3d-wonderland/build-tools/webstart directory. Enter the following command to create a keystore with the wonderlandSig key.

#  keytool -genkey -keystore wonderlandKeystore.jks -alias wonderlandSig

You will be prompted for a bunch of information, which you should fill in as appropriate for your organization:

Enter keystore password:  wonderland
What is your first and last name?
  [Unknown]:  Project Wonderland
What is the name of your organizational unit?
  [Unknown]:  Sun Labs
What is the name of your organization?
  [Unknown]:  Sun Microsystems
What is the name of your City or Locality?
  [Unknown]:  Burlington
What is the name of your State or Province?
  [Unknown]:  MA
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=Project Wonderland, OU=Sun Labs, O=Sun Microsystems, L=Burlington, ST=MA, C=US correct?
  [no]:  yes

Enter key password for <wonderlandSig>
        (RETURN if same as keystore password): [return] 

Build Wonderland.war

The next step is to build the .war file with the following command:

# ant pkg-war-combined

This will create a file called lg3d-wonderland/release/platform/debug/combined/Wonderland.war. Whenever any part of Wonderland, or a Wonderland module, changes, you will need to re-run "ant pkg-war-combined" to update the web admin files and then re-deploy the .war file.

(Generally, you need to increase the size of your Java VM heap space before running the pkg-war-combined target. The easiest way to do this is set an environment variable ANT_OPTS to -Xmx1g before running ant.)

Include artwork

If you would like to include artwork in the Wonderland.war file, check out the lg3d-wonderland-art workspace as described here: http://wiki.java.net/bin/view/Javadesktop/DownloadAndBuildSource. The build the combined Wonderland.war file with the following command:

# ant -Dwonderland.useLocalArt=true pkg-war-combined

This will include all Wonderland artwork in the .war file

Appendix B. Installing in the Jetty web container

Jetty is an easy-to-use web container. To install in Jetty, simply do the following:

1. Download the latest version of Jetty from http://www.mortbay.org/
2. Unzip the Jetty archive and put the Wonderland.war file in the Jetty "webapps" directory
3. Start the server (from the Jetty directory): java -jar start.jar

If you use Java 1.6 as your server, you may see an error like the following:

java.lang.LinkageError: JAXB 2.0 API is being loaded from the bootstrap classloader, 
but this RI (from jar:file:/tm/Jetty_0_0_0_0_8080_WonderlandWorldBuilder.war__
WonderlandWorldBuilder__-ol5e17/webapp/WEB-INF/lib/jaxb-impl.jar!
/com/sun/xml/bind/v2/model/impl/ModelBuilder.class) needs 2.1 API. Use the 
endorsed directory mechanism to place jaxb-api.jar in the bootstrap classloader.

To fix this problem, create a directory called "endorsed" in the jetty directory, and extract the following files from Wonderland.war into it:

# cd jetty-6.1.8
# mkdir endorsed
# cd endorsed
# jar xvf ../webapps/Wonderland.war WEB-INF/lib/activation.jar WEB-INF/lib/jaxb-api.jar WEB-INF/lib/jaxb-impl.jar WEB-INF/lib/jaxb-xjc.jar WEB-INF/lib/jsr173_api.jar

Start Jetty using the following command:

# cd jetty-6.18
# java -Djava.endorsed.dirs=./endorsed -jar start.jar

Appendix C. Installing in the Glassfish web container

Glassfish is a fully-featured, open source web container. You can download it from http://glassfish.dev.java.net/ .

To install on Glassfish, simply deploy the Wonderland.war file using the Glassfish web administration console or using the command line:

# cd glassfish
(If it's not already running, start the glassfish server: # asadmin start-domain domain1)
# ./bin/asadmin deploy /Users/jkaplan/Desktop/Wonderland.war

Appendix D. Installing in the Tomcat web container

To install in Tomcat 5.5 or 6.0, do the following:

1. Copy the Wonderland.war file to tomcat´s "webapps" directory;
2. Start tomcat;
3. Remove the file WEB-INF\lib\jsp-api-2.0-20040521.jar from the Wonderland app directory created in tomcat´s "webapps" directory. Alternatively, you can remove this file from the Wonderland.jar file using a zip tool before copying it into the "webapps" directory;
4. Restart the server.

If you use Java 1.6, check the host log file (normally it´s named localhost.<date>.log) in the tomcat´s log directory and see if this message appears:

java.lang.LinkageError: JAXB 2.0 API is being loaded from the bootstrap classloader, 
but this RI (from jar:file:/tm/Jetty_0_0_0_0_8080_WonderlandWorldBuilder.war__
WonderlandWorldBuilder__-ol5e17/webapp/WEB-INF/lib/jaxb-impl.jar!
/com/sun/xml/bind/v2/model/impl/ModelBuilder.class) needs 2.1 API. Use the 
endorsed directory mechanism to place jaxb-api.jar in the bootstrap classloader.

This can cause an error in the Save World operation of the worldbuilder tool, showing in the browser a message like "failed to save world" and aborting the saving operation.

To fix this problem, extract the following files from Wonderland.war into the tomcat´s endorsed directory:

WEB-INF/lib/jaxb-api.jar 
WEB-INF/lib/jaxb-impl.jar

The tomcat´s endorsed directory is <TOMCAT_HOME>/endorsed in Tomcat 6.x (it´s doesn´t exists as default so you´ll need to create it) or <TOMCAT_HOME>/common/endorsed in Tomcat 5.5.

Restart the tomcat and everything should be ok then.

Appendinx E. Configuring Wonderland.war

Default values used in Wonderland web administration can be configured to use different default values. The typical way to do this is to open the Wonderland.war file and change the values of the various context parameters in the WEB-INF/web.xml file. The NetBeans (Web & Java EE) IDE will automatically let you open and repackage the .war file. To do this, select "File->New Project->Enterprise->Packaged Archive".

Alternatively, some web containers make it easy to set Java system properties. All properties can also be set using Java system properties (Java system properties will override values specified in the web.xml file). For example, when you start Jetty, you can use a command like the following to set Java system properties:

# java -Dsgs.server=my.host.com -jar start.jar

One more alternative: the jar command will let you extract and recompress war archives.

# jar xvf ../Wonderland.war
# jar uvf ../Wonderland.war .

The following properties can be modified: