This page is up to date for 3.06 (5 Nove 2014)

Advanced Installation

For most users, the main Greenstone download (also called the "binary") with default settings is sufficient, and is very easy to install. However, there are some instances where you may want or need to go through a more advanced installation process:

  • If you want to compile up Greenstone for a particular OS that we don't provide the binaries for
  • If you had any issues with the pre-compiled binaries for your operating system
  • If you want to locally patch up or modify the source code of a particular release that otherwise works fine for you
  • If you want up-to-date code
Installation OptionCurrency of CodeCode typeDescription
Binary (the main download)Release-SpecificBinaryThis is the official, pre-compiled version of the software. It is platform-specific, and what most Greenstone users use.
Source componentRelease-SpecificSource Top-Upif you already have the binary installed, you can top it up with the source component which provides the code that you can compile. Note that the source component belongs with a particular binary. This means it is static code (code as it was when the associated binary was released), not the latest version of the source code.
Source distributionRelease-SpecificSourceif you want to compile the code for a particular binary release without installing the binary first, you can get the source distribution. Once more, this is static code: the code as it was when the binary was released. This is useful if you want to compile up Greenstone for a particular OS that we don't provide the binaries for, or if you had any issues with the pre-compiled binaries for your OS. It's also handy for if you want to locally patch up or modify the source code of a particular release that otherwise works fine for you.
Source via SVNUp-to-dateSourceSVN hosts the latest version of the Greenstone code. This is handy to get if you want to compile up Greenstone yourself and ensure you have the latest code in doing so.

Installation for a networked lab environment

To support use of Greenstone 3 in a networked lab environment, it is possible to adjust the configuration settings of the installation to have one shared installation of the software, but allow individual users to build and serve collections from their own area of the file system. We refer to this as a "dispersed GS3" setup. More specifically, it is appropriate for a situation where your Greenstone 3 is to be distributed across 3 locations of your Windows machine: an installation location which is read-only regular users, and to which only the administrator has write permissions; a user-web location that is writable and specific to a user; and a temporary (typically local) file system area the user has read/write permissions to.

In the following text we describe the setup procedure for Windows, with Greenstone installed in C:/Program Files/. The same capability will work in networked situations for MacOS and Linux labs, choosing an appropriate directory such as /usr/local/Greenstone3 as the location to install the GS3 software to.

For one computer, here's how you can have Greenstone installed centrally (e.g. Program Files), but then have each different user when working at that computer have their own instance of the Greenstone 3 sites, collections, and customisations of the interface.

Install GS3 as an administrator using the binary installer. Then set the following 4 properties in build.properties:

  • set using.user.web=true
  • set web.home=${user.home}/greenstone3/web
    Java's user.home property should resolve to a writable user location, e.g web.home will work out to be something like C:/Users/me/greenstone3/web). You can decide on other locations within ${user.home}, as you choose. For example, you can set web.home=${user.web}/gs3/myweb.
    Or if your lab setup is such that you're mounting each user's account at H: at each log in, then just set web.home=H:/gs3/web. Then, whenever any user is logged in, their collection data will be in H:/gs3/web. So web.home in such a case may look static and fixed to somewhere in H: in the build.properties file, but it's actually not static, since it changes to refer to different users' accounts based on who is logged in.
  • set gsdl3home.isreadonly=true
  • set gsdl3.writablehome=${java.io.tmpdir}/greenstone/web

Set all the property values exactly as above, except web.home, which you should customise to point to a location that is writable by the GS3 user where the user can create collections. File path separators should be URL style slashes (forward slash, /).

Now if you replicate the installation to other machines in the lab, your users can log into any machine and continue working with Greenstone3.

Running the installer in text-only mode

  1. If you're on Linux or Mac, give the binary of the installer execute permissions
  2. Then run it by passing in the text-only flag, as shown below.
  3. Follow the instructions on the screen thereafter. If you mistype at any stage, press ctrl-C to start again.
> ./Greenstone-3.06rc1-linux-x64 text-only
----------------------------
Extracting java installer...
----------------------------

Extraction Complete
You can now run "java -jar greenstone.jar text" to run the installer from the command line
>

Windows

Prerequisites for compiling the source component and source distribution on Windows:

  • Java JDK 6.x or later. For compiling on Windows 64 bit, need the 64 bit version of JDK. For compiling Greenstone 3.06 and onwards, need JDK 7.x or later.
  • PERL: if you're using GS3.07 or earlier, get ActivePerl for Windows. From GS3.08 onwards, binaries and source distributions come with a Strawberry Perl located in the GS3's gs2build\bin\windows\perl folder.
  • Visual Studio 8 or later (Visual Studio 12 on 64 bit Windows 10 worked too.)
  • (If you want to compile GS2 or GS3 with debugging on, you will need Microsoft SDK)
  • Additionally for Greenstone3: Apache ANT

You will need to set up your environment to locate and use the above. For this purpose, it's handy to create a bat file that you can always run before compiling Greenstone. A template bat file follows. Adjust it to contain the paths to your installations of the above. We'll call this bat file setupenv.bat and refer to it as such below.

@echo off

:: Script to set up Java, ant, perl
:: And set up Visual Studio for compiling the C/C++ in GS2 and GS3

set JAVA_HOME=C:\Program Files\Java\jdk1.7.0_25
if not exist "%JAVA_HOME%" (
echo %JAVA_HOME% not found. Exiting...
goto done
)

:: From GS3.08 onwards, a Strawberry Perl is included with binaries and source distributions
:: in your GS3's gs2build\bin\windows\perl folder
set PERLPATH=C:\Users\Me\perl

:: If you're compiling Greenstone 3, you'll also need ANT
:: Note that GS3 binaries ship with Ant, located in ''packages\ant''
:: For GS3 source distributions, download your own ANT and extract it and set
:: the environment variable below and adjust the PATH.
set ANT_HOME=C:\Users\Me\ant

:: Add the bin folders of Perl and Java (and Ant for GS3) to your PATH
set PATH=%PERLPATH%\bin;%ANT_HOME%\bin;%JAVA_HOME%\bin;%PATH%

:: If you want to compile GS2 with debugging on, you also need MS SDK and the following line:
:: call "C:\Program Files\Microsoft SDKs\Windows\v6.1\Bin\SetEnv.cmd"

:: Set up Visual studio environment. vcvars<num>.bat may be called vsvars<num>.bat
:: FOR COMPILING ON 32 BIT WINDOWS:
:: (if using 64 bit windows, comment out the following line by prefixing with two colons)
call "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin\vcvars32.bat"

:: FOR COMPILING ON 64 BIT WINDOWS, 
:: only confirmed to work with MS Visual Studio versions 9.0 and 12 so far:
:: (if using 64 bit windows, uncomment the following line by removing the two colons at its start)
:: call "C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat" amd64

:done

To make it easier for developers, a batch file containing placeholders you can adjust is already prepared and discussed at Source Installation on Windows.

Source Component

Source Distribution

Up-to-Date source code from SVN

Prerequisites for compiling on Windows:

  • Java JDK 6.x or later
  • PERL (ActivePerl for Windows
  • Visual Studio 8 or later
  • (If you want to compile GS2 or GS3 with debugging on, you will need Microsoft SDK)
  • Additionally: Apache ANT for Greenstone3

In addition to the Prerequisites for compiling Greenstone on Windows listed above, to install Greenstone from SVN source on Windows, you need to install svn.

SVN, ANT, and JAVA must be put on PATH and Visual Studio must be set up for compiling the C/C++ code, which can be accomplished using this file:

 vcvars<number>.bat file

For more detailed instructions on source installation, please refer to the Windows source installation page.

Linux/Mac

In order to install Greenstone from source on Linux, you need to have the following installed:

  • ANT
  • Java JDK. JDK 7 for Greenstone 3.06 and onwards
  • C/C++ compiler: XCode on Mac, gcc/g++ on Linux

Source Component

Source Distribution

In the terminal:

  • set ANT_HOME and JAVA_HOME
    To set these, you can find out where java is installed on your unix system by first running where java. Doing so should display a system location. Then run ls -la <java-location> using that location value. If the result of this ls operation shows that the location is a symlink, run ls -la <symlink> on the symlink, until all symlinks are exhausted and you get to an actual location on the file system. Having found the actual location of java, you don't want the bin directory, but its containing folder. Set this as JAVA_HOME. Locate and set ANT_HOME in similar manner.
  • Add svn/bin to PATH
  • Add ANT_HOME/bin to PATH
  • Add JAVA_HOME/bin to PATH

It may be easiest to create a bash script to set the above environment variables. Then you could run that script before compiling and, in a separate terminal, before running Greenstone applications.

export ANT_HOME=/path-to-your/ant
export JAVA_HOME=/path-to-your/java
export PATH=/path-to-your/svn/bin:$JAVA_HOME/bin:$ANT_HOME/bin:$PATH

Up-to-Date source code from SVN

For more detailed instructions on installation, please refer to the Linux and Mac OS source installation pages.

Source Code Stability

Note: This page is aimed at Greenstone developers.

The source code stability system attempts to provide developers with a constant stable code base for development even as the main trunk passes between stable and unstable states. If you are doing development on a working copy of the trunk, but the trunk has bugs which prevent it compiling or running, then it can be very hard to test your changes. Rather than spend time inquiring into those bugs, the stability system gives you a way to temporarily roll your working copy back to the last stable state. Once you have finished testing your changes, you can then roll you working copy forward again and commit your changes. Except in the case where other developers have made significant changes to the trunk, your changes will start working once the trunk is stable again.

The stability system works by periodically checking out the trunk and testing it for stability, then creating a 'stable' tag if and only if the trunk passes these stability tests. For now the stability tests are as simple as checking that the release kits on all three main operating systems were able to successfully create a release from the trunk. In the future, these checks could be extended to include regression tests, installer tests, tests to the runtime system and anything else which might further 'prove' the stability of the trunk. Stable tags related to Greenstone2 are named 'stable' and stable tags related to Greenstone3 are named 'stable3'.

To make your working copy stable, change to the root directory of the working copy and run one of these commands:

 (For Greenstone2): svn switch http://svn.greenstone.org/gsdl/stable
 (For Greenstone3): svn switch http://svn.greenstone.org/greenstone3/stable3

Or to checkout a fresh stable working copy, run one of these commands:

 (For Greenstone2): svn checkout http://svn.greenstone.org/gsdl/stable gsdl
 (For Greenstone3): svn checkout http://svn.greenstone.org/greenstone3/stable3 greenstone3

Then test your changes and/or keep working on them. Once you are ready to commit your changes, switch back to the trunk:

 (For Greenstone2): svn switch http://svn.greenstone.org/gsdl/trunk
 (For Greenstone3): svn switch http://svn.greenstone.org/greenstone3/trunk

And commit as normal.

Note: The stable tags are read-only. (Only the nightly tasks that create the stable tags can write to them.) This is for good reason; allowing commits to the stable tag would be lost the next time the trunk was tagged as stable.

The projects 'gli', 'gs2build', 'indexers' and 'documentation' also have stable tags. You can execute a command like the following to switch to the stable tag for one of these projects:

svn switch http://svn.greenstone.org/project-name/stable[3]

And switch back with:

svn switch http://svn.greenstone.org/project-name/trunk

Note: Though the stable branches are in separate locations in the repository, they should be considered as one unit. To get a bona fide stable working copy, each project which made up the working copy would have to be switched to the stable tag of the project. Mixing of 'stable' and 'stable3' tags would also prevent a working copy from being a bona fide working copy.

Moving a Greenstone installation

For Linux, you will need to uninstall your Greenstone first and then reinstall it in the new location.

For Windows: In the case of GS2.83, if you move your Greenstone2 installation folder to some other location, make sure that you relocate it such that there are no spaces in its new path. For instance, "C:\Program Files\myfolder\greenstone2" contains a space between "Program" and "Files", which is not supported in version 2.83. In future versions of Greenstone, the spaces will not be a problem.

Once you've moved your Greenstone installation, there are a few further things to do to get it to work again:

  1. Open your Greenstone 2 installation's cgi-bin\gsdlsite.cfg file and change the value for the GSDLHOME property to reflect the new path to your Greenstone installation.
  2. To get the local library server (server.exe) to work from the new location: if your top-level Greenstone installation folder contains the files llssite.cfg and glisite.cfg, delete these. (Note that you should not delete the template files llssite.cfg.in and glisite.cfg.in!) If running the local library server has any issues with Internet Explorer, go to the local library's File>Settings menu and change the Other Browser setting to use Firefox.
  3. To get the Apache web server included with Greenstone to work: delete the file lib\java\log4j.properties. (Doing so will ensure that if you execute the gs2-server.bat file–which launches the Greenstone Server Interface–this properties file will be regenerated with the correct value for gsdlhome.)