A. Prerequisite software

1. A unix-like operating system (Linux, Solaris, BSD, HP/UX, ...)
2. A java developer environment (SDK) - we used Sun's 1.4.2 SDK
3. ANT, the Java compile tool
4. A servlet container/http server that can do SSL (Secure Socket Layers)
   in this course, we opted for standalone Tomcat, version 5.0
   other alternatives include Jetty, JBoss and similar.
5. The Postgres open source database server
   Currently DSpace can't work with any other database yet, although this is 
   likely to change in the future.
6. Three separate java library packages:
    - JavaBeans Activation Framework http://java.sun.com/products/javabeans/glasgow/jaf.html
    - Java Servlet 2.3 and JSP 1.2 http://java.sun.com/products/jsp/download.html
    - JavaMail API http://java.sun.com/products/javamail/index.html

Ideally, you want to download these files to a separate download directory so you can
refer to these files later.

We assume some knowledge of the unix operating system so you're supposed to know how
to install software in a permanent location, or how to unpack software to a temporary
directory. If you don't feel comfortable with this, please get the help from a Unix 
sysadmin.

Make sure you have a "dspace" user on your system.

The following notes contain examples that were specific to the Mandrake Linux
operating system on the course PCs. The actual location of files might be
different on your system. The "export" syntax for setting variables is bash 
shell specific. If you use a different shell, it's up to you to find out how
to set and export environment variables.

B. Postgres

On the course systems, Postgres was pre-installed from binary. You need to make
sure you can connect to the database server from the local machine. To do this
you may have to edit pg_hba.conf (wherever this is installed on your system).

You will probably also have to edit the postgresql.conf file to allow tcp/ip
connections to the database server.

For example, on our Mandrake system, this meant (as root)
   vi /var/lib/pgsql/data/postgresql.conf
    add the line:
    tcpip_socket = true
    restart postgres with /etc/init.d/postgresql restart

1. Become the right postgres user for your system, on Mandrake Linux this would be:
    su - postgres
    (unless you execute this su from user root, this will ask for a password)
2. createuser -d -A -P dspace
   make sure to remember the password you assign to the dspace user
3. createdb -U dspace -E UNICODE dspace


C. Java SDK

The Java SDK can be installed as binary either in plain binary format or as a
RPM for some linux systems. In any case, the Java SDK is all contained within 
one single directory. In the course example, this directory was /usr/java/j2sdk...

Set JAVA_HOME with: export JAVA_HOME=/usr/java/j2sdk..... making sure that
you use the directory the software is contained in on your system.


D. Ant

1. Go to the directory where you downloaded the ant binary
2. unzip ant
3. cd apache-ant...
4. Set ANT_HOME to this directory with: export ANT_HOME=$(pwd)
5. Add ant to your PATH: export PATH=$PATH:$ANT_HOME/bin


E. Tomcat

1. go to the directory where you downloaded the tomcat binaries
2. Extract tomcat with: tar xzvf tomcat.tar.gz
3. cd jakarta-tomcat....
4. export CATALINA_HOME=$(pwd)
5. export JSSE_HOME=$JAVA_HOME/jre/lib
    (this gives Tomcat access to the java SSL libraries)


F. Dspace

1. Unzip/untar the dspace source package in a temporary directory 
   with tar zxvf dspace...tar.gz
2. cd to the dspace source directory you just created
3. Extract the javamail, javabeans activation framework and servlet jars 
   to a temporary directory.
4. Copy all the .jar files from these into <dspace-src-dir>/lib
5. Edit dspace configuation file: 
    <srcdir>/config/dspace.cfg

    dspace.url = https://localhost:8443
      (8443 is the port the Tomcat SSL uses by default. 
      This can be changed in the Tomcat config if you want)
    dspace.hostname = localhost
   For a real dspace system, you want to change these to the publicly
   visible hostname of the server running DSpace.

   Add the correct database user/password information.
   

7. Copy the postgres jdbc driver into <srcdir>/lib
   On our mandrake systems, do:
   cp /usr/share/pgsql/jdbc7.2dev-1.2.jar <dspace-src-dir>/lib/postgresql.jar

   If you had built postgresql from source (with the --with-java option) Then 
   postgresql.jar would have been built at that time.

9. In the dspace source dir, do 
     ant; ant fresh_install


G. Configuring Tomcat

1. Connect dspace webapps to Tomcat. Go to $CATALINA_HOME/webapps

2. Make symbolic links into the dspace install directory:

    ln -s /dspace/jsp dspace
    ln -s /dspace/oai dspace-oai

3. Make Dspace the main Web UI webapp: (still in the webapps directory)

   mv ROOT ROOT.bak
   ln -s /dspace/jsp ROOT

4. SSL setup. Generate a key for SSL (as root):

   $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
   and use the password: changeit

   vi $CATALINA_HOME/conf/server.xml 

   Find the example ssl server connector config and remove the 
   comment tags surrounding it (<!-- and -->)

   Add comment tags around the "normal" (non-SSL) Tomcat connector.

5. Start Tomcat: $CATALINA_HOME/bin/startup.sh



If you now go to https://your.dspace.server:8443/ you should see the
DSpace you just installed. Replacing "your.dspace.server" with the hostname
of your dspace server.