Backing up client settings
| Info |
|---|
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. |
...
| Warning |
|---|
Weave 2.4.16 changes the way user settings are stored and removes the need to backup and restore the user settings when performing an upgrade. |
Backing up user settings
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.
...
| Info |
|---|
Note that you need to be using version 1.1.0 of the |
| Infowarning |
|---|
To execute these commands the server needs to either be started using |
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.
| Info |
|---|
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. |
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.
| No Format |
|---|
java -jar weave-installer.jar
|
| Info |
|---|
In this text when directly referring to the Weave installer .jar file it will be presented as |
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
| No Format |
|---|
c:\weave\jdk\bin\java -jar weave-installer.jar
|
or for Linux
| No Format |
|---|
/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.
| Info |
|---|
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 |
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.
| Info |
|---|
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.
| Note |
|---|
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. |
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.
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 Weave updater is the same as the Weave 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.
The updater will copy over updated versions of plugins, but will not remove older versions. It will update the config.ini as appropriate for components installed as part of the Weave installation process, but this means that custom bundles may need to be added back to a config.ini file after an update as the custom bundles will not be touched by the updater.
...
Updating to the new Database user storage option
The method used to store bookmarks and redlines in earlier versions was not robust enough under load, so it has been replaced by one that stores this information in a database.
If you are running version 2.4.16 you are already using this update. If you are running an earlier version you can follow these instructions to update without having to upgrade to 2.4.16.
The updated bundle is available at:
com.cohga.server.user.storage.db_1.4.2.jar
To use this you must:
- export the existing settings using ustorage save at the osgi prompt
- stop the server
- remove the older com.cohga.server.user.storage.osgi bundle from platform\plugins
- install the newer com.cohga.server.user.storage.db bundle to platform\plugins
- replace com.cohga.server.user.storage.osgi with com.cohga.server.user.storage.db in platform\configuration\config.ini
- clean out the platform\configuration directory (except config.ini)
- start the server
- import the existing settings using ustorage load at the osgi prompt.
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 the 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.
| Info |
|---|
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. |
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.
| No Format |
|---|
java -jar weave-installer.jar
|
| Info |
|---|
In this text when directly referring to the Weave installer .jar file it will be presented as |
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
| No Format |
|---|
c:\weave\jdk\bin\java -jar weave-installer.jar
|
or for Linux
| No Format |
|---|
/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.
| Info |
|---|
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 |
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.
| Info |
|---|
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.
| Note |
|---|
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. |
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.
| Warning |
|---|
If you're replacing a newly installed workspace with an old production one you may need to copy the org.hsqldb.hsqldb_2.2.5.jar file from the old workspace jdbc directory to the new one. |
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)
| Note |
|---|
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. |
| Info |
|---|
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. |