Differences

This shows you the differences between two versions of the page.

--- en:user_advanced:installation_310 [2025/07/14 22:25] – created kjdon
+++ en:user_advanced:installation_310 [2025/07/15 00:06] (current) – kjdon
@@ Line 1: / Line 1: @@
 ====== Advanced Installation : 3.10 and prior ======
 //Up to date for GS3.10, checked 20 Feb 2021.
 This page is up to date for 3.06 (5 November 2014). Much of it was checked again to be up to date after 3.08.//
+[[en:user_advanced:installation|Advanced Installation Index Page]] - from here you can access different versions of this page.
 For most users, the main Greenstone download (also called the "binary") with default settings is sufficient, and is very [[en:beginner:install_basic|easy to install]]. However, there are some instances where you may want or need to go through a more advanced installation process:
@@ Line 24: / Line 21: @@
-  * [[en:developer:compiling_greenstone|Compiling Greenstone]]
+  * [[en:developer:compiling_greenstone3|Compiling Greenstone3]]
@@ Line 99: / Line 96: @@
 To make it easier for developers, a batch file containing placeholders you can adjust is already prepared and discussed at [[http://wiki.greenstone.org/doku.php?id=en:developer:windows_source_install|Source Installation on Windows]].
 ==== Source Component ====
-<tabbox Greenstone3>
 **Note:** Greenstone 3 does not at present compile successfully if it was installed in a place containing spaces. The solution is to move the installed GS3 folder out into a different location, one without spaces in the filepath, //before// compiling. Once compiling is done, you can move your installed GS3 folder back to its original location.
@@ Line 122: / Line 119: @@
 Therefore, to run GLI after compiling GS3 for 64 bit, add the bin folder of JRE 7 for 64 bit to the PATH, or set JAVA_HOME to JDK 7 64 bit and add its bin folder to the PATH. Then run GLI in this environment.
-<tabbox Greenstone2>
-  - Get the source component zip file from the downloads page.
-  - 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.
-  - Open a DOS prompt
-  - Set up the environment for compiling Greenstone by running the setupenv.bat script described further above: ''setupenv.bat''
-  - Go into your Greenstone installation: ''cd C:\path\to\greenstone2''
-  - Run the makegs2 script: ''makegs2.bat'' for 32 bit windows or ''makegs2x64.bat'' for 64 bit windows
-  - It will prompt you about whether to extract certain important files. Type Y to do so.
-  - It will next present you with various compilation options. You want to type 4 ("All") to tell it to compile everything.
-  - It will take some minutes to compile after which, if there are no errors, you can start running GLI or the gs2-server.
-  - 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''.
+==== Source Distribution ====
-**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.
-</tabbox>
-==== Source Distribution ====
-<tabbox Greenstone3>
   - Get the source distribution zip file from the downloads page.
   - //Unzip it in a location with no spaces in the filepath.//
@@ Line 150: / Line 133: @@
 To run GLI or the gs3-server after compiling the source code on a 64 bit Windows machine, you need your environment to be set up with JDK 7+ (or JRE 7+) for 64-bit and Ant: set the JAVA_HOME environment variable to your 64 bit JDK and add the JDK's ''bin'' folder to the PATH. Also set the ANT_HOME environment variable and add its ''bin'' folder to the PATH. Then run GLI or gs2-server in this environment using the gli.bat and gs2-server.bat scripts.
-<tabbox Greenstone2>
-  - Get the source distribution zip file from the downloads page.
-  - Unzip it
-  - Open a DOS prompt
-  - Set up the environment for compiling Greenstone by running the setupenv.bat script described above: ''setupenv.bat''
-  - Go into your Greenstone installation: ''cd C:\path\to\Greenstone2''
-  - Run the makegs2 script: ''makegs2.bat'' for 32 bit windows or ''makegs2x64.bat'' for 64 bit windows
-  - It will prompt you about whether to extract certain important files. Type Y to do so.
-  - It will next present you with various compilation options. You want to type 4 ("All") to tell it to compile everything.
-  - It will take some minutes to compile after which, if there are no errors, you can start running the gs2-server.
-  - 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.
-  - 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''.
-  - 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).
-  - If you don't already have an imagemagick installed 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.)
-</tabbox>
@@ Line 183: / Line 151: @@
 which can be accomplished using the file ''vcvars<number>.bat'', or ''vcvarsall.bat'' passing in ''amd64'' for 64 bit windows.
-<tabbox Greenstone3>
 Run the following:
 <code>
@@ Line 191: / Line 158: @@
 ant install
 </code>
-<tabbox Greenstone2>
-Then run:
-<code>
-makegs2.bat
-</code>
-  * Choose yes twice
-  * Choose step 4 to compile ALL without debugging
-</tabbox>
 For more detailed instructions on source installation, please refer to the
@@ Line 212: / Line 172: @@
 ==== Source Component ====
-<tabbox Greenstone3>
   - Download and extract the Source Component for your Operating System into the top-level folder of your Greenstone 3 binary installation. For Linux/Mac, download the tar.gz version as zip doesn't preserve necessary file permissions.
   - Set up ant and Java: set JAVA_HOME (to JDK 7 for Greenstone 3.06, JDK 8 for Greenstone 3.11 onwards) and add its ''bin'' folder to the PATH. If you're on a 64 bit machine, you'll need a JDK for 64 bit machines, if you're on a 32 bit machine, you will need a JDK for 32 bit machines. Set ANT_HOME and add its ''bin'' folder to the PATH. If you don't already have ant installed, the Greenstone 3 binary comes with one in its ''packages/ant'' folder. Set that to ANT_HOME, and add its ''bin'' subfolder to the PATH.\\ <code>
@@ Line 246: / Line 206: @@
 The gnome-lib environment may conflict with graphical applications on Linux systems. After compiling, open a fresh terminal to run GLI or other graphical applications. But make sure the new terminal has the environment set up for Java and Ant too before running any Greenstone applications like the Greenstone Server (gs3-server) and GLI.
-<tabbox Greenstone2>
-  - 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.
-  - Use a terminal to extract the downloaded file's contents into your Greenstone installation folder: \\ <code>cd <your greenstone folder>
-tar -xvzf <source-componentfile>
-</code>
-  - Move the ''ext/gnome-lib-minimal'' out of the way or rename it to something else.
-  - 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.
-  - Make sure JAVA_HOME is set and the bin folders for Java and Perl are on your PATH.
-  - Run the following, which will get gnome-lib and compile it up as it's compiling your Greenstone: \\ <code> ./makegs2.sh gnome-lib
-cd gli
-./makegli.sh
-./makejar.sh
-</code> \\ **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:
-<code>> cd gsdl-2.80-unix</code>
-  * Run Install Shield again:
-<code>> ./setupLinux.bin</code>
-  * 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.
-<code>> cd $GSDLHOME</code>
-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):
-<code>> svn co http://svn.greenstone.org/indexers/trunk indexers</code>
-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 [[en:user_advanced:installation|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):
-<code>> ./configure
-> make all
-> make install
-</code>
-All going well, this would have compiled it. If you had any difficulties during compilation, see the [[en:user_advanced:installation|source install]] page.
-  * Still in $GSDLHOME, **set up the environment for Greenstone**:
-<code>> source setup.bash</code>
-  * 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**:
-<code>> cd gli
-> ./makegli.sh
-> ./makejar.sh
-</code>
-(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:
-<code>> ./gli.sh</code>
-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:
-<code>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)
-        ....
-</code>
-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
-<code>UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());</code>
-with:
-<code>UIManager.setLookAndFeel("javax.swing.plaf.metal.MetalLookAndFeel");</code>
-  * 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 [[en:user_advanced:gs2_server| set up your web server]].
-</tabbox>
 ==== Source Distribution ====
@@ Line 340: / Line 224: @@
 </code>
-<tabbox Greenstone3>
   - Download the Source Distribution for your Operating System and extract it into the location where you want Greenstone installed. For Linux/Mac, download the tar.gz version as zip doesn't preserve necessary file permissions.
   - Make sure JAVA_HOME is set (to JDK 7 for Greenstone 3.06, JDK 8 from Greenstone 3.11 onwards) and that its ''bin'' folder is added to the PATH. If you're on a 64 bit machine you need a JDK for 64 bit machines, if you're on a 32 bit machine, you will need a JDK for 32 bit machines. Also set ANT_HOME to an ant installation and add its ''bin'' folder to the PATH.
@@ Line 371: / Line 255: @@
-<tabbox Greenstone2>
-  - Download the Source Distribution and extract it. For Linux/Mac, please use the tar.gz version as zip doesn't preserve necessary file permissions.
-  - 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
-  - Make sure JAVA_HOME is set and the bin folders for Java and Perl are on your PATH.
-  - Run the following, which will get gnome-lib and compile it up as it's compiling your Greenstone.\\ <code>
-./makegs2.sh gnome-lib imagemagick
-cd gli
-./makegli.sh
-./makejar.sh
-</code> \\ **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.
-  - 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).
-</tabbox>
 ==== Uptodate source code from SVN ====
-<tabbox Greenstone3>
   - Make sure you have SVN installed and on your Path
@@ Line 435: / Line 306: @@
 </code>
-<tabbox Greenstone2>
-  - First grab all the source code from SVN by running the following commands in your terminal \\ <code>
-svn co http://svn.greenstone.org/main/trunk/greenstone2 greenstone2
-cd greenstone2
-svn co http://svn.greenstone.org/main/trunk/gli
-</code>
-  - 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 http://trac.greenstone.org/browser/gs2-extensions/gnome-lib/trunk \\ Then unzip the downloaded gnome-lib minimal package into your greenstone2-home/ext
-  - Compile up Greenstone: \\ <code>
-./makegs2.sh gnome-lib
-cd gli
-./makegli.sh
-./makejar.sh
-</code>
-  - 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).
-</tabbox>
@@ Line 467: / Line 324: @@
 **NOTE:** Previously, the instructions for running the installer in text-only mode were incorrect. They advised running the installer wrongly using ''./Greenstone-3.06rc1-linux-x64 text-only'', which rather triggered the default behaviour of the installer software (antinstaller) for a different kind of text-only installation rather than triggering the Greenstone installer's specific -textonly mode. Unfortunately, the wrong route would not install the bundled JRE into the Greenstone installation, despite requiring the Greenstone user to run the ''java'' command in the very next step of the install.
-===== Installation for a networked lab environment =====
-To support use of Greenstone 3 in a networked lab environment, it is possible to adjust the configuration settings of the installation to have one shared installation of the software, but allow individual
-users to build and serve collections from their own area of the file system.  We refer to this as a "dispersed GS3" setup.
-More specifically, it is appropriate for a situation where your Greenstone 3 is to be distributed across 3 locations of your Windows machine: an installation location which is read-only regular users, and to which only the administrator has write permissions; a user-web location that is writable and specific to a user; and a temporary (typically local) file system area the user has read/write permissions to.
-In the following text we describe the setup procedure for Windows, with
-Greenstone installed in C:/Program Files/.  The same capability will work in networked situations
-for MacOS and Linux labs, choosing an appropriate directory such as /usr/local/Greenstone3
-as the location to install the GS3 software to.
-For one computer, here's how you can have Greenstone installed centrally (e.g. Program Files), but then have each different user when working at that computer have their own instance of the Greenstone 3 sites, collections, and customisations of the interface.
-Install GS3 as an administrator using the binary installer. Then set the following 4 properties in build.properties:
-  * set ''using.user.web=true''
-  * set ''web.home=${user.home}/greenstone3/web''\\ [[https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html|Java's user.home property]] should resolve to a writable user location, e.g  web.home will work out to be something like C:/Users/me/greenstone3/web). You can decide on other locations within ${user.home}, as you choose. For example, you can set web.home=${user.home}/gs3/myweb. \\ Or if your lab setup is such that you're mounting each user's account at H: at each log in, then just set web.home=H:/gs3/web. Then, whenever any user is logged in, their collection data will be in H:/gs3/web. So web.home in such a case may look static and fixed to somewhere in H: in the build.properties file, but it's actually not static, since it changes to refer to different users' accounts based on who is logged in.
-  * set ''gsdl3home.isreadonly=true''
-  * set ''gsdl3.writablehome=${java.io.tmpdir}/greenstone/web''
-Set all the property values exactly as above, except ''web.home'', which you should customise to point to a location that is writable by the GS3 user where the user can create collections. File path separators should be URL style slashes, so forward slash, /.
-Now if you replicate the installation to other machines in the lab, your users can log into any machine and continue working with Greenstone3.
-<!--
-greenstone-307.cmd file contains:
-@goto %1
-:start
-robocopy /e /purge /np image "C:\Program Files\Greenstone3" /log:image.log
-if %ERRORLEVEL% GEQ 4 fail
-robocopy /e /xx /np patches "C:\Program Files\Greenstone3" /log:patches.log
-if %ERRORLEVEL% GEQ 4 fail
-robocopy /e /purge /np startmenu "%ALLUSERSPROFILE%\Start Menu\Programs\Greenstone 3" /log:startmenu.log
-if %ERRORLEVEL% GEQ 4 fail
-done
--->
-===== Source Code Stability =====
-Note: This page is aimed at Greenstone developers.
-The source code stability system attempts to provide developers with a constant stable code base for development even as the main trunk passes between stable and unstable states. If you are doing development on a working copy of the trunk, but the trunk has bugs which prevent it compiling or running, then it can be very hard to test your changes. Rather than spend time inquiring into those bugs, the stability system gives you a way to temporarily roll your working copy back to the last stable state. Once you have finished testing your changes, you can then roll you working copy forward again and commit your changes. Except in the case where other developers have made significant changes to the trunk, your changes will start working once the trunk is stable again.
-The stability system works by periodically checking out the trunk and testing it for stability, then creating a 'stable' tag if and only if the trunk passes these stability tests. For now the stability tests are as simple as checking that the release kits on all three main operating systems were able to successfully create a release from the trunk. In the future, these checks could be extended to include regression tests, installer tests, tests to the runtime system and anything else which might further 'prove' the stability of the trunk. Stable tags related to Greenstone2 are named 'stable' and stable tags related to Greenstone3 are named 'stable3'.
-To make your working copy stable, change to the root directory of the working copy and run one of these commands:
-<code>
- (For Greenstone2): svn switch http://svn.greenstone.org/gsdl/stable
- (For Greenstone3): svn switch http://svn.greenstone.org/greenstone3/stable3
-</code>
-Or to checkout a fresh stable working copy, run one of these commands:
-<code>
- (For Greenstone2): svn checkout http://svn.greenstone.org/gsdl/stable gsdl
- (For Greenstone3): svn checkout http://svn.greenstone.org/greenstone3/stable3 greenstone3
-</code>
-Then test your changes and/or keep working on them. Once you are ready to commit your changes, switch back to the trunk:
-<code>
- (For Greenstone2): svn switch http://svn.greenstone.org/gsdl/trunk
- (For Greenstone3): svn switch http://svn.greenstone.org/greenstone3/trunk
-</code>
-And commit as normal.
-**Note**: The stable tags are read-only. (Only the nightly tasks that create the stable tags can write to them.) This is for good reason; allowing commits to the stable tag would be lost the next time the trunk was tagged as stable.
-The projects 'gli', 'gs2build', 'indexers' and 'documentation' also have stable tags.
-You can execute a command like the following to switch to the stable tag for one of
-these projects:
-''svn switch <nowiki>http://</nowiki>svn.greenstone.org/**//project-name//**/stable[3]''
-And switch back with:
-''svn switch <nowiki>http://</nowiki>svn.greenstone.org/**//project-name//**/trunk''
-**Note**: Though the stable branches are in separate locations in the repository, they should be considered as one unit. To get a //bona fide// stable working copy, each project which made up the working copy would have to be switched to the stable tag of the project. Mixing of 'stable' and 'stable3' tags would also prevent a working copy from being a //bona fide// working copy.
-===== Moving a Greenstone installation =====
-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:
-  - 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.
-  - 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.
-  - 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.)