Installation Procedure

Prerequisite

Before reading further make sure:

• That you have downloaded the latest Jigsaw distribution (version 1.0beta2 or 2.0beta1)
• That you have downloaded any implementation of Java for your platform (Jigsaw 1.0beta2 and up will compile and run only with a 1.1 JDK)
• If you're using the zip distribution, make sure it's  at least version 6.x

This document describes how to install Jigsaw. As an example, we are assuming that you are running either on Windows (be it 95 or NT) or on UNIX, even though Jigsaw will (should ?) run on any platform that supports Java.

The installation process involves the following steps:

• Unpack the distribution file
• Set up some environment variables
• Run Jigsaw

Note on upgrading (skip if not upgrading)

The upgrade may require two steps if you are upgrading from a version earlier than alpha5. If it is not the case, read the following section, otherwise, go to the Alpha4 to Alpha5 part before upgrading to beta.

Please note that there are no upgrade from 1.0beta to 2.0alpha.

Upgrade from 1.0alpha5 to 1.0beta

Once again, an automatic upgrade from your old version of Jigsaw has been provided. During the upgrade process, Jigsaw will give you information about this upgrade process. Be sure to have the upgrade package needed for this operation, upgrade.zip for Windows, upgrade.tar.gz for UNIX. Those packages are in the Jigsaw/upgrade directory.

It is strongly recommended to keep a backup of your current configuration. Backup'ing the configuration can be done using any tools, if INSTDIR is the place where you installed the previous release of Jigsaw:

Backuping the config 

UNIX	cd INSTDIR; tar cvf - config > config.tar
Windows	cd INSTDIR; zip -r config.zip config

If you use the following instructions, you can re-install using:

Restoring a backed up configuration 

UNIX	cd INSTDIR; tar xomvf - config.tar
Windows	cd INSTDIR; unzip config.zip

Now, you must install the new configuration files in your configuration directory, taken from the update zip.

Installing the new configuration files 

UNIX	cd INSTDIR/Jigsaw/Jigsaw/config; gzip -c -d upgrade.tar.gz | tar xomvf -
Windows	cd INSTDIR/Jigsaw/Jigsaw/config; unzip upgrade.zip

Be careful, if you have already an "admin" realm for your Authentification, be sure to put back the backuped version. This realm is used by the administration server.

To complete the upgrade of Jigsaw, you only have to start jigsaw (w3c.jigsaw.Main). During this last step, Jigsaw will emit traces of what happened, the result will be stored in INSTDIR/Jigsaw/Jigsaw/config/upgrade2to3.txt. Check this file for errors.

Upgrade from 1.0alpha4 to 1.0alpha5

For those of you who have already installed a previous release of Jigsaw, you should be aware that since version 1.0alpha4, Jigsaw has a facility for automatically upgrading your configuration files. You will note that the first time you run a newer release of Jigsaw, it will tell you about that upgrading process, and how it goes.

Note: for the upgrade process to happen, it is mandatory that you run Jigsaw the old way, through the w3c.jigsaw.http.httpd class. Once the upgrade is done, you can safely start using the modern command line (ie the w3c.jigsaw.Main). That's a bug !

It is recommended that you keep a backup of the previous configuration, by packing all the config directory in an archive file. Backup'ing the configuration can be done using any tools, if INSTDIR is the place where you installed the previous release of Jigsaw:

Backuping the config 

UNIX	cd INSTDIR; tar cvf - config > config.tar
Windows	cd INSTDIR; zip -r config.zip config

If you use the following instructions, you can re-install using:

Restoring a backed up configuration 

UNIX	cd INSTDIR; tar xomvf - config.tar
Windows	cd INSTDIR; unzip config.zip

Last but not least, once your configuration has been upgraded, you may want :

• To copy the Jigsaw/Jigsaw/WWW/Admin directory into your (empty ?) Admin directory, the Overview.html document available there provides a nice frame based toolbar.
• To install a w3c.jigsaw.contrib.SalvagerResource and a w3c.jigsaw.contrib.CheckpointResource in your /Admin directory

Unpacking the distribution file

Pick a place to unpack the distribution: we'll call this directory the installation directory (abreviated as  INSTDIR). This can be any directory, you just have to change your current working directory to it:

UNIX	cd INSTDIR
Windows	cd INSTDIR

Now unpack the file:

UNIX	cat jigsaw.tar.gz | gzip -d | tar xomvf -
Windows	unzip jigsaw.zip

This will create a number of directories under the Jigsaw directory:

Jigsaw/src

Contains Jigsaw sources.

Jigsaw/classes

Contains the pre-compiled classes.

Jigsaw/lib

Contains some native code support for solaris.

Jigsaw/Jigsaw

Is a sample root directory to run the server in. This directory in turns contain the following sub-directories:

Jigsaw/Jigsaw/config

Is the configuration directory for the server

Jigsaw/Jigsaw/configadm

Is the configuration directory for the administration server.

Jigsaw/Jigsaw/logs

Is the normal directory for log files

Jigsaw/Jigsaw/bin

Contains some shell scripts to help you start Jigsaw.

Jigsaw/Jigsaw/cache

The directory to use for caching when using Jigsaw as a caching proxy.

Jigsaw/Jigsaw/WWW

Is your exported file space

You are now ready for the next section, which explains how to setup your environment.

Setting up your environment

As Jigsaw is just a set of Java classes, you need to specify to the Java interpreter the place where Jigsaw classes are stored. This is usually done by setting some CLASSPATH environment variable. This is simply done by the following command:

UNIX	# This depends on the shell you are using, we're assuming /bin/sh CLASSPATH=INSTDIR/Jigsaw/classes/jigsaw.zip export CLASSPATH
Windows	set CLASSPATH=INSTDIR\Jigsaw\classes\jigsaw.zip

Don't forget to change INSTDIR with the absolute path of the place you have unpacked the distribution.     You should now be ready to run Jigsaw.

Warning: on some Windows Java implementation, prefixing the CLASSPATH with the disk drive letter may cause some confusion. If java complains about not being able to find some class, you may want to remove the disk drive letter from the CLASSPATH. Note also that if you are adding this line in a batch file, you must escape the '\' the line will be: set CLASSPATH=INSTDIR\\Jigsaw\\classes\\jigsaw.zip

Running Jigsaw

If you are using Jigsaw 2.0 and above, you can automatically setup the right values in the configuration file by typing 'java Install' in the INSTDIR/Jigsaw/Jigsaw directory.

You are now all set to run Jigsaw. Just type in the following command (for 2.0 and up):

UNIX	cd INSTDIR/Jigsaw/Jigsaw java org.w3c.jigsaw.Main -host host -root INSTDIR/Jigsaw/Jigsaw
Windows	cd INSTDIR\Jigsaw\Jigsaw java org.w3c.jigsaw.Main -host host -root INSTDIR\Jigsaw\Jigsaw

For Jigsaw 1.0:

UNIX	cd INSTDIR/Jigsaw/Jigsaw java w3c.jigsaw.Main -host host -root INSTDIR/Jigsaw/Jigsaw
Windows	cd INSTDIR\Jigsaw\Jigsaw java w3c.jigsaw.Main -host host -root INSTDIR\Jigsaw\Jigsaw

Don't forget to susbstitute to INSTDIR the absolute path of the location where you have unpacked the distribution file, and to host the full IP hostname of the machine running Jigsaw.

Jigsaw should be running, and will probably have emited a message like:

jigsaw Sample/Jigsaw> java org.w3c.jigsaw.Main
loading properties from: /auto/tarantula/u/tarantula/0/w3c/ylafon/Sample/Jigsaw/config/server.props
Jigsaw[2.0beta1]: serving at http://jigsaw.inria.fr:8007/
*** Warning : no logger specified, not logging.
JigAdmin[2.0beta1]: serving at http://jigsaw.inria.fr:8009/

Or:

www24:Jigsaw$ bin/jigsaw -root `pwd` 
 loading properties from: /0/w3c/abaird/puzzles/JigEdit/config/server.props
 Jigsaw[1.0beta]: serving at http://www43.inria.fr:8009/

Indicating that it is waiting to meet your browser at the given URL.

Further reading

At this point, it is recommended that you start reading the documentation, available from your server at /Doc (i.e. in the above example, the full URL would be http://www24.w3.org:8001/Doc/ For the 1.0 version the documentation is under /User

Here is a roadmap to the documentation:

• You should first start by reading the architecture overview. More on the Jigsaw 2.0 design
• You should then configure your server to meet your need. There are two sources of documentation for this stage:
  • The administration guide
  • The configuration tutorial and the old one.
  • The Jigsaw aministration tool.
• At this point, you should have understood the configuration process, you can now browse the rest of the documentation in whatever order you want.