This version (2017/08/24 18:01) is a draft.
Approvals: 0/1

Transferring Collections between Greenstone Installations

This page provides information on where collections are stored in your Greenstone installation, as well as information on moving collections from one installation to another (including from Greenstone2 to Greenstone3).

Transferring collections from one Greenstone installation to another can be very simple or reasonably complicated, depending on the circumstances. Collections live in the collect folder of a Greenstone installation. Each collection has its own folder inside there. Each collection is (almost always) self-contained in its folder.

The simple way to transfer collections is to copy the collection's folder from the original collect folder into the new collect folder. Most of the time, this will be enough to have the new collection working in the new Greenstone installation.

Folders to copy

If your collection is very big, you may not want to copy all the folders. The following is a summary of the folders in a collection. Some of them may not be present in a particular collection:

You never need to copy archives or building unless you have done special customizations where you are linking directly to files in archives, or if you are using incremental building and you don't want to do a full rebuild once the collection gets to its new place.

Generally, collections should copy over without many issues, though you may have to rebuild the collection. However, difficulties may arise depending on how different the versions are; therefore, you are encouraged to backup any collections prior to copying/rebuilding them in a different installation.

Complicating factors

There may be complication factors to this. Some of these are listed below. Your situation may encompass one or more or all of these factors.

Transfer between different operating systems

The GDBM files in a collection are endian-specific. For Greenstone 2.81 and later, collections should work on any 32bit operating system without modification. We have modified GDBM to handle both big and small endian files. Prior to that, the endianness of the gdbm file must match that of the OS running Greenstone. Generally, transfer between Windows and Linux is fine, but transfer to and from a Mac is not. The GDBM database must be rebuilt on the new platform.

If the new version of Greenstone is 2.81 or later, then the endianness of the file shouldn't matter, regardless of which platform it came from.

Transfer between different versions of Greenstone

In general, I think that built collection should copy fine. Some problems may occur if you want to rebuild the collection in the new installation. The configuration file may be slightly out of date if you are copying to a much newer Greenstone installation. The thing to do is to rebuild and see what happens. In GLI, use Expert mode so you can see if there are any errors during collection building. Some potential problems include plugin names and options changing, or other configuration file options changing.

Collections with a customized interface

If the collections have modified interfaces (i.e. customized macro files) then transfer may be a bit tricky.The simple case is where all the modifications have been done in (or other files) in the macros folder of the collection, and transfer is between the same version of Greenstone. Just copy the collection and it should be fine.

If the macros are all in the collection, but the Greenstone versions are significantly different, then the macros might not work as expected. Copy the collection over, make a backup of the macro files in the collection, then modify them to get what you want. Look at the main macros in the new installation to see how things are done there.

The hardest situation is where you are copying collections from a heavily modified Greenstone installation. Here, the macro changes are probably in the main macro files, and it may be difficult to see what has changed. Some suggestions are

  • If you want the collections to look exactly the same, consider having a separate Greenstone installation on the new server for these collections. You'll need to install the same version of Greenstone that was used originally, then copy over all the macro files.
  • If you are happy that it doesn't look like the orignal, just copy the collection and use the existing Greenstone installation. You may want to make some small collection specific customizations.

From Greenstone2 to Greenstone3

If you are a Greenstone2 user, you can move your collections from Greenstone2 to Greenstone3. Simply copy the appropriate folders from the Greenstone2 collect folder to the Greenstone3 collect folder, and then rebuild the collections in the GLI.

Important Note: This option is for Greenstone 3.02 only, it will be added into 3.03 later. For large collections, you can avoid rebuilding by running a conversion script instead. For the version 3.03 you must use this conversion script not the one provided by the Greenstone3 installer. This script will be added into the next release.


These instructions assume Greenstone2 is installed to C:\Program Files\Greenstone2 and that Greenstone3 is installed to C:\Program Files\Greenstone3, so please make the necessary adjustments if you installed either version of Greenstone to a different folder.

To port a collection called mycoll, you would use a file browser to copy the folder C:\Program Files\Greenstone2\collect\mycoll to the folder C:\Program Files\Greenstone3\web\sites\localsite\collect. Then, open the collection in the GLI and rebuild it.

If the collection is very large, you may prefer to just run the conversion script, to avoid a lengthy rebuild. To do this, open up an MS-DOS box (Start →(All) Programs → Accessories → Command Prompt) and execute these commands.

cd "C:\Program Files\Greenstone2"
cd "C:\Program Files\Greenstone3\gs2build"
cd "C:\Program Files\Greenstone3"
gs2build\bin\windows\perl\bin\perl.exe bin\script\ \
     -collectdir "C:\Program Files\Greenstone3\web\sites\localsite\collect" mycoll

If you need you collections to appear with the classic Greenstone2 look-and-feel, see the interfaces page.


These instructions assume Greenstone2 is installed to /opt/greenstone2/ and that Greenstone3 is installed to /opt/greenstone3/, so please make the necessary adjustments if you installed either version of Greenstone to a different folder.

To port a collection called mycoll, you would copy the folder /opt/greenstone2/collect/mycoll/ to the folder /opt/greenstone3/web/sites/localsite/collect/.

cd /opt/greenstone2/
cp -r collect/mycoll/ /opt/greenstone3/web/sites/localsite/collect/

Then, you would open the collection using the GLI and rebuild it. Or if you collection is very large and a rebuild would take too long, run the conversion script instead. On the command line, execute these commands: (from the Greenstone2 installation directory)

cd /opt/greenstone2/
source setup.bash
cd /opt/greenstone3/gs2build
source setup.bash
cd /opt/greenstone3/
bin/script/ -collectdir /opt/greenstone3/web/sites/localsite/collect mycoll

You need to do this for each collection you wish to port. To see a list of available Greenstone2 collections, run this command:

ls /opt/greenstone2/collect/

You may need to close and re-open the Greenstone3 server before the ported collections are available in Greenstone3.

If you need you collections to appear with the classic Greenstone2 look-and-feel, see the interfaces page.