Changeset 10884 for trunk/gsdl3

Timestamp:

2005-11-11T13:30:45+13:00 (18 years ago)

Author:

kjdon

Message:

removed all CVS related notes from README.txt to the new README-CVS.txt file

Location:

trunk/gsdl3

Files:

• README-CVS.txt (added)
• README.txt (modified) (9 diffs)

trunk/gsdl3/README.txt

@@ -14 +14 @@
 do various things like compile the source code, start up the server etc.
 
-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.
-
-Installing Greenstone from a binary distribution:
+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.
+
+Installing Greenstone
 ---------------------------------------------------------
 
-Download the appropriate zip/tar file (greenstone-3.xx-linux.tar.gz/greenstone-3.xx-win32.zip/greenstone-3.xx-macOSX.tar.gz), and unzip/untar it. In the greenstone3 directory, edit the build.properties file (see 'Configuring your installation' below), and run 'ant install'.
-
-Installing Greenstone from a CVS checkout (GNU/Linux, Windows, MacOS X):
----------------------------------------------------------------------
-
-Make sure the CVS executable is on your PATH.
-
-Checkout the code:
-
-cvs -d :pserver:[email protected]:2402/usr/local/global-cvs/gsdl-src co greenstone3
-
-Build and install:
-
-In the greenstone3 directory, edit the build.properties file (see 'Configuring your installation' below), and run 'ant prepare install'. The two targets can be run separately if you like.
-
-The 'prepare' target will download additional code (using CVS and http), so you need to be online to run it. The 'install' target can be run offline.
+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'.
+
+See 'Using External Tomcat' and 'Using External MySQL' sections below if you want to use an existing version.
 
 Configuring your installation:
-------------------------------------
+--------------------------------------------------------
 
 The file build.properties contains various parameters that can be set by the user. Please check these settings before running the install.
 
-Greenstone 3 uses the Tomcat servlet container. 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 download/install its own Tomcat. Please read the section "Using External Tomcat" for details about how to configure Tomcat for Greenstone.
-
-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 download/install mysql. Please read the section "Using external mysql server" for details about how to configure mysql for Greenstone.
-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.
-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.
-
-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, please set the gsdl2.installed.path property (in build.properties) to be the root of your Greenstone 2 installation. Greenstone 3 will then use this installation rather than its own bits. (Note, be careful about compatibility between versions.) If you are using Greenstone 3 from CVS, and don't want to download the Greenstone 2 stuff, set the gsdl2.installed.path to any non-empty string.
+Greenstone 3 comes with MySQL and Tomcat bundled in.  
+
+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.
+
+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.
+
+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.
+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.
+
 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.
 
-The prepare/install target will ask you if you accept the properties before starting.
+The install target will ask you if you accept the properties before starting.
 To suppress this prompt, use the -Dproperties.accepted=yes flag. E.g.
-ant -Dproperties.accepted=yes prepare install (from CVS), or
-ant -Dproperties.accepted=yes install (from binary dist).
+ant -Dproperties.accepted=yes install 
 
 To log the output in build.log, run
-ant -Dproperties.accepted=yes -logfile build.log prepare install (from CVS), or
-ant -Dproperties.accepted=yes -logfile build.log  install (from binary dist).
-
-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.)
-
-Common install/update targets (for use with Greenstone out of CVS).
--------------------------------
-1. Install for the first time from CVS:
-cvs co greenstone3
-cd greenstone3
-ant prepare install
-
-2. Install for the first time from CVS, mostly offline:
-[online]
-cvs co greenstone3
-cd greenstone3
-ant prepare
-[offline]
-ant install
-
-3. Install for the first time, with CVS done outside of Ant (if you have problems running CVS commands from Ant):
-cvs co -P greenstone3
-cd greenstone3/src/packages
-cvs co mgpp
-cd ../..
-[if you want greenstone 2 building:
-cvs co -P gli
-cvs co -P gs2build
-]
-[if you are on windows
-cvs co winbin
-]
-ant -Dnocvs.mode=yes prepare install (prepare needs to be online, install can be done offline)
-
-4. Updating your Greenstone installation from CVS (and reconfigure/recompile):
-cd greenstone3
-ant update
-
-5. Updating your Greenstone installation from CVS, offline:
-cd greenstone3
-[online]
-ant cvsupdate
-[offline]
-ant -Dnocvs.mode=yes update
-
-6. Updating your Greenstone installation, with CVS done outside of Ant:
-cd greenstone3
-cvs update -l
-cvs update -dP extensions bin comms docs lib resources src winutil packages 
-cd web (or the path-to-tomcat/webapps/greenstone3 if have installed greenstone as a webapp in Tomcat, see Using External Tomcat section)
-cvs update -dP 
-cd greenstone3
-[ if you have greenstone 2 building:
-cvs update -dP gli
-cvs checkout -P gs2build
-Note that the gs2build one uses checkout not update.
-]
-ant -Dnocvs.mode=yes update
-
-The main targets for installation/update are:
-configure, configure-c++, clean, compile.
-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.
-
-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 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.
+ant -Dproperties.accepted=yes -logfile build.log  install 
 
 Running Greenstone:
--------------------
-
-To startup the local servers, run 'ant start'. 'ant restart' and 'ant stop' restarts and shuts down the servers. To start or stop just Tomcat or MYSQL, use the start-tomcat, start-mysql, stop-tomcat, stop-mysql targets.
-These will only start/stop local servers (ones installed by Greenstone). You will need to manually start/stop external Tomcat/mysql.
-
-Greenstone will be available in a browser at "http://localhost:8080/greenstone3".
-
+---------------------------------------------------------
+
+To startup the local servers (Tomcat adn/or MySQL), run 'ant start'. 
+'ant restart' and 'ant stop' restarts and shuts down the servers. 
+To start or stop just Tomcat or MySQL, use the start-tomcat, start-mysql, stop-tomcat, stop-mysql targets.
+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.
+
+Once the Tomcat server is running, Greenstone will be available in a browser at "http://localhost:8080/greenstone3".
 You can change the port number by changing the 'tomcat.port' property in build.properties, then running 'ant configure'.
 
-
-Using SOAP:
--------------------------------
-
-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)
-
-To set up a SOAP server on a new site, run
-ant soap-deploy-site
-This will prompt you for the sitename (the directory name), and the site uri - this should be a unique identifier for the site's web service.
-
-For a non-interactive version, run
-ant -Daxis.sitename=xxx -Daxis.siteuri=yyy soap-deploy-site
-
-The service is accessible at http://localhost:8080/greenstone3/services/<siteuri>
-(or http://<computer-web-address>:<port>/greenstone3/services/<siteuri>)
+MySQL is only needed if you want to use the GS3MGDemo collection, or if you want to build collections using Greenstone3 native collection building.
+
 
 Building Collections:
------------------------
+----------------------------------------------------------
 
 You can build collections using either Greenstone 2 style building, or native Greenstone 3 style.
 
-Greenstone 2:
+Greenstone 2 style:
 
 You need to have Perl installed and on your PATH. Perl is included as part of the Windows binary distribution.
 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.
 
-Note that GLI doesn't start up the Greenstone server (Tomcat/mysql) so you should run 'ant start' before previewing your collection.
-
-Greenstone 3:
+Note that GLI doesn't start up the Greenstone server (Tomcat/MySQL) so you should run 'ant start' before previewing your collection.
+
+Greenstone 3 style:
 
 In the greenstone3 directory, run: 'source gs3-setup.sh' (GNU/Linux, Mac OS X) or 'gs3-setup' (Windows).
@@ -168 +81 @@
 See the manual for more details about both styles of collection building.
 
-Other Notes:
----------------
-
-See greenstone3/docs/manual/manual.pdf for more details about the software and installation etc.
-
-Under GNU/Linux and Mac OS X, Tomcat logs output to logs/catalina.out in the Tomcat directory (greenstone3/packages/tomcat)
-
-To prevent Tomcat showing directory listings, edit conf/web.xml file in the Tomcat directory and set the value of the "listings" servlet parameter to false.
-
-ant can't seem to do cvs using authenticated cvs on windows:
-there were some classes missing - www.ibiblio.org/maven/jsch/jars/jsch-0.1.17.jar
-many ssh processes seemed to be started up - all waiting in the background for password??
-So should only use anonymous cvs.
+Recompiling
+-------------------------------------------------------
+To recompile your Greenstone3 installation, in the top level greenstone3 directory, run:
+
+ant configure
+ant configure-c++
+ant clean
+ant compile
+
+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.)
+
+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.
+
+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.
+
+
+Using SOAP:
+-------------------------------------------------------
+
+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)
+
+To set up a SOAP server on a new site, run
+ant soap-deploy-site
+This will prompt you for the sitename (the directory name), and the site uri - this should be a unique identifier for the site's web service.
+
+For a non-interactive version, run
+ant -Daxis.sitename=xxx -Daxis.siteuri=yyy soap-deploy-site
+
+The service is accessible at http://localhost:8080/greenstone3/services/<siteuri>
+(or http://<computer-web-address>:<port>/greenstone3/services/<siteuri>)
+
 
 Using External Tomcat:
-------------------------
+---------------------------------------------------
 
 If you want to use an existing Tomcat, set the path to its base directory
-in build.properties (tomcat.installed.path) (on windows need to use double backslashes in paths '\\'). Then run 'ant prepare install'. If you have already done an install (e.g. using a local Tomcat), you don't need to do it again.
+in build.properties (tomcat.installed.path) (on windows need to use double backslashes in paths '\\'). 
 
  You will need to modify the Tomcat setup slightly.
@@ -192 +123 @@
 1. Tell Tomcat about the Greenstone web app. There are two ways to do this.
 
-A. Add in the Greenstone context to Tomcat's server.xml (In the Host name="localhost".. element)
+A. Add in the Greenstone context to Tomcat's server.xml (In the <Host name="localhost"..> element)
 
 <Context path="/greenstone3" docBase="path-to-greenstone3/web" debug="1" 
@@ -198 +129 @@
 
 B. Alternatively, you can move (and rename) the greenstone3/web directory to tomcat/webapps/greenstone3 (i.e. the resulting directories will be like
-tomcat/webapps/greenstone3/WEB-INF, no web directory). This should be done after running the initial 'ant [prepare] install'.
+tomcat/webapps/greenstone3/WEB-INF, no web directory). This should be done after running the initial 'ant install'.
+
 You will need to set the web.home property in the build.properties file
 i.e.
@@ -238 +170 @@
 Once all these changes have been made, you will need to restart the Tomcat server for them to take effect.
 
-Using External mysql server
-------------------------------
+Using External MySQL
+-------------------------------------------------------------
 
 Set the mysql.installed.path property in build.xml to be non-empty (its not actually used) before installation.
@@ -245 +177 @@
 You will need to add the two greenstone users: gsdl3reader and gsdl3admin. The reader user is only used for accessing the database, the admin user can be used for modification.
 
-Run mysql as the root user.
+Run MySQL as the root user (or a user with account creation privileges).
 
 Commands to add the two users:
@@ -253 +185 @@
 You will need to edit the greenstone3/web/WEB-INF/classes/global.properties file and set the two passwords that you used in here:
 mysql.admin.password and mysql.reader.password
-The mysql.tcp.port property specified here should be set to the port that your mysql is running on. (default 3306).
+The mysql.tcp.port property specified here should be set to the port that your MySQL is running on. (default 3306).
 
 You should also load up the database for the gs3mgdemo collection:
 create database localsite_gs3mgdemo;
 
-Close mysql, then run
+Close MySQL, then run
 mysql localsite_gs3mgdemo < <path-to-greenstone3>/web/sites/localsite/collect/gs3mgdemo/mysqldatadump.sql
 
@@ -267 +199 @@
 
 Notes for Mac OS
-------------------
+------------------------------------------------
 
 Set JAVA_HOME to be /Library/Java/Home
 
 Notes on Versions
-------------------
+-----------------------------------------------
 
 Tomcat: 
 jakarta-tomcat-5.5.12.zip & jakarta-tomcat-5.5.12-compat.zip
-Mysql: 
+MySQL: 
 mysql-standard-4.1.15-pc-linux-gnu-i686.tar.gz (GNU/Linux, x86, glibc-2.2, static (Standard only), gcc)
 mysql-standard-4.1.15-apple-darwin7.9.0-powerpc.tar.gz (Mac OS X v10.3, without installer)
@@ -284 +216 @@
 
 All available from www.greenstone.org/gs3files if not available at their respective websites.
+
+Other Notes:
+-------------------------------------------------
+
+See greenstone3/docs/manual/manual.pdf for more details about the software and installation etc.
+
+Under GNU/Linux and Mac OS X, Tomcat logs output to logs/catalina.out in the Tomcat directory (greenstone3/packages/tomcat)
+
+To prevent Tomcat showing directory listings, edit conf/web.xml file in the Tomcat directory and set the value of the "listings" servlet parameter to false.
+
+The file web/WEB-INF/classes/global.properties is generated on install and contains some properties for the run time system.
+