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

• Compiling Greenstone2

Important Note: Before proceeding, you're to set all instructed environment variables in the same terminal, unless explicitly stated otherwise.

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

• For compiling on Windows 64 bit, need the 64 bit version of JDK. For 3.11 and onwards, JDK 8 is needed. For compiling Greenstone 3.06 and onwards, need JDK 7.x or later. For old versions of Greenstone: Java JDK 6.x or later.

C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\VC\Auxiliary\Build\vcvarsall.bat

• 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

:: First: change to using Windows short filenames to allow spaces in the filepath when compiling 
:: For this, need to cd into the folder where this script lives using the short filename path to this folder
:: %0 is this script
:: For the following 2 lines, the spaces between percent sign, tilde and what follows after need to be removed
:: when writing the active command based on those lines. Spaces have been inserted in the following
:: to prevent this script from causing errors about these commented out lines when running.
:: % ~ dp gives the full path to the folder containing this script.
:: % ~ s gives the windows short filename version
:: Combine to get what we want.
:: Note that this will leave the DOS prompt pointing to short filename of the folder
cd "%~sdp0"


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
:: Running VS in 64 bit mode doesn't work for GS2, need to run in 32 bit mode. 
:: (It may be apache httpd that needs 32 bit mode to compile.)
:: For now only VS9.0 (VS2008) works


:: FOR COMPILING GS2 on WINDOWS:
:: OR FOR COMPILING GS3 ON 32 BIT WINDOWS:
:: (if using 64 bit windows to compile GS3, 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 GS3 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



:: TO LOCATE YOUR vcvars32.bat (GS2/GS3) OR vcvarsall.bat (GS3) IN YOUR VISUAL STUDIO INSTALLATION:
:: Different Visual Studio installations can contain the vcvars32.bat and/or vcvarsall.bat in locations
:: different to the above examples. To locate your installation's instances of these scripts:
:: Open a DOS prompt and cd/change directory into your Visual Studio folder. Then use the command: dir /b /s "*search-term*"
:: and specify find the vcvars script by name, e.g.
:: C:\Program Files (x86)\Microsoft Visual Studio>dir /b /s "*vcvarsall.bat*"
:: If such a file exists within your Visual Studio installation, the prompt will return the location, e.g.
::    C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\VC\Auxiliary\Build\vcvarsall.bat
:: Use this result in the "call" command above
:: (and further, only for vcvarsall.bat, but not for vcvars32.bat, pass in: amd64), e.g.
:: call "C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\VC\Auxiliary\Build\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.

1. Get the source component zip file from the downloads page.
2. Unzip it in your Greenstone installation. If Windows prompts you about whether you want existing folders merged (and existing files replaced), tick the box to confirm for all and click in the affirmative.
3. Open a DOS prompt
4. Set up the environment for compiling Greenstone by running the setupenv.bat script described further above: setupenv.bat
5. Go into your Greenstone installation: cd C:\path\to\greenstone2
6. Run the makegs2 script: makegs2.bat for 32 bit windows or makegs2x64.bat for 64 bit windows
7. It will prompt you about whether to extract certain important files. Type Y to do so.
8. It will next present you with various compilation options. You want to type 4 ("All") to tell it to compile everything.
9. It will take some minutes to compile after which, if there are no errors, you can start running GLI or the gs2-server.
10. If you want to recompile GLI go into your Greenstone's gli subfolder: cd gli. Next, type: makegli.bat. To recompile the GLI jar files, such as used for Remote Greenstone situations, type: makejar.bat.

Note: Building collections that use lucene as their indexer requires Java. If you compiled up GS2 using a later version of Java than the version of JRE included in the binary (Java 7), then building a lucene collection may produce error messages about incompatible java versions. In such a case, rename your GS2 installation packages/jre subfolder so that Greenstone no longer finds the bundled JRE. Before re-running GLI to rebuild your lucene collection, ensure that the Java you compiled GS2 with is in the environment (so that JAVA_HOME set to it and its bin folder is on the PATH). Remember to use the same Java environment to launch this GS2 installation's applications in future.

1. Get the source distribution zip file from the downloads page.
2. Unzip it
3. Open a DOS prompt
4. Set up the environment for compiling Greenstone by running the setupenv.bat script described above: setupenv.bat
5. Go into your Greenstone installation: cd C:\path\to\Greenstone2
6. Run the makegs2 script: makegs2.bat for 32 bit windows or makegs2x64.bat for 64 bit windows
7. It will prompt you about whether to extract certain important files. Type Y to do so.
8. It will next present you with various compilation options. You want to type 4 ("All") to tell it to compile everything.
9. It will take some minutes to compile after which, if there are no errors, you can start running the gs2-server.
10. If you want to run GLI as well, this will need to be compiled. To compile it, go into your Greenstone's gli subfolder: cd gli. Next, type: makegli.bat. Once it's done, you can run gli from the commandline with gli.bat from inside the gli folder, or with gli\gli.bat from the toplevel Greenstone installation folder.
11. If you wish to compile up the GLI jar files, such as for Remote Greenstone situations, run the following from within the gli folder: makejar.bat.
12. You will need to enable the Administration pages if you want access to them. Do so by editing your Greenstone installation's etc/main.cfg file. Change the status field value from disabled to enabled. In that case, you may also want to change the admin password for the Adminstration pages. Use a DOS prompt to run: gsicontrol.bat configure-admin which will allow you to (re)set the password for username admin (the default admin password is the same as the username).
13. If you don't already have an imagemagick installed on your system and want to have imagemagick in your GS installation, as imagemagick is used to create thumbnail and screenview size images from your full size images, then grab the pre-compiled imagemagick Windows binary from http://trac.greenstone.org/export/head/gs2-extensions/imagemagick/trunk/imagemagick-windows.zip and unzip it into your compiled up GS2 source distribution folder's bin\windows subfolder, so that you end up with an imagemagick folder in there. Make sure it hasn't created an extra level of an imagemagick subfolder on extraction, like bin\windows\imagemagick\imagemagick. (The dll files should be at the bin\windows\imagemagick level.)

Prerequisites for compiling on Windows:

• Java JDK 6.x or later, JDK 7+ for GS3.06 onwards, and JDK 8 for GS3.11 onwards
• 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.

(NOTE: Some of the prerequisite packages are available from greenstone's svn and are put into a subfolder called local. For instructions on compiling up from source using the local folder, refer to the Windows source installation page
Otherwise, proceed with the following.)

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 the file vcvars<number>.bat, or vcvarsall.bat passing in amd64 for 64 bit windows.

svn co https://svn.greenstone.org/main/trunk/greenstone2 gs2-svn
cd gs2-svn

Then on 64 bit Windows run:

makegs2x64.bat

whereas on 32 bit Windows, you'd need to run:

makegs2.bat

• Choose yes twice
• Choose step 4 to compile ALL without debugging

Check out and compile GLI:

svn co https://svn.greenstone.org/main/trunk/gli
cd gli
makegli.bat
makejar.bat

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

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

• SVN
• ANT
• Java JDK. JDK 7 for Greenstone 3.06 and onwards.
  WARNING: But do not use Oracle's JDK version 1.8.0_161 as it is problematic: failing to compile GS3 and also failing to successfully run the solr web servlet in GS3 binaries. We found that Oracle's JDK versions 1.8.0_144 and 1.8.0_191 worked for us.
• C/C++ compiler: XCode on Mac, gcc/g++ on Linux

1. Download the Source Component tar.gz file that matches with your Greenstone binary version, and put it in your Greenstone installation folder. For Linux/Mac, you want the tar.gz version because the zip version doesn't preserve necessary file permissions.
2. Use a terminal to extract the downloaded file's contents into your Greenstone installation folder:
   

   cd <your greenstone folder>
   tar -xvzf <source-componentfile>

3. Move the ext/gnome-lib-minimal out of the way or rename it to something else.
4. If you want to compile up gnome-lib yourself, skip this step. If you want to use a pre-compiled gnome-lib binary (to save on all the time of compiling gnome-lib), download the gnome-lib-minimal package for your OS by visiting http://trac.greenstone.org/browser/gs2-extensions/gnome-lib/trunk
   Then unzip the downloaded gnome-lib minimal package into your greenstone2-home/ext folder.
5. Make sure JAVA_HOME is set and the bin folders for Java and Perl are on your PATH.
6. Run the following, which will get gnome-lib and compile it up as it's compiling your Greenstone:
   

    ./makegs2.sh gnome-lib
   cd gli
   ./makegli.sh
   ./makejar.sh

   
   Note that some Linux machines don't need gnome-lib at all, in which case, the first compilation step above would just be ./makegs2.sh. To tell whether your Linux machine needs gnome-lib, try compiling it without it first. If compilation fails during wvware, then you need gnome-lib. The Mac Mountain Lion and Leopard machines we tested it on required gnome-lib.
   Note also that, starting with GS2.87 releases, -fPIC is automatically prepended to the CFLAGS environment variable on 64-bit unix systems by the ./makegs2.sh script, as this tends to be needed for compiling.

INSTRUCTIONS FOR OLDER VERSIONS OF GREENSTONE:

• Go to the folder where you unpacked the Greenstone binary distribution. For example, if this folder were called gsdl-2.80-unix:

> cd gsdl-2.80-unix

• Run Install Shield again:

> ./setupLinux.bin

• You already have Greenstone installed, therefore when it asks you whether you want to install it as a web server choose Custom Setup.

• Untick everything. Tick only the Source Code option. If it asks you whether you want to overwrite files you already have, press the No to All button.

• Go into $GSDLHOME – the folder where you installed Greenstone.

> cd $GSDLHOME

See if there is a folder called indexers. If there is none (as is the case with Greenstone 2.80, but it is intended to be included in future Greenstone binary releases), then you need to get it. To get it from SVN (and into the $GSDLHOME folder where you now are):

> svn co http://svn.greenstone.org/indexers/trunk indexers

If you don't know what subversion/SVN is or don't have it installed, then you need to get the indexers folder by downloading the entire Source Distribution and compiling that, see the source install page.

• Now that you are in $GSDLHOME and have the indexers folder in it, you can compile it all by typing the following in an xterm (note that each step can take a few minutes):

> ./configure
> make all
> make install

All going well, this would have compiled it. If you had any difficulties during compilation, see the source install page.

• Still in $GSDLHOME, set up the environment for Greenstone:

> source setup.bash

• To get the Greenstone Librarian Interface (GLI) working, you need to compile that. So go into the gli folder, which is located in $GSDLHOME, and compile GLI:

> cd gli
> ./makegli.sh
> ./makejar.sh

(The above would have compiled GLI and then the last line created the executable jar file from the compiled files.)

You can run GLI with:

> ./gli.sh

Unfortunately there's a non-intrusive bug in Greenstone 2.80's GLI when installed from the source included in the binary distribution. If upon running GLI, you see the following on your xterm:

Running the Greenstone Librarian Interface...
/usr/share/themes/Clearlooks/gtk-2.0/gtkrc:60: Engine "clearlooks" is unsupported, ignoring
Version: 2.80

Exception in thread "AWT-EventQueue-0" java.lang.NullPointerException
        at javax.swing.plaf.synth.SynthContext.getPainter(SynthContext.java:181)
        ....

You can correct the problem above, by

• going to the directory $GSDLHOME/gli/src/org/greenstone/gatherer
• opening its file GathererProg.java in a text editor
• and replacing the line

UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());

with:

UIManager.setLookAndFeel("javax.swing.plaf.metal.MetalLookAndFeel");

• Save the file you just edited.
• Finally, you need to recompile GLI again as explained just above.

• Assuming your web server is set up and running, you can view the pages Greenstone serves from the browser at http://WebServerName:WebServerPort/gsdl/cgi-bin/library

where the WebServerName and WebServerPort are what you specified when you set up your web server.

In the terminal:

• set JAVA_HOME. For GS3, also set ANT_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 JAVA_HOME/bin to PATH
• For GS3, also add ANT_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

1. Download the Source Distribution and extract it. For Linux/Mac, please use the tar.gz version as zip doesn't preserve necessary file permissions.
2. If you want to compile up gnome-lib yourself, skip this step. If you want to use a pre-compiled gnome-lib binary (to save on all the time of compiling gnome-lib), download the gnome-lib-minimal package for your OS by visiting http://trac.greenstone.org/browser/gs2-extensions/gnome-lib/trunk
   Then unzip the downloaded gnome-lib minimal package into your greenstone2-home/ext
3. Make sure JAVA_HOME is set and the bin folders for Java and Perl are on your PATH.
4. Run the following, which will get gnome-lib and compile it up as it's compiling your Greenstone.
   

   ./makegs2.sh gnome-lib imagemagick
   cd gli
   ./makegli.sh
   ./makejar.sh

   
   Note that some Linux machines don't need gnome-lib at all, in which case, the first compilation step above would just leave out the gnome-lib parameter when running the makegs2.sh script above. To tell whether your Linux machine needs gnome-lib, try compiling it without it first. If compilation fails during wvware, then you need gnome-lib. The Mac Mountain Lion and Leopard machines we tested it on required gnome-lib.
   Note that if you already have imagemagick installed on your system or don't need it, you can leave out the imagemagick parameter to the makegs2.sh script.

5. You will need to enable the Administration pages if you want access to them. Do so by editing your Greenstone installation's etc/main.cfg file. Change the status field value from disabled to enabled. In that case, you may also want to change the admin password for the Adminstration pages. Use a DOS prompt to run: gsicontrol.bat configure-admin which will allow you to (re)set the password for username admin (the default admin password is the same as the username).

1. First grab all the source code from SVN by running the following commands in your terminal
   

   svn co https://svn.greenstone.org/main/trunk/greenstone2 greenstone2
   cd greenstone2
   svn co https://svn.greenstone.org/main/trunk/gli

2. If you want to compile up gnome-lib yourself, skip this step. If you want to use a pre-compiled gnome-lib binary, download the gnome-lib-minimal package for your OS by visiting https://trac.greenstone.org/browser/gs2-extensions/gnome-lib/trunk
   Then unzip the downloaded gnome-lib minimal package into your greenstone2-home/ext
3. Compile up Greenstone:
   

   ./makegs2.sh gnome-lib
   cd gli
   ./makegli.sh
   ./makejar.sh

4. You will need to enable the Administration pages if you want access to them. Do so by editing your Greenstone installation's etc/main.cfg file. Change the status field value from disabled to enabled. In that case, you may also want to change the admin password for the Adminstration pages. Use a DOS prompt to run: gsicontrol.bat configure-admin which will allow you to (re)set the password for username admin (the default admin password is the same as the username).

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

1. Give the binary of the installer execute permissions
2. Then run it by passing in the text-only flag.
3. Follow the instructions on the screen thereafter. If you mistype at any stage, press ctrl-C to start again.

> ./Greenstone-2.87-linux text-only
----------------------------
Extracting java installer...
----------------------------

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

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.)