Introduction
As you may have seen from the new features available in 2.0, there have been very busy adding many improvements. Since some of these improvements result in significant changes to the persistent storage used by Pulse, we have deviated from our standard in-place upgrades, and implemented this one-off migration process.
The Pulse 1.2.x to 2.0 migration tool, lovingly named Jabberwocky, will generate an export of your 1.2.x installation that can then be imported into your new or existing 2.0 installation.
A step by step description of the process is provided below.
Generating a 1.2.x Export
The migration tool is available via the following links.
jabberwocky-1.0.zip
jabberwocky-1.0.tar.gz
To install jabberwocky, simply unzip it.
$ tar xzvf jabberwocky-1.0.tar.gz
We will refer to the directory into which jabber is unzipped as JABBER_HOME.
If your Pulse installation is using an external database, jabberwocky will need access to jdbc drivers you are using. Simply copy the jdbc jar file into the JABBER_HOME/lib directory. For example:
$ cp postgresql-jdbc3-8.1.jar $JABBER_HOME/lib
Jabberwocky is a Java application that requires Java 1.5 or higher. To assist the command line scripts in locating the correct version of Java, ensure the java binary is in your PATH or set the JAVA_HOME environment variable:
$ export JAVA_HOME=/path/to/jdk/1.5
All that is left now is to run jabber and let it generate your export file:
$ $JABBER_HOME/bin/jabber export -f pulse-1.2.x-export.zip /path/to/pulse_data
For more information about the command line utility, use the help command as follows:
$ $JABBER_HOME/bin/jabber help
for general help, of:
$ $JABBER_HOME/bin/jabber help export
For specific help on the export command.
To keep the size of the export manageable, the artifacts located in the PULSE_DATA/projects directory are not included in the zip file. If you wish to transfer them to Pulse 2.0, you will need to manually copy PULSE_DATA/projects to the host/filesystem where you intend to install Pulse 2.0 , and then reference it when starting Pulse 2.0 (instructions for this are below).
Please be aware that when Pulse 2.0 imports the artifacts it will be rearranging the directory structure to suit the 2.0 layout. For this reason, it is highly recommended that you make a copy of the PULSE_DATA/projects directory, and not just refer to it during the Pulse 2.0 startup. Doing the latter will result in incompatible changes to your PULSE_DATA/projects directory that will prevent Pulse 1.2.x from being able to locate artifacts.
If disk space is an issue, we would recommend that you review your project cleanup rules and clean out artifacts that you do not require. Alternatively, you can proceed with the export but not transfer the artifacts.
Setting Up Pulse 2.0.x
The latest 2.0.x releases can be found on the Early Access Program page. Once downloaded, simply unzip the pulse™ 2.0 package:
$ tar xzvf pulse-2.0.tar.gz
The directory into which pulse™ is unzipped will now be referred to as PULSE2_HOME.
If you intend to connect pulse™ to an external database, you will need to provide the jdbc driver for that database. Obtain an appropriate driver from your database vendor, and then point pulse™ to a copy of the driver on the local filesystem during the setup wizard.
Before starting pulse™ 2.0, you will need the pulse-1.2.x-export.zip file you created previously, and the copy of the PULSE_DATA/projects directory if you intend to restore the artifacts.
$ $PULSE_HOME/bin/pulse start --restore=/path/to/pulse-1.2.x-export.zip --restore-artifacts=/path/to/artifact/copy
Once pulse™ has started, follow the instructions to restore and setup via the web UI.
Step 1:
Select your pulse™ 2 data directory. pulse™ 1.x and pulse™ 2 use slightly different data directories layouts. Please be sure that you do not select your pulse™ 1.2.x data directory as your pulse™ 2 data directory.
Step 2:
Select your database. The ability to configure your database via the setup UI is new to pulse™ 2.0. Simply follow the on-screen directions to configure your database details and test your database connectivity.
Step 3:
Restore Pulse. This stage of the setup begins the import of your data and configuration from the exports. Depending on the amount of data being dealt with, this may take some time. pulse™ will provide feedback on progress and estimates on time remaining where possible.
Once the restore is complete, pulse™ 2 will complete its startup and will begin monitoring your repositories based on your 1.2.x configurations.
What's Next?
For now, head on over to the Early Access Program for the latest details on the 2.0 release. As we get closer to the final release of 2.0 we will be adding more documentation to ease your passage into 2.0.
