Installing Greenstone2

For simple instructions, see Compiling Greenstone.

For more detailed instructions and platform specific notes, see Compiling Greenstone Advanced.

For Greenstone 2's SVN urls see Greenstone SVN. To install the source once you've downloaded it from SVN, follow the steps in Compiling the Source for Linux and Installing Greenstone 2 from SVN source on Windows.

For a step by step walkthrough for compilation on Linux, see Installing Greenstone 2 from source for Beginners.

Some helpful related information:

• A walkthrough on how to set up an Apache web server with your Greenstone 2 (for Windows, Linux and Mac Leopard) is at Setting up an Apache Web Server for Greenstone 2 Walkthrough.
• There's a page on some Useful SVN Commands.

Firstly, the local library is only available if you're running Greenstone under Windows. It's not yet available on Unix.

The major difference between the two is that the local library contains it's own built-in webserver. The web library however, requires an external webserver like Apache or Microsoft IIS. This makes the local library much easier to install and configure than the web library.

For this reason, it's recommended that Windows users install the local library unless they're sure that they need the web library. Even if you think you might need the web library, try installing the local library first. You can always uninstall it later and install the web library if you then decide you need it.

A situation where the web library may be preferable is if you plan to serve your Greenstone collections as a full-time service on the web. In this case you'll probably want the added stability that running the web library in conjunction with an external webserver can provide.

Please note that the local library is quite capable of serving Greenstone collections over a local area network or the web (despite its rather misleading name).

Note: we don't use IIS, test Greenstone with it, or recommend it (Apache has a much better security record, and of course it's open source).

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

• Visit http://localhost in a web browser to check that IIS is running
• Run the IIS configuration program (Control Panel → Administrative Tools → Internet Information Services)
• 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.
• 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".
• 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.
• 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.)
• Close the IIS configuration program.
• 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:
• Go to IIS
• Default website
• click on cgi-bin virtual directory.
• 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

Install the GLI applet by following the instructions on this page.

Enable the remote building facility by following the instructions on this page. This is similar to installing the GLI as an applet.

The following instructions were contributed to the Greenstone mailing list by Julian Fox: Upgrading Greenstone 2.x on Linux

It is assumed you are on Linux.

• 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 Source_distribution.

• 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 Source_distribution.

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

If you want to know more about this, see Setting up an Apache Web Server for Greenstone 2 Walkthrough

If you try to run library from the cgi-bin directory and you get a message like ELF binary type "0" not known. ./library: Exec format error. Binary file not executable.

It may be that you need to enable compatibility with linux binaries.

• Enable it in rc.conf:

linux_enable="YES"

• Install linux_base from ports
• Run the command

brandelf -t Linux /home/gsdl/cgi-bin/library (putting the path to your library program)

You need a computer that is permanently connected to the internet and has a webserver program running. We recommend Apache, or you can use IIS or another webserver if necessary. If your organization does not have this kind of computer, you can pay a web hosting company to host Greenstone for you. See below. However you will need to find one that will install Greenstone for you (or allow you to install it yourself) and allow CGI executables to run. Some hosting companies (particuarly cheap ones) do not provide these services.

Once you have access to this computer you need to install the "Web Library" version of Greenstone on it. Next, configure your web server to make Greenstone accessible – instructions for Apache are provided by the Greenstone installer (2.80 and earlier) or see here, and instructions for IIS are available here.

Lastly, copy your collections into this Greenstone installation and check that everything is now accessible from the web.

Answer contributed to the mailing list by Diego Spano.

How easy it is to install Greenstone (GS) will depend a lot on your internet hosting company. They might install Greenstone for you if you ask (it is very strange, but who knows…), or they might give you SSH access to a computer and let you install it yourself (this is the best option).

To install GS on a web server you need terminal access to your hosting company through ssh. When you want to acquire a domain, the company will offer you a varity of options but you have to take in account that you need a dedicated server (aka Virtual private server). A dedicated server allows you to manage what to install and have the freedom of configuring it as you want because you have root access.

Some topics to get GS on a web server, assuming that you have a dedicated server in your hosting company:

• Connect via ssh to the server
• Download Greenstone into the server with wget command or just download it in your computer and upload the installer with FPT or WINSCP.
• Install GS the same way you install in your computer. It is the same installer for local computer and for remote one.
• The web library is installed by default.
• It is very common that your Apache is already installed in your server. So you have to decide if you modify the main Apache configuration to run GS or if you will use GS Apache instead. The main advantage of using GS Apache is that you have it configured because the installer do that job. To check if you have a running Apache installed on the server, you can execute the following on the server (if it's a Linux machine):

ps -aux | grep httpd" or "ps -aux | grep apache2

• If you want to modify your installed Apache, you have to edit /etc/apache2/apache2.conf (or /etc/httpd/httpd.conf) and add the two GS blocks there and restart the service.
• If you want to run GS Apache you only have to run /greenstone installation folder/apache-httpd/linux/bin/apachectl start and it should run.
• Try this url in your browser: http://server_ip_or_host_name/greenstone/cgi-bin/library.cgi. Does it show anything?
• Sometimes hosted web servers have some security restrictions for running cgi scripts. You have to check it if you get any error.

Troubleshooting

• You've configured Apache, but when you try to reach the URL you are redirected to the hosting web page. What kind of hosting did you buy? Perhaps it has Apache running and you are trying to run GS Apache at the same time, this is not possible unless both Apache are in different ports or just stopping one to run the other.