From 4beb0fa2bf626af579111d8db62239ee42886e95 Mon Sep 17 00:00:00 2001 From: Tim Donohue Date: Fri, 11 Jan 2008 22:41:04 +0000 Subject: [PATCH] An initial stab at updated installation instructions for DSpace 1.5. If there are details you see missing, feel free to add to it. git-svn-id: http://scm.dspace.org/svn/repo/branches/dspace-1_5_x@2517 9c30dcfa-912a-0410-8fc2-9e0234be79fd --- dspace/docs/install.html | 295 ++++++++++++++++++++++++++++++++++----- 1 file changed, 258 insertions(+), 37 deletions(-) diff --git a/dspace/docs/install.html b/dspace/docs/install.html index 7e075a8265..d85ef1abcd 100644 --- a/dspace/docs/install.html +++ b/dspace/docs/install.html @@ -10,17 +10,35 @@

Back to contents

+

 

+

Installation Table of Contents +

+

+ +

Prerequisite Software

-

Prerequisites

- -

The list below describes the third-party components and tools you'll need to run a DSpace server. These are simply recommendations based on our setup at MIT; since DSpace is built on open source, standards-based tools, there are numerous other possibilities and setups.

+

The list below describes the third-party components and tools you'll need to run a DSpace server. These are just guidelines. Since DSpace is built on open source, standards-based tools, there are numerous other possibilities and setups.

Also, please note that the configuration and installation guidelines relating to a particular tool below are here for convenience. You should refer to the documentation for each individual component for complete and up-to-date details. Many of the tools are updated on a frequent basis, and the guidelines below may become out of date.

    -

  1. UNIX-like OS (Linux, HP/UX etc)

    2. +

  2. UNIX-like OS (Linux, HP/UX etc) or Microsoft Windows (see full Windows Instructions for full set of Windows prerequisites)

    3. -

  3. Java 1.4 or later (standard SDK is fine, you don't need J2EE)

    4. +

  4. Java SDK 1.5 or later (standard SDK is fine, you don't need J2EE)

  5. Apache Ant 1.6.2 or later (Java make-like tool)

    6. @@ -65,7 +83,7 @@ -

  6. Jakarta Tomcat 4.x/5.x or equivalent, such as Jetty or Caucho Resin.

    +

  7. Jakarta Tomcat 4.x or later. DSpace will also run on an equivalent, such as Jetty or Caucho Resin.

    Note that DSpace will need to run as the same user as Tomcat, so you might want to install and run Tomcat as a user called 'dspace'.

    @@ -88,25 +106,102 @@

    Jetty and Resin are configured for correct handling of UTF-8 by default.

    8. + +

  8. (Optional) Apache Maven 2 (Java project build manager)

    +

    Maven is only necessary to install if you want to re-package and re-build all of DSpace from its source code. + Therefore, Maven is only required if you want to do one or more of the following:

    +
      +
    • Change the underlying Java API of DSpace
      • +
    • Completely re-package DSpace with your own custom API or custom interfaces
      • +
    • Create DSpace interface "overlays"
      • +
    +

    If your institution does not have a developer who actually customizes + the underlying Java API for DSpace, chances are you don't need Maven.

    +
    9. +
+

Installation Options

+ +

Overview of Install Options

-

Quick Installation Steps

+

With the advent of a new Maven-based build architecture in DSpace 1.5.x, + you now have a few options in how you may wish to install and manage your + local installation of DSpace. There are now two different methods to installing + DSpace software. Which path you choose may be entirely dependent on your + institution's DSpace resources and technical knowledge:

+

+

+

-

But First, a Word on Directories and Path Names

+

Overview of DSpace Directories

-

DSpace uses three separate directory trees. Although you don't need to know all the details +

Before beginning an installation, it is important to get a general understanding + of the DSpace directories and the names by which they are generally referred. + (Please attempt to use these below directory names when asking for help on the + DSpace Mailing Lists, as it will help everyone better understand what directory + you may be referring to.)

+ +

DSpace uses three separate directory trees. Although you don't need to know all the details of them in order to install DSpace, you do need to know they exist and also know how they're referred to in this document:

-

+
    +
  1. the installation directory, referred to as [dspace]. This is the location where + all the DSpace configuration files, command line scripts, documentation and webapps exist.
    2. +
  2. the source directory, referred to as [dspace-source]. This is the location + where the DSpace module source code resides. Please note that in DSpace 1.5.x and above, + this location only exists if you install DSpace using the Maven-based Installation method.
    3. +
  3. the web deployment directory. This is the directory that contains + your DSpace web application(s). In DSpace 1.5.x and above, this corresponds + to [dspace]/webapps by default. However, if you are using Tomcat, + you may decide to copy your DSpace web applications from [dspace]/webapps/ to [tomcat]/webapps/ (with [tomcat] being wherever + you installed Tomcat--also known as $CATALINA_HOME).
    4. +

For details on the contents of these separate directory trees, refer to directories.html. - Note that the source directory and install directory should always be separate!

+ Note that the [dspace-source] and [dspace] directories are always separate!

+ + +

Quick Installation Method

+ + This method gets you up and running with DSpace quickly and easily. However, you should be aware + that it provides you with pre-compiled DSpace Java code. This means that if you are wanting to + change any of the underlying DSpace Java code, you should use the Maven-based Installation Method instead.
  1. @@ -114,13 +209,19 @@ you installed Tomcat--also known as $CATALINA_HOME). This directory is generated 
    useradd -m dspace
    2. -
  2. -

    Download the latest DSpace source code release and unpack it:

    - - 
    gunzip -c dspace-source-1.x.tar.gz | tar -xf -
    - -
    3. +

    Download the latest DSpace installation package and unpack it + into a temporary location. It is not necessary to keep this directory around after you install DSpace.

    + + 
    gunzip -c dspace-1.x.tar.gz | tar -xf -
    + +

    For ease of reference, we will refer to the location of this unzipped version + of the DSpace installation package as [dspace-package] in the + remainder of these instructions. + +

    + +

  3. Database Setup

    @@ -128,11 +229,12 @@ you installed Tomcat--also known as $CATALINA_HOME). This directory is generated

    1. Copy the PostgreSQL JDBC driver (.jar file) into -[dspace-source]/lib. If you compiled PostgreSQL yourself, it'll be in postgresql-7.x.x/src/interfaces/jdbc/jars/postgresql.jar. Alternatively you can download it directly from the PostgreSQL JDBC site. Make sure you get the driver for the version of PostgreSQL you're running and for JDBC2.

      2. +[dspace-package]/lib. If you compiled PostgreSQL yourself, it'll be in postgresql-7.x.x/src/interfaces/jdbc/jars/postgresql.jar. Alternatively you can download it directly from the PostgreSQL JDBC site. Make sure you get the recommended driver for the version of PostgreSQL you're running.

    2. Create a dspace database, owned by the dspace PostgreSQL user:

      - 
      createuser -U postgres -d -A -P dspace ; createdb -U dspace -E UNICODE dspace
      + 
      createuser -U postgres -d -A -P dspace
+createdb -U dspace -E UNICODE dspace

      Enter a password for the DSpace database. (This isn't the same as the dspace user's UNIX password.)

      3. @@ -140,7 +242,7 @@ you installed Tomcat--also known as $CATALINA_HOME). This directory is generated

      Oracle:

      1. -

        Copy the Oracle JDBC driver into [dspace-source]/lib.

        +

        Copy the Oracle JDBC driver into [dspace-package]/lib.

      2. Create a database for DSpace. Make sure that the character set is one of the Unicode character sets. DSpace uses UTF-8 natively, and it is suggested that the Oracle database use the same character set. Create a user account for DSpace (e.g. dspace,) and ensure that it has permissions to add and remove tables in the database.

        @@ -152,9 +254,9 @@ db.url = jdbc.oracle.thin:@//host:port/dspace db.driver = oracle.jdbc.OracleDriver
      3. -

        Go to [dspace-source]/etc/oracle and copy the contents to their parent directory, overwriting the versions in the parent: +

        Go to [dspace-package]/etc/oracle and copy the contents to their parent directory, overwriting the versions in the parent: -

        cd dspace_source/etc/oracle
+
        cd [dspace-package]/etc/oracle
 cp * ..
        
             
        You now have Oracle-specific .sql files in your etc directory, and your dspace.cfg is modified to point to your Oracle database.
        4. @@ -162,7 +264,7 @@ cp * ..
      4. -

        Edit [dspace-source]/config/dspace.cfg, in particular you'll need to set these properties: +

        Edit [dspace-package]/config/dspace.cfg, in particular you'll need to set these properties:
        dspace.dir -- must be set to the [dspace] (installation) directory. @@ -196,17 +298,19 @@ See the dspace.cfg file for examples.

      5. -

        Create the directory for the DSpace installation. As root, run:

        +

        Create the directory for the DSpace installation (i.e. [dspace]). As root (or a user with appropriate permissions), run:

        - 
        mkdir [dspace] ; chown dspace [dspace]
        + 
        mkdir [dspace]
+chown dspace [dspace]

        (Assuming the dspace UNIX username.)

      6. -

        As the dspace UNIX user, compile and install DSpace:

        +

        As the dspace UNIX user, initialize the DSpace database and install DSpace to [dspace]:

        - 
        cd [dspace-source] ; ant fresh_install
        + 
        cd [dspace-package] 
+ant fresh_install

        Note: to see a complete list of build targets, run

        @@ -216,9 +320,21 @@ See the dspace.cfg file for examples.
      7. -

        Copy the DSpace Web application archives (.war files) to the appropriate directory in your Tomcat/Jetty/Resin installation. For example:

        +

        Tell your Tomcat/Jetty/Resin installation where to find your DSpace web application(s). + As an example, in the <Host> section of your [tomcat]/conf/server.xml you could add lines similar to the following + (but replace [dspace] with your installation location):

        + + 
        <!-- DEFINE A CONTEXT PATH FOR DSpace JSP User Interface  -->
+<Context path="/dspace-jspui" docBase="[dspace]\webapps\dspace-jspui" debug="0" reloadable="true" cachingAllowed="false" allowLinking="true"/>
+	
+<!-- DEFINE A CONTEXT PATH FOR DSpace OAI User Interface  -->
+<Context path="/dspace-oai" docBase="[dspace]\webapps\dspace-oai" debug="0" reloadable="true" cachingAllowed="false" allowLinking="true"/>
        + +

        Alternatively, you could copy only the DSpace Web application(s) you wish to use from [dspace]/webapps to the appropriate directory in your Tomcat/Jetty/Resin installation. For example:

        + + 
        cp -r [dspace]/webapps/dspace-jspui [tomcat]/webapps
+cp -r [dspace]/webapps/dspace-oai [tomcat]/webapps
        - 
        cp [dspace-source]/build/*.war [tomcat]/webapps
      8. @@ -228,12 +344,117 @@ See the dspace.cfg file for examples.
      9. -

        Now the moment of truth! Start up (or restart) Tomcat. Visit the base URL of your server, e.g. http://dspace.myu.edu:8080/dspace. You should see the DSpace home page. Congratulations!

        +

        Now the moment of truth! Start up (or restart) Tomcat/Jetty/Resin. Visit the base URL(s) of your server, depending on which DSpace web applications you want to use. You should see the DSpace home page. Congratulations!

        + +

        Base URLs of DSpace Web Applications:

        +
          +
        • JSP User Interface - (e.g.) http://dspace.myu.edu:8080/dspace-jspui
          • +
        • XML User Interface (aka. Manakin) - (e.g.) http://dspace.myu.edu:8080/dspace-xmlui-webapp
          • +
        • OAI-PMH Interface - (e.g.) http://dspace.myu.edu:8080/dspace-oai/request?verb=identify (Should return an XML-based response)
          • +
      -

      In order to set up some communities and collections, you'll need to access the administration UI. To do this, append 'admin' to your server's URL, e.g. http://dspace.myu.edu:8080/dspace/dspace-admin.

      +

      In order to set up some communities and collections, you'll need to login as your DSpace Administrator (which you created with create-administrator above) and access the administration UI in either the JSP or XML user interface.

      +

      Maven-based Installation Method

      + +

      This method allows you to build your own custom version of DSpace using Apache Maven 2. + If you are not wanting to custom any of DSpace's Java API, or just want to get up and running quickly, + it is recommend that you use the Quick Installation Method instead.

      + +

      Additional Prerequisites +

        +
      • Apache Maven 2 - This is obviously required if you are doing a Maven-based install
        • +
      • Subversion (SVN) - Necessary to checkout the DSpace source code from SourceForge SVN
        • +
      +

      + +
        +
      1. +

        Create the DSpace user. This needs to be the same user that Tomcat (or Jetty etc) will run as. e.g. as root run:

        + + 
        useradd -m dspace
        +
        2. +
      2. +

        Create the directory for the DSpace source to reside (i.e. [dspace-source]). As root (or a user with appropriate permissions), run:

        + + 
        mkdir [dspace-source]
+chown dspace [dspace-source]
        + +

        (Assuming the dspace UNIX username.)

        +
        3. +
      3. +

        Checkout the DSpace Source code from SourceForge SVN into [dspace-source]. For example:

        + + 
        svn co https://dspace.svn.sourceforge.net/svnroot/dspace/tags/dspace-1_5 [dspace-source]
        + +

        If you wish, you can choose to only checkout the source code for the specific DSpace "modules" + which you want to install. However, you must always checkout the 'dspace' module, as + it is the module which builds DSpace. For example, if you only want to install the XML-UI and the OAI-PMH interface + you can perform the following checkouts:

        + + 
        svn co https://dspace.svn.sourceforge.net/svnroot/dspace/tags/dspace-1_5/dspace [dspace-source]
+svn co https://dspace.svn.sourceforge.net/svnroot/dspace/tags/dspace-1_5/dspace-xmlui [dspace-source]
+svn co https://dspace.svn.sourceforge.net/svnroot/dspace/tags/dspace-1_5/dspace-oai [dspace-source]	  	
+
        + +

        In order, you are checking out the 'dspace' module (builds DSpace), + 'dspace-xmlui' module (provides XML-UI), and 'dspace-oai' module (provides OAI-PMH).

        + +

        In the end, you should have a folder structure similar to the following in [dspace-source]: +

          +
        • [dspace-source] +
            +
          • dspace/ - DSpace 'build' and configuration module
            • +
          • dspace-api/ - DSpace Java API module
            • +
          • dspace-jspui/ - DSpace JSP-UI module
            • +
          • dspace-oai/ - DSpace OAI-PMH interface module
            • +
          • dspace-xmlui/ - DSpace XML-UI module
            • +
          +
          • +
        +
        4. +
      4. +

        Build your custom DSpace installation package (from within the 'dspace' module)

        + + 
        cd [dspace-source]/dspace/
+mvn package
        + +

        Note: without any extra arguments, DSpace is built for PostgreSQL. If you want to use Oracle instead, + you should build DSpace as follows:

        + + 
        mvn -Ddb.name=oracle package
        +
        5. +
      5. +

        Building DSpace may take awhile. But, once it is complete, you should have your + custom DSpace installation package ready in your + [dspace-source]/dspace/target/dspace-[version].dir/ directory.

        +

        Note: Although we won't go into this in detail, you can also create your own + completely custom Maven-based modules in your [dspace-source] directory. + To build your custom modules into DSpace, you would need to modify the 'dspace' + module's pom.xml (Project Object Model) to look for those custom modules, and + then re-build your DSpace installation package. Look + at the Maven Documentation or + DSpace Wiki for more hints and tricks.

        +
        6. +

      6. Once your DSpace installation package has been built, you can follow the steps in the + Quick Installation Method above to install and configure DSpace. + Just remember that you can skip downloading the DSpace Installation Package from + SourceForge (Step #2 in the Quick Installation Method), since you just built + your own custom DSpace Installation Package into [dspace-source]/dspace/target/dspace-[version].dir/

        +
        7. +
      + +

      Useful Maven References +

        +
      • Maven Homepage - The place to go for all things Maven...it also includes links to the below resources.
        • +
      • Maven User Centre - Basic documentation and Tutorials for Maven. Also has a Project Object Model (POM) reference.
        • +
      • Maven Plugins - Various Maven plugins you can take advantage of in your Maven POMs.
        • +
      +

      + +

      Advanced Installation

      The above installation steps are sufficient to set up a test server to play around with, but there are a few other steps and options you should probably consider before deploying a DSpace production site.

      @@ -572,7 +793,7 @@ $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keysize 1024 \

      You'll need to install this pre-requisite software:

        -

      • Java SDK 1.4 or later (standard SDK is fine, you don't need J2EE)

        • +

      • Java SDK 1.5 or later (standard SDK is fine, you don't need J2EE)

      • PostgreSQL 8.x for Windows. This comes with an installer application now, so Cygwin is no longer required. Make sure the ODBC + JDBC options are selected, as well as the pgAdmin III tool

      • Apache Ant 1.6.x. Unzip the package in C:\ and add C:\apache-ant-1.6.2\bin to the PATH environment variable. For Ant to work properly, you should ensure that JAVA_HOME is set.

      • Jakarta Tomcat 5.x+