As you may have seen from the new features available in pulse™ 2.x, we 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.x 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.x installation.
A step by step description of the process is provided below.
Upgrading to the Latest 1.2
Before migrating, you must upgrade your 1.2 install to the latest 1.2.x release. This is because Jabberwocky is only designed to export from the final 1.2.x schema. This upgrade should be done in the normal fashion as described on the Upgrading page.
Generating a 1.2.x Export
The migration tool is available via the following links.
Download it using the links above, or using a tool like wget if you are connecting to a remote Pulse server:
To install jabberwocky, simply unpack it using an archiving tool. If you are using the command-line a simple tar or unzip will suffice:
We will refer to the directory into which jabber is unpacked 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 driver jar file into the JABBER_HOME/lib directory. For example, in bash:
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. For example, in bash:
In Windows the variable may be set via the Control Panel.
All that is left now is to run jabber and let it generate your export file. From the JABBER_HOME directory:
For more information about the command line utility, use the help command as follows:
for general help, or:
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.x, you will need to manually copy PULSE_DATA/projects to the host/filesystem where you intend to install Pulse 2.x, and then reference it when starting Pulse 2.x (instructions for this are below).
Please be aware that when Pulse 2.x imports the artifacts it will be rearranging the directory structure to suit the 2.x 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.x 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.x
The latest 2.x releases can be found on the Zutubi website page. Once downloaded, simply unpack the pulse™ 2.x package, for example:
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:
- Create a new blank database for pulse™ 2.x. You cannot use the same database as was used for your 1.2 install, although you can use the same MySQL or PostgreSQL server.
- 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.x, 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. Now start pulse™ from the PULSE2_HOME directory:
Once pulse™ has started, follow the instructions to restore and setup via the web UI.
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.
Select your database. The ability to configure your database via the setup UI is new to pulse™ 2.x. Simply follow the on-screen directions to configure your database details and test your database connectivity.
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.
Hints and Tips
For the jabber export to run smoothly on larger installations, you may need to increase the heap size used by the export process. There are two ways to do this. Either you can set the JAVA_OPTS environment variable as follows:
or you can update the jabber or jabber.bat files, changing the default value of JAVA_OPTS.
Please note that by default, JAVA_OPTS is set to use 1G of ram. This should be enough for most installations.
The 1.2.x to 2.x migration process is far from trivial considering the large internal changes that were made. If you happen to run into a problem that we have missed, please let us know by sending us an email or posting to the forums.