Changeset 13383


Ignore:
Timestamp:
2006-11-30T16:25:13+13:00 (17 years ago)
Author:
kjdon
Message:

brought these files a bit more up to date

Location:
trunk/gsdl3
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/gsdl3/README-CVS.txt

    r10884 r13383  
    3030--------------------------------------------------------------
    3131
    32 Greenstone 3 uses some parts of Greenstone 2 for collection building using the Librarian Interface. These will be installed during the Greenstone 3 installation process. If you have Greenstone 2 already installed and want to use that version instead (or don't want to use it at all), please set the gsdl2.installed.path property (in build.properties) to be the root of your Greenstone 2 installation, or any non-empty string. Greenstone 3 will then use this installation rather than its own version. (Note, be careful about compatibility between versions.)
     32Greenstone 3 uses some parts of Greenstone 2 for collection building,
     33including external packages and the Librarian Interface. These will be
     34installed during the Greenstone 3 installation process. If you do not want
     35collection building capability, please set the disable.collection.building property to true in build.properties.
    3336
    3437
    … …  
    7679cd greenstone3
    7780cvs update -l
    78 cvs update -dP extensions bin docs lib resources src winutil packages
     81cvs update -dP bin docs lib resources src winutil packages
    7982cd web (or the path-to-tomcat/webapps/greenstone3 if have installed greenstone as a webapp in Tomcat, see Using External Tomcat section)
    8083cvs update -dP
    81 cd greenstone3
     84cd ../
    8285[ if you have greenstone 2 building:
    8386cvs update -dP gli

  • trunk/gsdl3/README.txt

    r11291 r13383  
    1414do various things like compile the source code, start up the server etc.
    1515
    16 On GNU/Linux MySQL seems to have trouble with spaces in paths, so it's best to install Greenstone into a path with no spaces.
    17 
    1816Installing Greenstone
    1917---------------------------------------------------------
    2018
    21 Download the appropriate zip/tar file (greenstone-3.xx-linux.tar.gz/greenstone-3.xx-win32.zip/greenstone-3.xx-macOSX.tar.gz) from sourceforge.net/projects/greenstone3, and unzip/untar it. In the greenstone3 directory, edit the build.properties file (see 'Configuring your installation' below), and run 'ant install'.
    22 
    23 See 'Using External Tomcat' and 'Using External MySQL' sections below if you want to use an existing version.
     19[TODO: check once release is done]
     20Download the appropriate installer from sourceforge.net/projects/greenstone3 and run it.
    2421
    2522See 'Installing from a Source Distribution' section below for extra notes about installing from Source.
    2623
    2724See the README-CVS.txt file for extra notes about installing from CVS.
    28 
    29 Configuring your installation:
    30 --------------------------------------------------------
    31 
    32 The file build.properties contains various parameters that can be set by the user. Please check these settings before running the install.
    33 Note, either forward slash '/' or double backslash '\\' can be used as path separators in the build.properties file, but not single backslash '\'.
    34 
    35 Greenstone 3 comes with MySQL and Tomcat bundled in. 
    36 
    37 If you already have Tomcat running, you can set the 'tomcat.installed.path' property (in build.properties) to the base directory of your Tomcat installation, and Greenstone will not use its own Tomcat. (You can delete the packages/tomcat directory if you like.) Please read the section "Using External Tomcat" for details about how to configure Tomcat for Greenstone.
    38 
    39 Greenstone 3 uses MySQL for the collection database (with Greenstone 3 native building). If you already have MySQL installed, set the 'mysql.installed.path' property (in build.properties) to the base directory of your MySQL installation, and Greenstone will not use its local MySQL. (You can delete the packages/mysql directory if you like.) Please read the section "Using external MySQL server" for details about how to configure MySQL for Greenstone.
    40 
    41 If you are using MySQL that comes with greenstone 3, and you are installing greenstone 3 on an NFS drive, MySQL may not work properly (it has problems removing locks on its data files). After installation, copy the data directory from greenstone3/packages/mysql to a local drive, then set the path to this directory in the mysql.datadir property in build.properties.
    42 If the version of MySQL that greenstone is using is not suitable for your setup (see notes on versions below), please install an appropriate version and set the mysql.installed.path property.
    43 
    44 Mac OS X: You need to have GDBM installed (http://www.gnu.org/software/gdbm/gdbm.html). Please set the gdbm.installed.path property (in build.properties) to the root of your gdbm installation if it is not installed in a default place. If you run GLI or GS2 collection building from the command line, you will need to set the DYLD_LIBRARY_PATH environment variable to include <path-to-gdbm>/lib.
    45 
    46 The install target will ask you if you accept the properties before starting.
    47 To suppress this prompt, use the -Dproperties.accepted=yes flag. E.g.
    48 ant -Dproperties.accepted=yes install
    49 
    50 To log the output in build.log, run
    51 ant -Dproperties.accepted=yes -logfile build.log  install
    5225
    5326Running Greenstone:
    5427---------------------------------------------------------
    5528
    56 To startup the local servers (Tomcat adn/or MySQL), run 'ant start'.
    57 'ant restart' and 'ant stop' restarts and shuts down the servers.
    58 To start or stop just Tomcat or MySQL, use the start-tomcat, start-mysql, stop-tomcat, stop-mysql targets.
    59 These will only start/stop local servers (ones installed by Greenstone). You will need to manually start/stop external Tomcat/MySQL. if you are using both external Tomcat and external MySQL, then the start, restart, stop targets do nothing.
    60 
    61 Once the Tomcat server is running, Greenstone will be available in a browser at "http://localhost:8080/greenstone3".
     29To start up the local Tomcat server, run 'ant start'.
     30'ant restart' and 'ant stop' restarts and shuts down the server.
     31This will only start/stop a local server (one installed by Greenstone). You will need to manually start/stop external Tomcat.
     32
     33Once the Tomcat server is running, Greenstone will be available in a browser at "http://localhost:8080/greenstone3" (or whatever port you specified during the
     34installation process).
    6235You can change the port number by changing the 'tomcat.port' property in build.properties, then running 'ant configure'.
    6336
    64 MySQL is only needed if you want to use the GS3MGDemo collection, or if you want to build collections using Greenstone3 native collection building.
    65 
     37[TODO: notes about running server program]
    6638
    6739Building Collections:
    6840----------------------------------------------------------
    6941
    70 You can build collections using either Greenstone 2 style building, or native Greenstone 3 style.
    71 
    72 Greenstone 2 style:
    73 
    74 You need to have Perl installed and on your PATH. Perl is included as part of the Windows binary distribution.
    75 run  'ant gli", or cd to greenstone3/gli and run gli4gs3.sh/bat. This is a graphical tool for building collections. Once you have created and built a collection, you can see it by clicking 'Preview collection' on the Build panel.
    76 
    77 Note that GLI doesn't start up the Greenstone server (Tomcat/MySQL) so you should run 'ant start' before previewing your collection.
    78 
    79 Greenstone 3 style:
    80 
    81 In the greenstone3 directory, run: 'source gs3-setup.sh' (GNU/Linux, Mac OS X) or 'gs3-setup' (Windows).
    82 To create a new collection, run 'gs3-mkcol.sh/bat <sitename> <collname>'
    83 Put documents in the import directory (greenstone3/web/sites/<sitename>/collect/<collname>/import), edit the collection configuration file (greenstone3/web/sites/<sitename>/collect/<collname>/etc/collectionConfig.xml), and run 'gs3-build.sh <sitename> <collname>'
    84 Rename the building directory to index (in greenstone3/web/sites/<sitename>/collect/<collname>) and reload the collection in Tomcat (?a=s&sa=a&st=collection&sn=<collname>), or restart Tomcat.
    85 
    86 See the manual for more details about both styles of collection building.
    87 
    88 Recompiling
    89 -------------------------------------------------------
    90 To recompile your Greenstone3 installation, in the top level greenstone3 directory, run:
    91 
    92 ant configure
    93 ant configure-c++
    94 ant clean
    95 ant compile
    96 
    97 The compile target, under GNU/Linux and Mac OS X, does Java and C/C++ compilation. For Windows, since Visual Studio is not a standard component, only Java compilation is carried out. Pre-compiled binaries are provided for the C/C++ components (src/packages and Greenstone 2 style building). If you have Visual Studio installed (version 6), you can run the compile-windows-c++ targets to compile the code locally. (Don't forget to setup the Visual Studio environment first, by running, e.g. C:/Program Files/Microsoft Visual Studio/VC98/Bin/VCVARS32.BAT or equivalent.)
    98 
    99 Any sub targets can be run by themselves. Run 'ant -projecthelp' for a list of public targets, otherwise you can look at the build.xml file to see which targets depend on other ones.
    100 
    101 If you run your install using an external Tomcat, the SOAP web service for localsite (used by the gateway servlet) will not be loaded. You need to start up Tomcat, then run 'ant soap-deploy-site' and accept the defaults for sitename and siteuri (both localsite). If you want to use the gateway servlet without restarting Tomcat, you will need to reload the site information. Visit the URL http://localhost:8080/greenstone3/gateway?a=s&sa=c  (substituting your server name and port number if necessary). See the user guide for more information about run time reconfiguration.
    102 
     42You need to have Perl installed and on your PATH. Perl is included as part of
     43the Windows binary distribution.
     44run  'ant gli", or cd to greenstone3/gli and run gli4gs3.sh/bat. This is a
     45graphical tool for building collections. Once you have created and built a
     46collection, you can see it by clicking 'Preview collection' on the Build panel.
     47
     48Note that GLI doesn't start up the Greenstone Tomcat server so you should
     49run 'ant start' before previewing your collection.
     50Greenstone Admin
     51------------------------------------------------------
     52
     53[TODO: notes about admin tool]
    10354
    10455Using SOAP:
    10556-------------------------------------------------------
    10657
    107 Greenstone comes with Apache Axis installed as part of the Greenstone web application.  A SOAP server on localsite is deployed during installation. You should be able to see all localsite's collections through the gateway servlet. (http://localhost:8080/greenstone3/gateway)
     58Greenstone comes with Apache Axis installed as part of the Greenstone web application. However, no SOAP services are deployed by default.
     59
     60To deploy a SOAP server for localsite, run 'ant deploy-localsite'. You should now be able to see all localsite's collections through the gateway servlet. (http://localhost:8080/greenstone3/gateway)
    10861
    10962To set up a SOAP server on a new site, run
    … …  
    172125Once all these changes have been made, you will need to restart the Tomcat server for them to take effect.
    173126
    174 Using External MySQL
    175 -------------------------------------------------------------
    176 
    177 Set the mysql.installed.path property in build.xml to be the path to your installation of mysql, before running the Greenstone install process. (This path is not actually used other than to check that its non-empty).
    178 
    179 You will need to add the two greenstone users: gsdl3reader and gsdl3admin to your mysql server. The reader user is only used for accessing the database, the admin user can be used for modification. You may also specify passwords for these two users.
    180 
    181 Run MySQL as the root user (or a user with account creation privileges).
    182 
    183 Commands to add the two users:
    184 GRANT SELECT,INSERT,DELETE,UPDATE,DROP,CREATE ON *.* TO gsdl3admin@localhost identified by 'admin-password';
    185 GRANT SELECT ON *.* TO gsdl3reader@localhost identified by 'reader-password';
    186 
    187 The "identified by 'xxx-password'" bits can be left out if you don't want to set any passwords. This will mean that anyone can log in to mysql using these usernames.
    188 
    189 You will need to edit the global.properties file and set the two passwords that you used:
    190 mysql.admin.password and mysql.reader.password
    191 Set these to be empty if you haven't used any passwords.
    192 The mysql.tcp.port property specified here should be set to the port that your MySQL is running on. (default 3306), and the mysql.server property should be set to the server address.
    193 
    194 This file is in greenstone3/resources/java/global.properties.in before greenstone3 installation, and greenstone3/web/WEB-INF/classes/global.properties after installation.
    195 
    196 You should also load up the database for the gs3mgdemo collection:
    197 create database localsite_gs3mgdemo;
    198 
    199 Close MySQL, then run
    200 mysql localsite_gs3mgdemo < <path-to-greenstone3>/web/sites/localsite/collect/gs3mgdemo/mysqldatadump.sql
    201 
    202 (Note that if you have installed the Greenstone web directory into Tomcats webapps dir, then this command will be
    203 mysql localsite_gs3mgdemo < <path-to-tomcat>/webapps/greenstone3/sites/localsite/collect/gs3mgdemo/mysqldatadump.sql )
    204 
    205 You may need to run this using '--user=root -p'
    206127
    207128Notes for Mac OS
    … …  
    222143ant prepare install
    223144
    224 Tomcat and MySQL will be downloaded as part of the prepare process. To stop this set the tomcat.installed.path and/or mysql.installed.path to be the root of existing Tomcat/MySQL installations.
    225 The Tomcat distribution is cross platform, but MySQL is not - only Windows, GNU/Linux and Mac OS X versions will be used (see below). If you require a different version of MySQL, then you will need to install it yourself.
     145Tomcat will be installed as part of the prepare process. To stop this set the tomcat.installed.path to be the root of an existing Tomcat installation.
    226146
    227147* Solaris notes:
    … …  
    240160Don't forget to setup the Visual Studio environment first, by running, e.g. C:/Program Files/Microsoft Visual Studio/VC98/Bin/VCVARS32.BAT or equivalent.
    241161
     162Configuring your installation:
     163--------------------------------------------------------
     164
     165The file build.properties contains various parameters that can be set by the user. Please check these settings before running the install.
     166Note, either forward slash '/' or double backslash '\\' can be used as path separators in the build.properties file, but not single backslash '\'.
     167
     168Greenstone 3 comes with Tomcat bundled in. 
     169
     170If you already have Tomcat running, you can set the 'tomcat.installed.path' property (in build.properties) to the base directory of your Tomcat installation, and Greenstone will not use its own Tomcat. (You can delete the packages/tomcat directory if you like.) Please read the section "Using External Tomcat" for details about how to configure Tomcat for Greenstone.
     171
     172Mac OS X: You need to have GDBM installed (http://www.gnu.org/software/gdbm/gdbm.html). Please set the gdbm.installed.path property (in build.properties) to the root of your gdbm installation if it is not installed in a default place. If you run GLI or GS2 collection building from the command line, you will need to set the DYLD_LIBRARY_PATH environment variable to include <path-to-gdbm>/lib.
     173
     174The install target will ask you if you accept the properties before starting.
     175To suppress this prompt, use the -Dproperties.accepted=yes flag. E.g.
     176ant -Dproperties.accepted=yes install
     177
     178To log the output in build.log, run
     179ant -Dproperties.accepted=yes -logfile build.log  install
     180
     181Recompiling
     182-------------------------------------------------------
     183To recompile your Greenstone3 installation, in the top level greenstone3 directory, run:
     184
     185ant configure
     186ant configure-c++
     187ant clean
     188ant compile
     189
     190The compile target, under GNU/Linux and Mac OS X, does Java and C/C++ compilation. For Windows, since Visual Studio is not a standard component, only Java compilation is carried out. Pre-compiled binaries are provided for the C/C++ components (src/packages and Greenstone 2 style building). If you have Visual Studio installed (version 6), you can run the compile-windows-c++ targets to compile the code locally. (Don't forget to setup the Visual Studio environment first, by running, e.g. C:/Program Files/Microsoft Visual Studio/VC98/Bin/VCVARS32.BAT or equivalent.)
     191
     192Any sub targets can be run by themselves. Run 'ant -projecthelp' for a list of public targets, otherwise you can look at the build.xml file to see which targets depend on other ones.
     193
     194If you run your install using an external Tomcat, the SOAP web service for localsite (used by the gateway servlet) will not be loaded. You need to start up Tomcat, then run 'ant soap-deploy-site' and accept the defaults for sitename and siteuri (both localsite). If you want to use the gateway servlet without restarting Tomcat, you will need to reload the site information. Visit the URL http://localhost:8080/greenstone3/gateway?a=s&sa=c  (substituting your server name and port number if necessary). See the user guide for more information about run time reconfiguration.
     195
     196
    242197Notes on Versions of Third Party packages
    243198-----------------------------------------------
    … …  
    250205website: http://tomcat.apache.org/
    251206download: http://tomcat.apache.org/download-55.cgi
    252 
    253 MySQL:
    254 
    255 Relational database. Binary versions. latest version 4 stable release as at October 2005.
    256 mysql-noinstall-4.1.15-win32.zip (Windows, without installer)
    257 mysql-standard-4.1.15-apple-darwin7.9.0-powerpc.tar.gz (Mac OS X v10.3, without installer)
    258 mysql-standard-4.1.15-pc-linux-gnu-i686.tar.gz (GNU/Linux, x86, glibc-2.2, static (Standard only), gcc)
    259 
    260 http://dev.mysql.com
    261207
    262208Axis:
    … …  
    275221See greenstone3/docs/manual/manual.pdf for more details about the software and installation etc.
    276222
    277 Under GNU/Linux and Mac OS X, Tomcat logs output to logs/catalina.out in the Tomcat directory (greenstone3/packages/tomcat)
     223Output is logged to web/logs. usage.log is a usage log, while greenstone.log is the error/message log. To change the level of logging, edit the web/WEB-INF/classes/log4j.properties file, and change the log4j.disable property. Valid values are TRACE, DEBUG, INFO, WARN, ERROR and FATAL.
    278224
    279225To prevent Tomcat showing directory listings, edit Tomcat's conf/web.xml file and set the value of the "listings" servlet parameter to false.
Note: See TracChangeset for help on using the changeset viewer.