Installation

Starting the installer

To perform the initial installation you will require either the Weave installation ISO image or the Weave installer .jar file. Both can be downloaded from Latest Downloads if you have a current support subscription.

The ISO image will need to either be burnt to a CD (note that Weave 2.5 will fit on a CD, Weave 2.4 required a DVD) or mounted directly as an ISO image. To mount an ISO image in Windows see the documentation for Mount-DiskImage.

The advantage of the ISO image is that it can be used to install Weave on a "clean" server, since it is self contained, whereas the Weave installer .jar file requires that the server have a version of Java already installed on the server, since the installer requires Java to run.

If you are using the ISO image then run the setup.cmd (on Windows) or setup.sh (on Linux) that is on the CD and the installer should start.

If you are using the .jar file then you will need to open a command prompt (sometimes double clicking on the .jar file may start the installer, depending upon how the server is setup) and start the installer manually.

As mentioned previously, the Weave installer .jar file requires an existing version of Java to be available on the server. If the server already contains a Weave instance then you already have Java available, and you just need to specify that Java be used when starting the installer.

For example, assuming that we have Weave 2.4 installed on Windows at c:\weave-2.4\, and the installer .jar file is currently located at d:\temp\weave-installer-2.5.jar, then you can initiate the Weave 2.5 installer with the following command:

c:\weave-2.4\jdk\bin\java -jar d:\temp\weave-installer-2.5.jar

Additionally, if you already know where you want to install the new Weave instance then you can also specify that on the command line, e.g.

c:\weave-2.4\jdk\bin\java -jar d:\temp\weave-installer-2.5.jar c:\weave-2.5

On Linux the process will be similar, e.g.

/opt/weave-2.4/jdk/bin/java -jar /tmp/weave-installer-2.5.jar /opt/weave-2.5

If you do not already have a Weave instance available on the server then you may need to install Java, which you can uninstall after you have finished the installation process.

In this case the java command you will have to run will be different because the java executable will be installed in a different location, e.g.

"c:\program files\java\jre1.8.0_45\bin\java" -jar d:\temp\weave-installer-2.5.jar

The installation process

Step 1

Installing Weave 2.5 is similar to the process required for Weave 2.4, which starts with a welcome screen

Step 2

This is followed by the Licence screen, where you must accept the licence agreement before you can proceed.

Step 3

Next you need to choose the location (Target Path) where you want to install the new instance of Weave. If you specified an install location on the command line when starting the installer, then the Target Path should already be showing on the Target Path menu.

Step 4

At this step you are presented with the available installation options.

The installation options are presented in a tree where the individual components are grouped based on their purpose.

The first group of options are the main components.

The second group of options are the optional components that can be added to Weave. Do not just select all of them blindly. These are optional because they have a cost associated with installing them. If you do not need them then you should not install them. You should, since we are talking about upgrading an existing Weave instance here, select the same set of extensions that you had installed in the previous instance of Weave that you are upgrading.

The final two sections, 'Tools and Samples' and 'Developer Tools', do not need to be selected.

The Tools and Samples section contains a tool to convert an existing EView configuration to Weave, and some (old) example configuration files, neither of which are useful when upgrading an existing instance.

The Developer Tools section contains developer documentation and additional bundles that should only ever be installed when creating a Target Platform for creating Weave extensions in the Eclipse IDE. These should not be installed into a standalone instance of Weave and they are only required when setting up a development environment.

Step 5

The next step is to choose the port numbers that Weave will be listening on, normally these should be different from any other instance of Weave that is running on the same server.

If you are performing this installation to upgrade an existing 2.4 instance, then you probably want to keep them the same port numbers as the existing instance so that you can just stop the old instance and start the new one and none of the users will have to be aware of any difference (for example, having to use a different URL to access Weave because the HTTP port has changed).

This can, however, cause problems if you want to run both instances at the same time. (e.g. if you are setting up the new Weave instance but still need to allow the users access to the old one). The obvious solution to this is that you probably should not be installing this new Weave instance directly in the same production server that your users are accessing and instead, should be using a staging/testing server for this process, and them moving the installation from the staging/testing server to the production server.

Assuming that you do not have this option, then you will need to specify a different set of ports at this step and once it is time to switch over, change the port numbers in the new instance to match the old one, stop the old instance, and start the new one (once you confirm that everything is working as it should).

Step 6

The next step is to optionally enable the Telnet service and specify the port it will listen on. The same issues with this port number apply as those from Step 5.

Step 7

This step configures the information required to install the new instance as a service/daemon. It does not install Weave as a service/daemon. That must be done as a separate step after the installation process is completed.

Step 8

The next page is shown when the installation process is running and the files are being copied to the new Weave installation directory.

Step 9

The final page is presented once the installation is completed and provides an option to generate an installation script. This script can be used with the installer at a later time to perform the same installation without having to go through the whole process of making the choices via the install GUI. In this way the installer can be run entirely without presenting the GUI and perform the same installation (with the option of installing to a different directory)

Interoperability with Third Party Applications

If you are integrating Weave with third party applications (e.g. Pathway, DataWorks, etc), then you will need to perform an extra installation step since these components are no longer provided as part of the core Weave installer. To do this, go to the download page and grab the Interop installer download (it will be a .jar file you can run in the same manner outlined above for the main installer). You just need to provide the new Weave installation directory and which of the interop bundles you want installed as part of the installation process. The installer will install the additional bundles and update the installation to ensure that they are started.

Migrating your existing configuration

Once you have the new Weave instance installed you will need to move your configuration from the existing 2.4 instance to the new instance.

The primary files that you will need to migrate are security.xml and any files it includes (for example users.properties) and config.xml along with any files that it includes.

By convention some sites split their config.xml file into multiple files and stored most of the actual content under a conf directory. Generally it would be enough to copy config.xml and the conf directory from the previous instance to the new one.

If you have encrypted any passwords in your config.xml file using the OSGi consoles encrypt command then you will need to copy the private.key file from your old installation.

Once you have security.xml and config.xml (and their associated files) and maybe private.key copied over you should have enough to at least test that the new server will start.

To perform a test at this stage run the startup.cmd or startup.sh script to start the Weave instance. You should see a whole bunch of logging being output to the console (those keen eyed amongst you may notice a bunch of exceptions about bundle dependencies not being met logged early in the startup process, these can be ignored).

security.xml changes

There are a couple of places where the security.xml file has been updated from 2.4 so if you copy over your existing security.xml file you will need to apply these changes manually.

Near the top where the filterChainProxy is defined there are a couple of new values that need to be added to the filter list. By default there will be at least two entries in this list already, one for /server/** and one for /**. These entries describe the list of filters that must be applied to every client request that starts with this pattern, and we need to add a couple of new entries to this list.

The first entry to add is a completely new one

/server/ping=pingSessionContextIntegrationFilter

This should be added exactly as it's show above to the list. Additionally early releases of 2.5 did not include a similar entry for the /server/heartbeat.do pattern, you may need to manually add that entry too (see the more complete example below)

The second entry to add is to filter resources that start with /services/**, and for this filter we need to copy the existing /server/** filter and just change the pattern. So for example if your current /server/** filter is:

/server/**=httpSessionContextIntegrationFilter,authenticationProcessingFilter,securityContextHolderAwareRequ...

you should copy and paste that line then change /server/** to /services/** in one of those lines, so you would end up with something like this:

/server/**=httpSessionContextIntegrationFilter,authenticationProcessingFilter,securityContextHolderAwareRequ...
/services/**=httpSessionContextIntegrationFilter,authenticationProcessingFilter,securityContextHolderAwareRe...

After those to changes the filter list should look something like:

/server/ping=pingSessionContextIntegrationFilter
/server/heartbeat.do=pingSessionContextIntegrationFilter
/server/**=httpSessionContextIntegrationFilter,authenticationProcessingFilter,securityContextHolderAwareRequ...
/services/**=httpSessionContextIntegrationFilter,authenticationProcessingFilter,securityContextHolderAwareRe...
/**=httpSessionContextIntegrationFilter,logoutFilter,authenticationProcessingFilter,securityContextHolderAwa...

Note that the list of filters for /server/** and friends may be different for your security.xml file, for example yours may include ntlmProcessingFilter if you're using integrated authentication.

The ordering is important, in as far as ensuring that the more generic filter patterns are listed after the more specific ones, for example /server/ping being listed before /server/**, and /** being listed last.

After we've changed the filter list we need to add a new bean which provides the definition for the pingSessionContextIntegrationFilter we just added.

So after the filterChainProxy bean we just edited a new bean with the following definition:

	<bean id="pingSessionContextIntegrationFilter" class="org.acegisecurity.context.HttpSessionContextIntegrationFilter">
		<property name="allowSessionCreation" value="false"/>
		<property name="forceEagerSessionCreation" value="false"/>
	</bean>

That takes care of the first change that we needed to make, the second change is further into the security.xml file, and the thing we need to change is the objectDefinitionSource inside of the filterInvocationInterceptor.

The change is similar to that which we made to the filterChainProxy above, in that we're adding a couple of new filters that were not in the older file.

What we need to  do is to ensure that three new URL's are always available regardless of the user being logged in or not, so the filter definitions we'll want to add are:

/login.*=IS_AUTHENTICATED_ANONYMOUSLY
/login/**=IS_AUTHENTICATED_ANONYMOUSLY
/report/remote/**=IS_AUTHENTICATED_ANONYMOUSLY

So after the changes you should have something like the following for the objectDefinitionSource within the filterInvocationInterceptor

		<property name="objectDefinitionSource">
			<!-- Make sure the login pages can always be accessed, unless you really want to disable forms login, and that BIRT can talk to the server -->
			<value>
				CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
				PATTERN_TYPE_APACHE_ANT
				/login.*=IS_AUTHENTICATED_ANONYMOUSLY
				/login/**=IS_AUTHENTICATED_ANONYMOUSLY
				/report/remote/**=IS_AUTHENTICATED_ANONYMOUSLY
				/**=IS_AUTHENTICATED_ANONYMOUSLY
			</value>
		</property>

Note that you may have other entries in the list and /** may have a different value, IS_AUTHENTICATED_FULLY for example, that doesn't matter, as long as you add the three new ones exactly as shown above, and add them before the /** entry. 

JDBC Drivers

You also need to copy any JDBC database drivers that Weave requires to connect to databases.

These drivers should be copied from the platform\workspace\jdbc directory in the old installation to the same directory in the new one.

One driver not to copy is the org.hsqldb.hsqldb driver, this is used internally by Weave and has been updated to a newer version and should already exist in the platform\workspace\jdbc directory.

Also, if you installed the BIRT report designer and you will be connecting to databases then you also need to copy your jdbc drivers into birt\plugins\org.eclipse.birt.report.data.oda.jdbc_4.3.1.v201308301349\drivers. This does not apply if you're just connecting to Weave to retrieve data, only if you are connecting to another database within any of your reports.

Testing

Once the server has finished starting up you should be able to open a browser and point it to the new instance and everything will appear as it did in the Weave 2.4 instance.

Yea right, if that happens I want to know, because there is probably going to be issues.

You will have bundles installed in your 2.4 instance that are not a core part of Weave that weren't installed as part of the installation, you'll have other custom files that were part of the old instance that have not been copied overs.

I'll attempt to update this document as sites come across these issues to provides clarity for other site, but for now it's probably a case of contacting support and outlining what issues you're having.

Additional configuration files

Aside from the security and config files there are a scattering of other files that you will probably want to look at when migrating from 2.4 to 2.5.

Encryption key

One important file that you will want to copy from your previous installation is the private.key file. This file contains the encryption key that Weave uses when it needs to internally encrypt content, and if you've been a good Weave administrator you've used the encryption facility provided by the OSGi consoles encrypt command to encrypt any passwords that you have in you config.xml file(s).

If you do not copy the private.key file from your previous instance then when Weave starts up it will generate a new encryption key, which means that when it tries to decrypt the passwords stored in the config.xml file(s) it will not generate the correct passwords.

Logging configuration

There are a number of changes between Weave 2.4 and 2.5 that have been made to the logging.properties file, primarily related to which packages are excluded from being able to generate log output.

If you copy your existing Weave 2.4 logging.properties from a 2.4 installation to a 2.4 installation you are going to have a large amount of extra mostly useless information output to the weave.log file (which does neither of us any good).

So rather than just copying your existing logging.properties file you should instead make any changes that you had made to the 2.4 version to the new 2.5 version (if any).

If in doubt I'd leave the file as it is rather than trying to guess, but if you insist on using a 2.4 logging.properties file then I suggest what you do is take the 2.4 version of the file and remove all of the lines that start with log4j.logger. then add in all of the lines that start with log4j.logger. from the 2.5 version, and use the combined content as your logging.properties file.

Post Installation

After you've completed the installation there a some additional steps that you may way to take.

Windows Service/Linux Daemon installation

You may want to install the instance as a service, this has changed from Weave 2.4.

Weave 2.5 uses a different wrapper to install Weave as a service than was used with Weave 2.4, and therefore the scripts and configuration used are different from earlier versions.

Everything related to installing Weave as a service is now contained within the service directory, this includes the configuration of the service, which is located at service\conf and the scripts for installing/uninstalling the service, which are located at service/bin (for Linux) or service\bat (for Windows).

The basic information required to configure the service were provided as part of the installation, but there are still numerous options that can be changed by editing the service\conf\wrapper.conf file, for example, this file can be edited to enable the Telnet service if it was not selected during installation, or it can be modified to change the account that is used to launch Weave.

More information about what can be configured for the service is available at YAJSW Configuration Properties.

Finally, to install Weave as a service you need to run the service\bat\installService.bat script (on Windows) or service/bin/installDaemon.sh (on Linux).

Both of these scripts need to be run as an Administrator.

Weave Maximum Memory Limit

When Weave is run from the startup script the script contains a setting that specifies the maximum amount of memory the the process will be allows to use.

This was 1024M in Weave 2.4, and then changes to 2048M in Weave 2.5, but because it could cause issues when running on 32-bit server it has been reduced back to 1024M (from 2.5.9 onwards).

This may not be enough, and probably isn't but was chosen to ensure that the JVM had enough to at least start.

Depending upon how large your configuration is you may have to edit the startup script and increase the value.

SET JAVA_OPTS=-server -Xms512M -Xmx1024M -XX:PermSize=64M -XX:MaxPermSize=192M

JAVA_OPTS="-server -Xms512M -Xmx1024M -XX:PermSize=64M -XX:MaxPermSize=192M"

When Weave is running as a service the maximum amount of memory it's allows to use is not an absolute value (by default) but is instead set as a percentage of the total available memory.

This is specified in the service\conf\wrapper.conf file by the wrapper.java.maxmemory.relative value, which is set to 80 (percent) by default.

This value can be adjusted up or down or it can be commented out and wrapper.java.maxmemory used to set a fixed maximum (like the memory limit in the startup script).