Backing up client settings

There is currently an update being tested that stores this information in a database, generally negating the need to perform this operation, but this update is not yet generally available.

Anything the user can save (bookmarks, redlines, etc) will be stored under the Weave installation directory, so they should be exported before the current Weave instance is decommissioned or upgraded.

This must be done from the osgi command prompt using the ustorage command. The ustorage command can save the current user settings to an external file using the following format

osgi> ustorage save <filename>

and reload the content in the new instance with the ustorage load command

osgi> ustorage load <filename>

You should specify a fully qualified file name as the last parameter in both commands to make it easy for you to locate the exported file, otherwise the file will be exported somewhere under the Weave directory (and if you don't specify a file name it will be named as ustorage.txt) but don't worry, the command will print out the name of the file that it is using.

This allows you to backup the current user settings and migrate them to the new Weave instance.

There is a similar storage command that does the same thing for system settings, to ensure a complete migration you should also use the storage save and load commands with another file.

Note that you need to be using version 1.1.0 of the com.cohga.server.user.storage.osgi bundle for the ustorage command, and version 1.1.2 of the com.cohga.server.storage.osgi bundle for the storage command.
These are the versions included with Weave 2.4.0, so if you're running 2.4.0 or later then you already have the storage and ustorage commands available. They can be manually added to earlier 2.3.x versions of Weave, please contact Cohga for updated bundles if you're running a version earlier than 2.4.0.

To execute these commands the server needs to either be started using startup.cmd (on Windows) or debug.sh (on Linux), to provide access to the osgi prompt directly, or started with telnet access enabled so that the osgi console can be remotely connected to using a telnet client, for situations where Weave is started as a background service and direct access to the osgi console isn't available.

Upgrading from 2.3 to 2.4

Upgrading Weave from 2.3 to 2.4 currently requires a fresh installation of the new version and migration of an existing configuration.

Installation Sources

There are generally two installation sources for Weave, a CD image .iso file (that can either be burnt to a physical CD or mounted directly with the appropriate software) and a .jar file which is the actual Weave installer.
Starting the software installation is slightly different if you're installing from a CD than if you're installing from the .jar file, but the actual installation process is the same.

The reason for the two different installation media is related to the size of the download, with the installer .jar file being significantly smaller than the CD image, but the .jar file requires a Java runtime to already be installed on the server, whereas the CD image contains the installer .jar file along with a (number of) Java runtime(s) to start it.
Both installation sources end up running the same Weave installer (the afore mentioned installer .jar file) and once the installer is started, the installation process is the same for both.

If you're going to be installing to a server that already has Java installed (any Java version 1.4 or above is sufficient) then using the installer .jar file directly will save you using unnecessary bandwidth. It may be even quicker to download the installer .jar file and a Java runtime (and install it directly) than it would be to download the .iso image, since the .iso image contains four Java runtimes (32 bit and 64 bit for both Windows and Linux). If you are installing to multiple servers or do not want to install unnecessary software (since the .iso installation method doesn't require the installation of the Java runtime just to run the installer) then the .iso image may be a better option.

Another advantage that the CD .iso image has over the installer .jar file and a reason for its larger size, is the fact that the CD image contains both a 32 and a 64 bit Java runtime for running the installer.
The reason for this is that currently the version of the Java runtime that is installed with Weave, as opposed to the one on the CD image used to run the Weave installer, will be 32 bit or 64 bit depending upon the Java runtime that was used to start the Weave installer.
This means that you can install the 64 bit version of Weave using the CD image if your server only has a 32 bit Java runtime, or no Java runtime, installed.
You can only install the same version as the Java runtime you are already using if you use the installer .jar file directly.
This may be changed in the future.

Installing from a CD image .iso file

Launching the Weave installer from the CD image can be done by running the install.cmd or install64.cmd batch files on Windows or install.sh or install64.sh scripts on Linux. These scripts are in the root directory of the CD image.
These scripts are used to launch the Weave installer .jar file using one of the Java runtimes available on the CD, with the install versions installing a 32 bit version of Weave, and the install64 version installing a 64 bit version of Weave.

Installing from an installer .jar file

To install Weave directly from the installer .jar file requires starting the .jar file using the Java runtime already installed on the server.
If you already have an older version of Weave installed on the server then you can use the JDK that was installed with that exisitng version.

Depending upon the file association configured for your server, you may be able to start the Weave installer .jar file directly (by double clicking on it in Windows Explorer for example) but if this does not work then you should open a command prompt and and run the installer directly using the following command.

java -jar weave-installer.jar

In this text when directly referring to the Weave installer .jar file it will be presented as weave-installer.jar, but the file name may be different, for example it may actually be weave-installer-latest.jar or weave-installer-2.4.0.jar or even weave-installer-2.4.0-20110216.jar

You may need to fully qualify the java command if it isn't already in your PATH, for example if you're using an existing Weave installation it may be

c:\weave\jdk\bin\java -jar weave-installer.jar

or for Linux

/opt/weave/jdk/bin/java -jar weave-installer.jar

The installation process

Once started, the installer takes you through a number of steps:

Welcome screen
License agreement
Installation directory
Software selection
Port selection
Telnet access
Software installation
Completion screen

The Welcome screen and License agreement should be self explanatory, but the Installation directory can be a little tricky since we are performing an update, and generally when performing an update using the Weave installer, you do not want to install on top of an existing Weave installation, so you need to ensure that you install to a new directory.

As an alternative to installing to a new directory you can rename an existing Weave installation, to get it out of the way, and install to the same location, just make sure you remove any existing Windows service (using the remove-service.cmd batch file) before renaming the directory.

Warning: Once you have settled on an installation directory, choose which packages to install. Do not just install all of the packages, especially the Additional Components. It may be tempting to just click all of the check boxes but this is almost certainly not what you want. This will install components that you will never need and don't use. It will add additional memory and performance overheads that you do not want and it will install multiple versions of bundles where there should only be one of that type.

During the package selection you can see if Weave is installing the 32 or 64 bit version by expanding the Java Runtime pack. If the included pack references x86 then it is the 32 bit version, and if it references x86_64 then it is the 64 bit version.

Since we are performing an update to an existing Weave instance, you should know what additional components you had installed, and the process will be simpler if you first install the new Weave instance using the same components as you had before (It is possible to re-run the installer later and add new components if you want to once you have your existing Weave configuration up and running with the new Weave version that we are installing).
You should the expand additional components and closely examine the description for each item before selecting it for installation. This is because some components require other components to also be installed (and currently this isn't done automatically) and other components require you to choose one from a number of possible alternatives.

This is probably a good time to mention custom bundles that you may have installed in your existing Weave instance. These are bundles that are added to Weave manually and may have provided functionality just for your site, or functionality that is not included as part of the core Weave installation.
Hopefully these components are now available under the Additional Components section of the installation packages but if they are not then you will need to copy these bundles from the existing installation to the new installation after the new installation process has been completed.

If you choose to install Jetty then you will be given the choice of what port numbers Jetty will listen on and whether you'll be provided with access to the OSGi console via telnet (if you don't install Jetty then you'll need to install your own Web application server, such as Tomcat or WebSphere, and manage this yourself).
It is important that if you want to continue to run your previous Weave instance, that you choose different port numbers when asked. If you are replacing an existing instance, or you intend to only run one at a time, then you can use the same port numbers.

Migration

Once you have finished the installation you need to migrate your existing Weave configuration to the new instance, and copy over any custom plugins, before you start the new Weave instance.
This process involves renaming the new workspace directory and copying over the one from your existing instance. You could just delete the new workspace directory, but by renaming it you have the option of comparing the old and new version of some of the supplementary files that are included there.
The next migration step is to use the ustorage (and storage) commands to import the user settings from the previous instance.

Testing

Once the previous workspace is copied to the new instance it should be ready to test and no changes to any configuration files should be required.
It is advisable to do this initial test by starting Weave from the command line, via startup.cmd or debug.sh, so that you can see log messages immediately, but aware that if Weave is then installed as a service and run as a different user, then permission problems may occur. This is generally an issue when the instance is first started as a service and then later started via the command line. It has been mentioned in case you would prefer to install it as a service immediately and do the testing with Weave running as a service.

Support

The system should now be running as it was before, but sometimes there are going to be issues and Cohga support is the place to go, as well as the trouble shooting section of this wiki.

Upgrading from 2.4.x to 2.4.y

As of the release of Weave 2.4.2 a smaller weave-updater .jar file is available that provides an installer that includes only the changes since 2.4.0 and the current release. As at Weave 2.4.2 the size of this file was 12MB, which is considerably smaller that a new installer .jar or .iso file (by 2.4.10 it's grown to 55MB, still smaller than the other options).

This updater will be updated as new releases are available to include only the changes required to get a 2.4.x version to the latest version, and will save considerable bandwidth and time when trying to update to the latest Weave version. Running the updater on any previous version of Weave will result in the instance of Weave having exactly the same set of bundles as as full new installation of that latest version

Running the Weave updater is the same as the Weave installer .jar file (see the notes above about Installing from an installer .jar file) but will provide a cut down list of items that you can update which depends on what is already installed in the Weave instance that the update is being applied to, and what has changed between the latest updater and Weave 2.4.0. This list is only of components that have changed between 2.4.0 and the latest version that will be included in the updater. Furthermore, only functionality that was previously installed via the Weave installer will be available to update via the updater (to install new functionality that wasn't installed initially the original Weave installer should be used and the updater applied after).

The updater will install the newest versions of any plugins that were updated since the existing instance was installed, but it will currently not remove older versions of plugins (but this is ok because the next startup of the Weave instance will only utilise the latest version of any multiple version plugins to are installed). The updater will also update the config.ini as appropriate for components installed as part of the Weave installation process, and include custom bundles that were previously manually added to the config.ini file.

The latest updater can be downloaded from http://cohga.com/weave/weave-updater-latest.jar, or specific versions from http://cohga.com/weave/weave-updater-2.4.x.jar, where x should be replaced with the specific release number (starting from 2)

There has been an incident where Weave would not start correctly after applying an update to a early version of Weave 2.4, but this was resolved by removing any old versions of plugins and manually cleaning out the weave\platform\configuration directory (i.e. deleting everything in that directory except the config.ini file) then restarting.
The Weave updater will be updated (post 2.4.10) to remove old versions of plugins on an update to try and avoid this happening in the future).

Removing old versions of plugins involves ensuring that there is only one version of any given plugin, for example if there is a com.cohga.client.weave.main_2.11.8.jar, a com.cohga.client.weave.main_2.14.12.jar and a com.cohga.client.weave.main_2.18.14.jar file then the com.cohga.client.weave.main_2.11.8.jar and com.cohga.client.weave.main_2.14.12.jar files should be deleted leaving just com.cohga.client.weave.main_2.18.14.jar.

However, if the major version number is different, for example 2 is the major version number in the above example, then the latest versions of both bundles should be kept. So if there was also a com.cohga.client.weave.main_1.1.4.jar file then that should be kept along with com.cohga.client.weave.main_2.18.14.jar. Although in practice this will rarely of ever actually happen.