VRSpace requires Java as well as a web server to function. While any web server will work with VRSpace, these instructions will lead you through installing Jakarta Tomcat 4.1, a Servlet/JSP engine that has an embedded web server. Its additional Servlet functionality will prove useful for advanced VRSpace applications. If you do not have Java, we suggest installing the most recent version of the Sun JRE before continuing.
This tutorial assumes that the reader is installing on a Windows platform, but the directions will work with slight modifications for other platforms (For example, replace all instances of c:\ with /usr/ when installing on Linux). For future reference, the installation directories will be:
Go to the SourceForge homepage of VRSpace and download the most recent version of VRSpace (vrspace-0.9.4.zip or higher). Unzip this file into c:\ (this will result in c:\vrspace being the top level directory for the installation). Note that all the files for running the server are located in the directory bin, and the client directory contains the web application that the user sees through the http server.
Tomcat can be downloaded directly from the Jarkarta Project. Scroll down the page to get the most recent version of Tomcat 4.1 for your platform (e.g. Windows: 4.1.29.exe, Non-Windows: 4.1.29.tar.gz). If you downloaded the executable distribution of Tomcat, run it and choose c:\vrspace\tomcat as the installation directory. Otherwise, save jakarta-tomcat-4.1.??.tar.gz to c:\vrspace, then gunzip, and detar it. This will create a directory called c:\vrspace\jakarta-tomcat-4.1.??. Use the move command to rename this directory to c:\vrspace\tomcat.
Tomcat will need to know the directory in which Java is installed in order to run. To instruct it, we need to create the environment variable JAVA_HOME. In particular, we must set JAVA_HOME=java installation directory. To do this, first search through your directories to find your java home (the top level directory of the installation). As an example, with the Sun JRE version 1.4.1_03, the directory could be c:\j2sdk1.4.1_03. Once you have found this directory, open c:\autoexec.bat with your text editor. Find any old blank line in the file, and type
With the above example, the line would be: set JAVA_HOME=c:\j2sdk1.4.1_02. Save autoexec.bat (remember, as a plain text file).
Now we place the client application into a location where it can be accessed by visitors. This client application is located in the vrspace directory under c:\vrspace\client. Move the directory vrspace (i.e. c:\vrspace\client\vrspace) into the document root directory of Tomcat (or into the document root directory of your web server, if you are not going to use Tomcat).
The directory we just moved contains the html, java, js (javascript), jpg and wrl files that together compose the client web application. For example, Dolphin.wrl contains the default client avatar, console.wrl, cursor.wrl, wrench.wrl support the user interface, etc. The main html file here is vrspace.html which loads the client, but index.html is a nice informational page to get users there. There is also client.jar which contains all of the java classes for running the client.
Both the VRSpace server and the Tomcat servers must be running in order for VRSpace to work. To start Tomcat, either select Start->Programs->Apache Tomcat 4.1->start Tomcat, or use the command line:
To start the VRSpace server, go to the bin directory and type vrspace, or do it directly with Java
We can try out the client now that the servers are running. Open your VRML browser and point it to:
Clicking "Enter", you should find yourself floating above the planet Earth, being prompted for your user name and password (see the troubleshooting the VRSpace Client, if you do not see the login prompt).
There is only one user created by default: admin, and this user is an Administrator. Log in as admin, with the password admin. Your first task in VRSpace is to give admin a new password. Fortunately, the VRSpace client actually allows for many different commands to be issued at the console to alter your preferences and the world around you. To change the password, we alter the Auth(entification)Info(rmation) of admin. Type the following into the console:
To test out the change, logout:
hit the browser's reload button, and log back in as admin. Finish up by shutting down the server:
The shutdown command only stops the VRSpace server (not Tomcat). You don't have to shutdown the server using it, instead you can go to window where VRSpace is running and press Control-C. This method also works to stop Tomcat. Although, Tomcat can also be stopped using the stop Tomcat shortcut through the Start menu.