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

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:

• commands to be typed in a Linux x-term prompt are indicated with $
• Downloading and verifying

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:

• the KEYS file from http://httpd.apache.org/download.cgi and
• the httpd2.2.8.tar.gz.asc from http://www.apache.org/dist/httpd/

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

• Extracting

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

$ tar -xvzf httpd2.2.8.tar.gz

• Installing by compiling

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

• Configuring the server and port

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:

• Add your host server's name in the ServerName section (make sure any other ServerName values are commented out):

ServerName <my.fullservername.location.com>

• Add the port you want your web server to be listening at in the Listen section. Choose a port number that is not in already in use.:

Listen 8080

• Running (starting) and stopping the server

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

• Testing that the web server runs

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.

• Some reading on your part:

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:

• Setting up the apache web server for Greenstone 2

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>

• If you haven't done so already, open up the file $GSDLHOME/cgi-bin/gsdlsite.cfg, and
• Change:

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/"

• Uncomment: #httpprefix /gsdl

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

httpprefix  /gsdl

• And adjust: "httpimg /images" to

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

httpimg     /gsdl/images

• Viewing pages served by Greenstone 2 in your browser

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

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

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.

• Download the binary release of the Apache HTTP server for Windows. I got the "Win32 Binary without crypto (no mod_ssl) (MSI Installer)".
• Double click on the downloaded file–for instance, this may be called apache_2.2.9-win32-x86-no_ssl-r2.msi–and go through the installation wizard. Choose "Typical installation". I accepted Port 8080.
• To start the server, open a DOS prompt and move into the Apache Software Foundation\Apache2.2\bin directory. Once there, type

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.

• Check the server is running by visiting localhost:8080 in a browser. It should show the message "It Works!"
• Edit the file "Apache Software Foundation\Apache2.2\conf\httpd.conf" as follows.

• Make it listen at port 8080 if this is not already set, by finding the "Listen" entry in the file:

Listen 8080

• Set the server name to be the name of your host machine by searching for the "ServerName" entry in the file. (More information can be found in the httpd.conf file where you're making these changes.)

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

• At the end of the httpd.conf file, paste the following and replace $GSDLHOME with the full path to your greenstone 2 installation. Take care to use forward slashes this time, and leave the quote-marks intact where you find them in the following:

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

• Edit the file gsdlsite.cfg located in your $GSDLHOME\cgi-bin as follows:

• Change the GSDLHOME placeholder in the file to be the full path to your Greenstone2 installation. Use Windows style file separators this time (backslashes). For example C:\gsdl.
• Uncomment the "httpprefix" entry to get

httpprefix  /gsdl

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

• You may also need to adjust the "httpimg" entry to:

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.

• Visit http://localhost:8080/gsdl/cgi-bin/library.exe in your browser and hopefully you will now see Greenstone 2's main page. (Or, more generally: http://your-host-name:your-port/your-alias/cgi-bin/library.exe)
• On Windows, there is a local library server which often runs automatically when running the Greenstone Librarian Interface, GLI. To avoid this from interfering with the custom web server you have associated with Greenstone (the Apache web server just configured), you may want to tell it to not start automatically when running GLI.

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)

• VERY IMPORTANT

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.

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

• Additional notes for 2.82, thanks to Diego Spano and Sridhara B
  • Make sure in cgi-bin you have gsdlsite.cfg not gsdlsite.cfg.in. It may be better to rename the file in IIS:

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