Table of Contents

Advanced Server: Greenstone 2

Setting up an Apache Webserver

Setting up an Apache web server to work with Greenstone 2.

Installing the Apache web server on Linux and MacOS (Leopard)

A walkthrough for Linux on how to set up Apache's httpd.2.2.8 web server for Greenstone v2.80. The following should hopefully work with other releases of the Apache's HTTP Server as well.

Notes:

Download the current httpd tar.gz file from http://httpd.apache.org/ e.g. You can go to the mirror site http://ossavant.org/apache and download tar.gz version of httpd2.2.8.

To verify you have an uncorrupted copy of the downloaded file <httpd-version.tar.gz>, you need to download the <httpd-version>.tar.gz.asc file and the KEYS file.

For example:

Now, to verify your download, open an x-term and do as described at http://httpd.apache.org/download.cgi.

For example:

$ gpg --import KEYS
$ gpg --verify <httpd version file name>tar.gz.asc

If you've verified it, extract the contents of the download where you want it:

$ tar -xvzf httpd2.2.8.tar.gz

Now the folder httpd2.2.8 is created. CD into this folder. Inside this folder, there's a README file which points one to the INSTALL file for installation instructions. The following comes from there. First choose the directory where you want to install your apache web server. In the following, PREFIX is the full path to where it will reside.

$ ./configure --prefix=PREFIX
$ make
$ make install

For example, PREFIX might be /home/myname/GS2/apache (no quotes!). In this case, we would do:

$ ./configure --prefix=/home/myname/GS2/apache


$ make


$ make install

Go into your PREFIX folder again (the "apache" folder where you installed the web server). Locate and open the httpd.conf configuration file for editing. That is, open PREFIX/conf/httpd.conf:

ServerName <my.fullservername.location.com>
Listen 8080

To run, type the following in the exterm:

$ PREFIX/bin/apachectl start

To stop it:

$ PREFIX/bin/apachectl stop

If you need to stop then start it up again, you can do both steps in one go:

$ PREFIX/bin/apachectl restart

Running start, stop and restart also works if you're in the PREFIX/bin folder by:

./apachectl start
./apachectl stop
./apachectl restart

For instance, we might do the following to start it using our example prefix:

$ /home/myname/GS2/apache/bin>./apachectl start

Open a browser at http://ServerName:portnumber/ (replace with the values you specified for ServerName and port number in the web server configuration file httpd.conf) and it should work. You will know, if a page loads with the message "It Works!" or some other confirmation message.

If you installed a Binary distribution of Greenstone 2 (GS2), then the installation wizard would have displayed some information with script code on how to set up the web server for GS2: (In the following, $GSDLHOME is the full path to your greenstone installation folder, usually gsdl.) To use the Greenstone Web Library you will need to have a webserver installed (you'll also need perl if you want to build your own collections). The following information is intended to help you configure your webserver for use with Greenstone. Particular attention is given to the Apache webserver which may be downloaded free from www.apache.org. Greenstone will work with other webservers too if that is your preference.

To refer back to this information later you can find it in the file $GSDLHOME/library.txt

Greenstone has been set up to expect $GSDLHOME/GS2 to be accessible from your webserver at the URL http://localhost/gsdl (localhost will of course be the usual web address of your machine if it has one). Likewise, the $GSDLHOME/cgi-bin directory must be accessible as a cgi executable directory.

For the Apache webserver this means adding the following directives to your httpd.conf configuration file:

ScriptAlias /gsdl/cgi-bin "$GSDLHOME/cgi-bin"
  <Directory "$GSDLHOME/cgi-bin">
     Options None
     AllowOverride None
  </Directory>
  
  Alias /gsdl "$GSDLHOME"
  <Directory "$GSDLHOME">
     Options Indexes MultiViews FollowSymLinks
     AllowOverride None
     Order allow,deny
     Allow from all
  </Directory>

Once your webserver is configured in this way you can access Greenstone by pointing your web browser at http://localhost/gsdl/cgi-bin/library or http://your.server.com/gsdl/cgi-bin/library

For more information on installing and configuring a webserver see the Greenstone Installer's guide.

The above is given in the Greenstone 2 installation wizard. We're going to use it now:

Open up the httpd.conf file again. It's in your web server installation's conf folder, i.e. PREFIX/conf/httpd.conf. Append the following at the end, making sure to replace $GSDLHOME with the full path to your Greenstone 2 installation folder (usually the GS2 folder's called gsdl):

ScriptAlias /gsdl/cgi-bin "$GSDLHOME/cgi-bin"
  <Directory "$GSDLHOME/cgi-bin">
     Options None
     AllowOverride None
  </Directory>
  
  Alias /gsdl "$GSDLHOME"
  <Directory "$GSDLHOME">
     Options Indexes MultiViews FollowSymLinks
     AllowOverride None
     Order allow,deny
     Allow from all
  </Directory>
gsdlhome    **GSDLHOME**

to the full path of $GSDLHOME (you can put it in quotes, try this especially if your path contains spaces):

gsdlhome    "/full/path/"

(Make sure that the prefix is the same as the alias registered with your web server.)

httpprefix  /gsdl

(Make sure that the prefix is the same as the alias registered with your web server.)

httpimg     /gsdl/images

Open the browser again at http://ServerName:Portnumber/gsdl/cgi-bin/library

And now you can hopefully see the main page for Greenstone 2.

Installing the Apache web server on Windows

A walkthrough for Windows on how to set up Apache's httpd.2.2.9 web server for Greenstone 2. The following should hopefully work with other releases of the Apache HTTP Server as well.

httpd.exe

To stop it, the Apache HTTP Server online manual says opening a new DOS prompt, going to the Apache server's bin directory and typing the following should stop a running server:

httpd.exe -k shutdown

However, this didn't work for me. You may need to type ctrl-c in the same prompt from where you ran httpd.exe instead. See here for more information.

Listen 8080
ServerName name-of-your-machine

For example, if you're going to test the remote Greenstone server from the same machine–that is, locally–then you can set this value to "localhost":

ServerName localhost
# Setting up the Apache webserver to work with Greenstone2
ScriptAlias /gsdl/cgi-bin "$GSDLHOME/cgi-bin"
  <Directory $GSDLHOME/cgi-bin>
     Options None
     AllowOverride None
  </Directory>
  
  Alias /gsdl "$GSDLHOME"
  <Directory $GSDLHOME>
     Options Indexes MultiViews FollowSymLinks
     AllowOverride None
     Order allow,deny
     Allow from all
  </Directory>

Instead of "gsdl" in the aliases above, you could choose something else (like "gs2remote"), as long as you use it consistently and use the same in the following steps as well.

httpprefix  /gsdl

Make sure the prefix is set to the same value as the alias you chose.

httpimg     /gsdl/images

Once again, make sure to use the script alias you'd chosen above.

If the images do not display in the next step, then come back here and change this back to the way it was before.

Make sure server.exe is not running. Go into your Greenstone2 installation directory. In there you will find either one or both of the following files: # gsdlsite.cfg # glisite.cfg

If the glisite.cfg file is missing, make a copy of the gsdlsite.cfg file and rename the *copy* as glisite.cfg.

Open glisite.cfg, and edit two lines: the line with the property "autoenter" and the line with the property "start_browser". Set both properties equal to 0 as follows:

    autoenter=0
    start_browser=0

The above will prevent the local library server (server.exe) from being launched every time you launch GLI.

You will also want to set the greenstone library path in GLI to connect to the correct web server when previewing collections. You do this in GLI, by going to File > Preferences > Connection tab and setting the value of the Greenstone Web Path field to http://YourServerHostName:PortNumber/gsdl/cgi-bin/library.exe (or http://localhost:9020/AliasYouChoseInStep5Above/cgi-bin/library)

If you are using Lucene as indexer you must add the following line to your httpd.conf file:

PassEnv "USERPROFILE" "ProgramFiles" "TEMP" "OS" "LANG"

Apache needs to know the temp folder to run Lucene queries. Otherway, you will have no results.

IIS

If you would like to run Greenstone with IIS, instead of Apache, these notes may be useful.

After installing the web library version of Greenstone, configure IIS by following these steps:

  1. Visit http://localhost in a web browser to check that IIS is running
  2. Run the IIS configuration program (Control Panel → Administrative Tools → Internet Information Services)
  3. Double-click on the local computer, then Web Sites. Right-click on Default Web Site, choose New → Virtual Directory. Set the Alias to "gsdl" for 2.80/2.81 and earlier versions (and to "greenstone" in or after 2.82), the Content Directory to the directory where you installed Greenstone (eg. C:\Program Files\Greenstone), and allow "Read" and "Browse" permissions only.
  4. Open the new "gsdl" entry, right-click on the "cgi-bin" folder and choose Properties. Enter "Greenstone" as the Application name and choose "Scripts and Executables" for Execute Permissions. Untick "Directory browsing".
  5. IIS 6: Copy the gsdlsite.cfg file from the Greenstone "cgi-bin" folder into the main Greenstone folder. If you have only gsdlsite.cfg.in there (may happen in 2.82), copy it to main folder and rename to gsdlsite.cfg. Edit it and modify the gsdlhome variable to be the location of your top level greenstone folder.
  6. IIS 6: expand Local Computer, click "Web Service Extension", then right-click "All Unknown CGI Extensions" and choose Allow. (Thanks to Victor T. Jones, Jr.)
  7. Close the IIS configuration program.
  8. Make the Greenstone "etc\error.txt", "etc\key.db" (or key.gdb) and "etc\users.db" (or users.gdb) files world-writeable by opening a DOS prompt (Start → Run → cmd.exe) then running:
cacls "C:\Program Files\Greenstone\etc\error.txt" /P Everyone:F

cacls "C:\Program Files\Greenstone\etc\key.db" /P Everyone:F

cacls "C:\Program Files\Greenstone\etc\users.db" /P Everyone:F

If error.txt not there, add and empty file called error.txt and change permissions as described.

You should now be able to access your Greenstone library at http://localhost/gsdl/cgi-bin/library.exe, or, for versions since 2.81, at http://localhost/gsdl/cgi-bin/library.cgi

  1. Go to IIS
  2. Default website
  3. click on cgi-bin virtual directory.
  4. In the right side cgi-bin files are found and rename gsdlsite.cfg.in to gsdlsite.cfg.

Then edit the values like the following: (this assumes installation into C:\greenstone2)

  gsdlhome    c:\greenstone2
  httpprefix  /gsdl
  httpweb     /gsdl/web
  gwcgi       /gsdl/cgi-bin/library.cgi