//**This page is in the 'old' namespace, and was imported from our previous wiki. 
We recommend checking for more up-to-date information using the search box.**//

====== Installing Greenstone2 from Source for Beginners ======

Instructions valid for 2.80.

This is more like a worked example of an installation. It gives a long, extended explanation with extra hand-holding, for people who want all the steps inbetween. 


Some specifics on what it does and does not cover:
  * Installation from source on Linux only
  * It assumes you have the correct C/C++ compiler installed
This document may therefore particularly help people new to the University of Waikato's DL lab, as they're working on Linux and will probably be using the correct compiler by default.


Greenstone 2 will be referred to as GS2. 
And $ is an xterm prompt.


===== Where to get the source to install from =====
You have two options, 
  - You can get the source code from the downloaded Binary distribution for Unix/Linux. 
  - You can download the Source Distribution for GS2 


===== Unix/Linux distribution (Binaries) =====

  * Download the distribution from Unix/Linux distribution from http://www.greenstone.org/download

  * Download the [[http://prdownloads.sourceforge.net/greenstone/Install-en.pdf|Installer's Guide, Install-en.pdf]] also off http://www.greenstone.org/ 

  * [[http://www.greenstone.org/download|The Download Greenstone]] page states: 
<blockquote>"To install this distribution, extract the gzipped tar archive and run the setupLinux.bin Java-based Installer program."</blockquote>
For instance, if the downloaded tarzip is called gsdl-2.80-unix.tar.gz:
<code>$ tar -xvzf gsdl-2.80-unix.tar.gz</code>
Go into the new folder created (e.g. gsdl-2.80-unix) and ls to see that setupLinux.bin is there. Then run it:
<code>$ cd gsdl-2.80-unix
$ ./setupLinux.bin</code>

  * That will start the GS2 installation wizard (InstallShield):
  * Make sure to choose Custom setup. 
  * Tick everything in Custom setup, including source code - because this is what we want.

  *  I am assuming that your installation directory is called **gsdl** (this is the usual case) but perhaps you've installed it elsewhere. Your installation directory will be referred to in the rest of this article as **$GSDLHOME**.

  *  Go into $GSDLHOME and look for the folders **src** and **indexers**. Folder **src** should now be there as we chose to install the source code. But depending on your GS2 Unix/Linux distribution version, folder **indexers** may be missing. If so, you'll need to download the Source distribution as explained in the section below and follow the steps from there onwards (or you can move the **indexers** folder from the extracted Source distribution and put it into $GSDLHOME and skip onto the section [[#Compiling the Source]]). 




===== Source distribution =====

  * Download the Source Distribution from http://www.greenstone.org/download. 
For instance, I tried the source distribution for [[http://prdownloads.sourceforge.net/greenstone/gsdl-2.80-src.tar.gz|GS2 version 2.80]]

  * Untar it to extract:
<code>$ tar -xvzf gsdl-2.80-src.tar.gz</code>
The **indexers** folder should now be there in the extracted **gsdl** folder. Folder gsdl will be referred to as **$GSDLHOME** from now on.




== Compiling the Source == 
This assumes your compiler is compatible, for further details on this matter, see 
[[Installing Greenstone]]. 


Also make sure that JAVA_HOME is set. On Macintosh machines Java tends to come installed these days (Mac OS Leopard) and is usually located at 
<code>/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home</code>
For a MAC, if your source code was from SVN, gdbm (Gnu Database Manager) will not be included and you will need to get it. You can download this [[http://www.linuxfromscratch.org/blfs/view/stable/general/gdbm.html|from here]].

==== For Macs: Installing GDBM ==== 

  * Open a console window and decompress the gdbdm tar file:
<code>> tar -xvzf gdbm-<version>.tar.gz</code>

  * Compile it with the prefix set to the parent directory of the unzipped gdbm folder. For instance, if you unzipped gdbm into $GSDLHOME, then your gdbm folder would be located in $GSDLHOME. Move into the gdbm folder and compile it with
<code>> ./configure --prefix=/path/to/parentfolder/of/gdbmfolder

> make
</code>
The make install step is different in that you need to provide your user and group names:
<code>> make BINOWN=your-user-name BINGRP=your-group-name install</code>
To find out what group(s) you belong to, type the following in an x-term:
<code>> groups</code>



==== Compiling Greenstone 2 ==== 

  * If you're on Linux, go to the $GSDLHOME folder and type
<code>$ ./configure
$ make
$ make install</code>
If it complains about **gdbm** or **usr/local** while compiling, then you need to find the path to **gdbm** first (assuming you're still in $GSDLHOME):
<code>$ find . -name "gdbm"</code>
Hopefully this will find the location of gdbm for you and you can use this path in the configuration and make again, as shown below. If you're on a **Mac OS**, you would similarly need to provide the location of gdbm's folder when compiling it up as follows. (If that doesn't work, then try specifying the parent folder of the gdbm folder instead.)
<code>$ ./configure --with-gdbm=/full/path/to/parentfolder/of/gdbmfolder
$ make
$ make install
</code>
If you still have difficulties compiling, looking at the [[Compiling Greenstone Advanced]] page may help you.

  * Still in $GSDLHOME, set up the environment for GSDLHOME:
<code>$ source setup.bash</code>

  *  Now you're set up. To view the Greenstone pages in your web server, you need to do the following:

  * You need set up your web server to work with GS2. [[Setting up an Apache Web Server for Greenstone 2 Walkthrough]] is a walkthrough that may help you if you haven't done this step yet.
In your apache web server httpd.conf file, add the following (unless you already added it), making sure to adjust the 4 occurrences of $GSDLHOME below to its full path:
<code>#Greenstone 2 script:
  ScriptAlias /greenstone/cgi-bin "$GSDLHOME/cgi-bin"
  <Directory "$GSDLHOME/cgi-bin">
     Options None
     AllowOverride None
  </Directory>
  
  Alias /greenstone "$GSDLHOME/"
  <Directory "$GSDLHOME/">
     Options Indexes MultiViews FollowSymLinks
     AllowOverride None
     Order allow,deny
     Allow from all
  </Directory>
</code>
**NOTE:** You can choose a prefix for the alias other than **greenstone**--for example, gs2remote--as long as whatever you chose is what you will use below.

  * In the file $GSDLHOME/cgi-bin/gsdlsite.cfg, 
  * Change: 
<code>gsdlhome    **GSDLHOME**</code>
to the full path of $GSDLHOME (you can put it in quotes, try this especially if your path contains spaces):
<code>gsdlhome    "/full/path/"</code>
  * In Greenstone versions GS2.81 and older, you will need to **uncomment** the line: ''#httpprefix  /gsdl''
to get:
<code>httpprefix  /sdl</code>
And you'll need to adjust: "httpimg /images" to
(In both cases, make sure that the prefix is the same as the alias registered with your web server.)
<code>httpimg     /gsdl/images</code>

  * Make sure your webserver is running and open your browser at:
<code>http://WebServerName:WebServerPort/gsdl/cgi-bin/library</code>
Or, if installed locally, try:
<code>http://localhost:WebServerPort/gsdl/cgi-bin/library</code>



  *  Now you need to compile the Greenstone Librarian Interface, GLI. So go into the **gli** folder in $GSDLHOME and run makegli.sh to compile:
<code>$ cd gli
$ ./makegli.sh</code>
  *  To run the GLI application:
<code>$ ./gli.sh</code>
  * Once it has started up for the first time, a dialog box pops up asking for you to "Enter value".


It wants the Greenstone browser url (see [[Setting up an Apache Web Server for Greenstone 2 Walkthrough]]):


http://WebServerName:WebServerPortnumber/gsdl/cgi-bin/library


where gsdl/cgi-bin is the Alias specified in your Apache web server installation's configuration file - /path/to/apache-webserver-installation-folder/conf/httpd.conf.



===== Troubleshooting =====

  * When on **Ubuntu**, if the compilation of **wget** fails with a message saying that **msgfmt** could not be found (followed by a listing of compile Error messages for wget), then you need to install msgfmt. In order to find out how you can install msgfmt, open a new xterm and type
<code>msgfmt</code>
It will hopefully tell you that you need to install this package first and tell you how to do it. If you have admin rights, you can follow the instructions that it provides to install msgmft. Once installed, execute the **make** command again and hopefully GS2 compilation will complete successfully now.