Installation Guide - Queens University Library

Queen’s University QSpace Installation Standard Operating Procedures Subject: Number: Issued by: Date Maximum Review Period QSpace Installation Version 1.00 Seamus Ryan 16 Mar 05 1 year History Version 1.00 1.01 Author(s) Seamus Ryan Seamus Ryan Revision Chart Description of Revision Initial Draft Incorporated ITS-SONP suggestions Date Completed 13 Mar 05 19 Apr 05 QSpace Installation SOP 1 Table of Contents 1.0 2.0 3.0 3.1 3.2 3.3 3.4 4.0 5.0 6.0 6.1 6.2 6.3 6.4 7.0 7.1 7.2 7.3 8.0 8.1 8.2 8.3 9.0 9.1 9.2 9.3 9.4 10.0 10.1 10.2 10.3 10.4 10.5 11.0 11.1 11.2 11.3 12.0 13.0 14.0 15.0 16.0 17.0 17.1 17.2 17.3 18.0 18.1 18.2 18.3 Forward................................................................................................................................................................. 4 Conventions used in this document .................................................................................................................... 5 General Information ............................................................................................................................................ 6 TCP ports used:.................................................................................................................................................... 6 System Users ......................................................................................................................................................... 6 IP address and Server Name ............................................................................................................................... 6 DNS Alias .............................................................................................................................................................. 6 Prerequisites for DSpace 1.2 install .................................................................................................................... 7 Sun V100 ............................................................................................................................................................... 8 Solaris 9 ................................................................................................................................................................. 9 Introduction .......................................................................................................................................................... 9 Environment Support .......................................................................................................................................... 9 DNS configuration ............................................................................................................................................... 9 Installation of Additional Tools .......................................................................................................................... 9 Java2SE 1.4.2...................................................................................................................................................... 10 Introduction ........................................................................................................................................................ 10 Environment Setup ............................................................................................................................................ 10 Installation of Patches........................................................................................................................................ 10 Apache Ant 1.6.2 ................................................................................................................................................ 11 Introduction ........................................................................................................................................................ 11 Environment Setup ............................................................................................................................................ 11 Installation of Ant .............................................................................................................................................. 11 Postgresql 7.4.5 ................................................................................................................................................... 12 Introduction ........................................................................................................................................................ 12 Environment Setup ............................................................................................................................................ 12 Prerequisites ....................................................................................................................................................... 12 Installation of Postgresql from Source ............................................................................................................. 13 Jakarta Tomcat 5.0.28 and jsvc......................................................................................................................... 15 Introduction ................................................................................................................................................... 15 Environment Setup ....................................................................................................................................... 15 Prerequisites .................................................................................................................................................. 15 Installing Tomcat ........................................................................................................................................... 15 Installing jsvc ................................................................................................................................................. 16 Dspace 1.2 ........................................................................................................................................................... 17 Introduction ................................................................................................................................................... 17 Environment Setup ....................................................................................................................................... 17 Installation ..................................................................................................................................................... 17 Setup Tomcat as daemon using jsvc ................................................................................................................. 21 Configuring Tomcat for SSL............................................................................................................................. 22 Configure Tomcat with Certificate from Entrust ............................................................................................ 23 Handle server setup ........................................................................................................................................... 24 OAI-PMH ........................................................................................................................................................... 25 Cron Jobs ............................................................................................................................................................ 26 dspace crontab entries: .................................................................................................................................. 26 postgres crontab entries: ............................................................................................................................... 26 root crontab entries: ...................................................................................................................................... 26 Startup / Shutdown Scripts ............................................................................................................................... 27 /etc/rc2.d ......................................................................................................................................................... 27 /etc/local.d....................................................................................................................................................... 27 /etc/local.d/handle .......................................................................................................................................... 28 2 QSpace Installation SOP 18.4 /etc/local.d/postgres ....................................................................................................................................... 29 18.5 /etc/local.d/tomcat .......................................................................................................................................... 30 19.0 Email Aliases ...................................................................................................................................................... 31 Appendix A – .cshrc file shared by dspace and postgres users .................................................................................... 32 Appendix B– dspace.cfg................................................................................................................................................... 35 QSpace Installation SOP 3 1.0 Forward QSpace is a Queen’s branded instance of DSpace, an open source Institutional Repository (IR). DSpace is implemented as a web application that runs within an application container. The Queen’s instance of DSpace (QSpace) is hosted in a Jakarta Tomcat Servlet/JSP application container. This document is meant to enhance and amplify the installation section of DSpace System Documentation. DSpace documentation and source code can be found on SourceForge at http://sourceforge.net/projects/dspace/ . QSpace Installation SOP 4 2.0 Conventions used in this document Times New Roman – Main body of the text of this document. Fixed-Width Font - Examples of commands or items that you might see on the computer screen. For example, directory and file names as well as installation commands. Fixed-Width Bold Font - Indicate interaction between a user and the system. The user’s input would be shown in bold such as: % su – root Password: # [Fixed-Width Italics] - Input that should be replaced by the user depending on the circumstance, contained within square brackets should be used. For example: % find-logs-by-month [month_name] Italic regular font - Filenames, paths, commands, etc. within the main body of the text. % - user account prompt # - root user account prompt QSpace Installation SOP 5 3.0 General Information 3.1 TCP ports used: 80 443 2461 8000 5432 3.2 Tomcat HTTP via jsvc Tomcat HTTPS via jsvc Handle server native Handle server HTTP PostgeSQL System Users Users that will have to be created on the machine onto which DSpace is to be installed are as follows:    rootr - the super-user for development. dspace - the user who will be the default QSpace user, and will own the tomcat instance etc. This is the primary userid. postgres - the user who will own the database software Both dspace and postgres users share a .cshrc file that provides a common environment. A sample .cshrc file is included at Appendix A. 3.3 IP address and Server Name 130.15.126.69 carrick.its.queensu.ca 3.4 DNS Alias DNS alias “qspace.library” points to “carrick.its” QSpace Installation SOP 6 4.0 Prerequisites for DSpace 1.2 install The following hardware/software environment was setup before installing DSpace 1.2:        Sun V100 Solaris 9 Java2SE 1.4.2 Apache Ant 1.6.2 PostgreSQL 7.4.5 Jakarta Tomcat 5.0.28 (implemented with Servlet 2.4 and JSP 2.0) jsvc – Commons Daemon (packaged with Tomcat) The Tomcat web application (web-app) container, expects its web-app traffic to be routed to it through an intermediary, usually Apache web server. In the QSpace environment, the jsvc tool provided by commons-daemon project was used to listen for and route requests to Tomcat. This setup eliminates the resource overhead of a web server with the sole purpose of serving requests to Tomcat. Please refer to the installation documentation for each prerequisite for complete and up-to-date details. Many of the tools are updated on a frequent basis. The installation of the prerequisites is outside the scope of this document. However, amplification to the standard install instructions for each prerequisite when deemed helpful is provided in following sections. QSpace Installation SOP 7 5.0 Sun V100 This machine is housed in a Sun rack in Dupuis Hall room G17, ITS Operations. It has a 40 GB IDE hard drive, 2GB swap, and 1 GB memory. QSpace Installation SOP 8 6.0 Solaris 9 6.1 Introduction A “development install” of Solaris 9 was made on the server. The development install includes many of the tools needed to develop and test code, and automate associated processes. 6.2 Environment Support Environment support for Sunfreeware tools in .cshrc file shared by dspace and postgres users should include: set path = ($path /opt/csw/bin) set path = ($path /opt/csw/include) set path = ($path /opt/csw/gcc3/bin) setenv LD_LIBRARY_PATH /opt/csw/lib:/opt/csw/gcc3/lib setenv MANPATH “/opt/csw/share/man” 6.3 DNS configuration Request that the system administrator configure DNS with the QSpace website alias. See the General Information Section for the alias name. 6.4 Installation of Additional Tools The compiler included in the development install was gcc2.8.1, failed to compile some components of the tool chain. To address this issue, gcc3.4.1 was installed. The PATH variable in .cshrc was adjusted to have the path to gcc3.4.1, precede the path to gcc2.8.1. For more details see Appendix-A, a sample .cshrc file for dspace and postgres users. For gcc3.4.1 and a number of other tools, including Apache Ant, the Sunfreeware site was used to download and configure tool packages. Sunfreeware.com offers a pkg-get command line utility that facilitates the downloading, installing, and configuring of packages. The pkg-get utility must be run by root user. By default packages are installed in /opt/csw. List of installed packages can be fetched using: rootr# pkg-get compare To download and install gcc3: rootr# pkg-get install gcc3 QSpace Installation SOP 9 7.0 Java2SE 1.4.2 7.1 Introduction Java 2 Platform, Standard Edition, v 1.4.2 (J2SE) was included in the Solaris 9 install. 7.2 Environment Setup Environment support for J2SE in .cshrc file shared by dspace and postgres users should include: setenv JAVA_HOME /usr/j2se set path = ($JAVA_HOME/bin $path) setenv MANPATH = “/opt/j2se/man” setenv CLASSPATH .:/usr/j2se/jre 7.3 Installation of Patches Installation Notes for Solaris list System Requirements including recommended and required patches: 113886-22 OpenGL 1.3: OpenGL Patch for Solaris (32-bit) - not installed, deemed inessential 113096-03 X11 6.6.1: OWconfig patch - installed 112785-43 X11 6.6.1: Xsun patch - installed Patches as noted above were installed. QSpace Installation SOP 10 8.0 Apache Ant 1.6.2 8.1 Introduction Apache Ant is a java make-like tool. Apache Ant home includes link to install. 8.2 Environment Setup Environment support for Ant in .cshrc file shared by dspace and postgres users should include: setenv ANT_HOME /opt/csw set path = ($path /opt/csw/bin) setenv CLASSPATH .:/opt/csw/lib/ant/ant.jar Notes: this set of environment variables assumes that ant was installed using pkg-get. If you installed from source and the ant binary is installed elsewhere, adjust the path accordingly. All ant documentation is in html format; there are no man pages included with Ant 1.6.2. The path to Ant 1.6.2 must precede the path to the system default Ant 1.4.1. For further details, see Appendix A, a sample .cshrc file for dspace and postgres users. 8.3 Installation of Ant Ant and its prerequisites can be alternatively downloaded and configured using the pkgget utility from Sunfreeware.com site. After installing pkg-get utility, as rootr run: rootr# pkg-get install ant QSpace Installation SOP 11 9.0 Postgresql 7.4.5 9.1 Introduction Review Postgres install by visiting PostgreSQL home, and following the documentation link. 9.2 Environment Setup Environment support for PostgreSQL in .cshrc file shared by dspace and postgres users should include: setenv setenv setenv setenv PG_HOME PG_SRC PGSQL PGDATA /export/home/postgres $PG_HOME/postgresql-7.4.5 $PG_HOME/pgsql $PGSQL/data set path = ($path $PGSQL/bin) setenv MANPATH "/export/home/postgres/pgsql/man:/usr/local/man" setenv LD_LIBRARY_PATH /export/home/postgres/pgsql/lib:/usr/local/lib 9.3 Prerequisites Postgres 7.4.5 requires gmake 3.76.1 or newer. Solaris 9 install does not include gmake. Use pkg-get to download, install, and configure gmake: rootr# pkg-get install gmake rootr# gmake --version QSpace Installation SOP 12 9.4 Installation of Postgresql from Source 1. Download postgresql-7.4.5.tar.gz from www.postgres.org. 2. Copy postgresql-7.4.5.tar.gz to PostgreSQL home, and unpack: postgres% cp postgresql-7.4.5.tar.gz $PG_HOME/ postgres% gunzip -c postgresql-7.4.5.tar.gz | tar -xf - 3. The PostgreSQL configure will fail, unless you increase available Solaris 9 shared memory and semaphores. Edit /etc/system with following entries: set set set set set set set set shmsys:shminfo_shmmax=0x7fffffff shmsys:shminfo_shmmin=1 shmsys:shminfo_shmmni=256 shmsys:shminfo_shmseg=256 semsys:seminfo_semmap=256 semsys:seminfo_semmni=1024 semsys:seminfo_semmns=1024 semsys:seminfo_semmsl=32 For changes to take effect you must reboot Solaris 9: rootr# reboot -- -r 4. The PostgreSQL configure script will fail for a dependency for a missing readline library that is not included in the Solaris 9 install. You can either add “-without readline” to the configure command, or you can use pkg-get utility to download, install and configure readline. Recommend latter option; readline adds emacs-like command line editing, that is valuable in the psql interface to the PostgreSQL database. rootr# pkg-get install readline 5. As postgres user configure PostgreSQL for installation: postgres% cd $PG_SRC postgres% ./configure --enable-multibyte --enable-unicode -with-java 6. As postgres user make PostgreSQL, still in $PG_SRC directory: postgres% gmake 7. Check that the build was successful. Look for errors in terminal output. postgres% gmake check 8. As rootr user install PostgreSQL: rootr# gmake install QSpace Installation SOP 13 9. As rootr & postgres users, prepare and initialize the PostgreSQL database: rootr# mkdir /export/home/postgres/pgsql/data rootr# chown postgres /export/home/postgres/pgsql/data rootr# su – postgres postgres% /export/home/postgres/bin/initdb 10. Start PostgreSQL, create dspace database, and test. psql is the command line SQL interface to a PostgreSQL database instance. postgres% /export/home/postgres/bin/pg_ctl –l logfile start postgres% /export/home/postgres/pgsql/bin/createdb test postgres% /export/home/postgres/pgsql/bin/psql test Welcome to psql 7.4.5, the PostgreSQL interactive terminal. Type: \copyright for distribution terms \h for help with SQL commands \? for help on internal slash commands \g or terminate with semicolon to execute query \q to quit dspace=# 11. Add following line to /export/home/postgres/pgsql/data/postgresql.conf tcpip_socket = true 12. Add following line to /export/home/postgres/pgsql/data/pg_hba.conf host dspace dspace 127.0.0.1 255.255.255.255 md5 13. Stop then start postgres, to read configuration changes: postgres% /export/home/postgres/bin/pg_ctl stop –m fast postgres% /export/home/postgres/bin/pg_ctl –l logfile_QS start These commands are part of the /etc/local.d/postgres script are discussed in the Startup / Shutdown Scripts section of this document. 14. The DSpace install will create and initialize a dspace database instance. QSpace Installation SOP 14 10.0 Jakarta Tomcat 5.0.28 and jsvc 10.1 Introduction Jakarta Tomcat home has links to tomcat and jsvc install documentation. Tomcat is the application container which will house DSpace; jsvc is a utility that enhances Tomcat with web-server functionality. In particular jsvc serves http, and handles SSL. 10.2 Environment Setup Environment support for Tomcat in .cshrc file shared by dspace and postgres users should include: setenv CATALINA_HOME /export/home/dspace/tomcat/jakarta-tomcat-5.0.28 set path = ($path $CATALINA_HOME/bin) setenv JAVA_OPTS "-Xmx512m -Xms64M -Dfile.encoding=UTF-8" setenv JSSE_HOME $JAVA_HOME/jre/lib setenv CLASSPATH .:$CATALINA_HOME/common/lib:$CATALINA_HOME/bin/commonsdaemon.jar:$CATALINA_HOME/bin/bootstrap.jar:$JAVA_HOME/lib/too ls.jar 10.3 Prerequisites To build the Tomcat jsvc utility, autoconf and gnu m4. are required. Use pkg-get to download, install, and configure autoconf: rootr# pkg-get install autoconf Note: since autoconf is dependent on gnu m4, the pkg-get utility will automatically download, install, and configure gnu m4 as part of the autoconf install. 10.4 Installing Tomcat Download a Tomcat binary distribution from: http://jakarta.apache.org/site/downloads/index.html Unpack the binary distribution (this assumes that the binary is in the dspace home directory): dspace% dspace% dspace% dspace% dspace% cd ~dspace mkdir tomcat cp jakarta-tomcat-5.0.28 tomcat/ cd tomcat gunzip -c jakarta-tomcat-5.0.28.tar.gz | tar -xf – QSpace Installation SOP 15 10.5 Installing jsvc Tomcat can be run as a daemon using the jsvc tool from the Commons-Daemon project. Source tarballs for jsvc are included with Tomcat binaries, and need to be compiled. 1. Ensure that JAVA_HOME environment variable is set in .cshrc: setenv JAVA_HOME /usr/j2se 2. Following commands should result in a compiled jsvc binary, located in the $CATALINA_HOME/bin folder. This assumes that GNU TAR is used, and that CATALINA_HOME is an environment variable pointing to the base path of the Tomcat installation. dspace% dspace% dspace% dspace% dspace% dspace% dspace% dspace% cd $CATALINA_HOME/bin tar xvfz jsvc.tar.gz cd jsvc-src autoconf ./configure make cp jsvc .. cd .. 3. Even though CLASSPATH includes path to javac, Tomcat does not find it. This was overcome by including a soft link to the Java tools.jar. dspace% cd $CATALINA_HOME/common/lib dspace% ln –s /usr/j2se/lib/tools.jar tools.jar 4. To start Tomcat using jsvc: dspace% cd $CATALINA_HOME/bin dspace% ./jsvc -Djava.endorsed.dirs=./common/endorsed -cp ./bin/bootstrap.jar -outfile ./logs/catalina.out errfile ./logs/catalina.err org.apache.catalina.startup.Bootstrap Note that the Commons-Daemon JAR file must be on your runtime classpath to run Tomcat. The Commons-Daemon JAR file is in the Class-Path entry of the bootstrap.jar manifest, but if you get a ClassNotFoundException or a NoClassDefFoundError for a Commons-Daemon class, add the Commons-Daemon JAR to the -cp argument when launching jsvc. 5. To stop jsvc: dspace% ps –edf | grep jsvc dspace% kill -9 [PID] 6. The jsvc start and stop commands are part of the /etc/local.d/tomcat script and are discussed in the Startup / Shutdown Scripts section of this document. QSpace Installation SOP 16 11.0 Dspace 1.2 11.1 Introduction The DSpace home provides many valuable resources and links to aid in installation and configuration. Here is the latest DSpace System Documentation, ensure that it matches version of DSpace that is installed. DSpace documentation and source can be found on SourceForge at http://sourceforge.net/projects/dspace/ . 11.2 Environment Setup Environment support for DSpace in the .cshrc file shared by dspace and postgres users should include: CLASSPATH=export/home/dspace/lib/postgresql.jar setenv DSPACE_SRC /export/home/dspace/dspace_src/dspace-1.2-source setenv DSPACE /export/home/dspace/dspace set path = ($path $DSPACE/bin) 11.3 Installation 1. Prepare directories. See the DSpace docs for explanation of required directory trees. dspace% dspace% dspace% dspace% cd ~dspace mkdir dspace mkdir dspace_src mkdir $CATALINA_HOME/webapps/dspace 2. Download DSpace source code and unpack it (this assumes that the binary is in the dspace home directory): dspace% dspace% dspace% dspace% cd ~dspace cp dspace-1.2-source.tar.gz dspace_src/ cd dspace_src gunzip –c dspace-1.2-source.tar.gz | tar –xf - 3. Copy following Java libraries to $DSPACE_SRC/lib:     activation.jar, obtained from http://java.sun.com/products/javabeans/glasgow/jaf.html mail.jar, obtained from http://java.sun.com/products/javamail servlet.jar, obtained from http://java.sun.com/products/jsp/download.html postgresql.jar, found in ~postgres/postgresql-7.4.5/src/interfaces/jdbc/jars QSpace Installation SOP 17 4. With PostgreSQL running, create a dspace database user, and supply password = “password”: dspace% cd $PGSQL/bin dspace% ./createuser -U postgres -d -A -P dspace Password: password 5. Create db to be used by dspace: dspace% cd $PGSQL/bin dspace% ./createdb –U dspace –E UNICODE dspace 6. Edit [dspace-source]/config/dspace.cfg, in particular you'll need to set these properties: dspace.dir = /export/home/dspace/dspace dspace.url = http://qspace.library.queensu.ca dspace.hostname = qspace.library.queensu.ca dspace.name = QSpace at Queen's University config.template.log4j.properties = /export/home/dspace/dspace/config/log4j.properties config.template.log4j-handle-plugin.properties = /export/home/dspace/dspace/config/log4j-handle-plugin.properties config.template.oaicat.properties = /export/home/dspace/dspace/config/oaicat.properties db.url = jdbc:postgresql://localhost:5432/dspace db.driver = org.postgresql.Driver db.username = dspace db.password = password mail.server=post.queensu.ca mail.from.address = qspace-noreply@post.queensu.ca feedback.recipient = qspace@post.queensu.ca mail.admin = qspace-help@post.queensu.ca alert.recipient = qspace-help@post.queensu.ca assetstore.dir = /export/home/dspace/dspace/assetstore history.dir = /export/home/dspace/dspace/history search.dir = /export/home/dspace/dspace/search log.dir = /export/home/dspace/dspace/log upload.temp.dir = /tmp upload.max = 536870912 handle.prefix = 1974 handle.dir = /export/home/dspace/dspace/handle-server webui.site.authenticator = org.dspace.app.webui.SimpleAuthenticator webui.cert.autoregister = true webui.submit.blocktheses = false default.language = en_US thumbnail.maxwidth 80 thumbnail.maxheight 80 QSpace Installation SOP 18 Note: a sample dspace.cfg is included as Appendix B – dspace.cfg. QSpace Installation SOP 19 7. Compile and install DSpace: dspace% cd $DSPACE_SRC dspace% ant fresh_install 8. Copy dspace.war and dspace-oai.war to the Tomcat webapps directory: dspace% cd $DSPACE_SRC dspace% cp $DSPACE_SRC/build/*.war $CATALINA_HOME/webapps 9. Create an administrator account: dspace% cd $DSPACE/bin dspace% create-administrator You will be prompted for administrator’s personal information (presumably your information). Supply an email address, a first name, a last name, and a chosen password. Email: First Name: Last Name: Password: firstName.lastName@queensu.ca firstName lastName password QSpace Installation SOP 20 12.0 Setup Tomcat as daemon using jsvc 1. Edit $CATALINA_HOME/conf/server.xml below where it reads: Setup a connector for port 80: 2. Edit $CATALINA_HOME/conf/Catalina/localhost/dspace.xml to make DSpace the default webapp: 3. Startup jsvc. This startup command will use the –user flag allowing process to start as a root owned process that can bind to privileged ports, then fork off a dspace copy of the process that will not expose root process to malicious traffic: rootr# $CATALINA_HOME/bin/jsvc –pidfile $CATALINA_HOME/jsvc.pid \ –user dspace –home $JAVA_HOME –Dcatalina.home=$CATALINA_HOME \ –Djava.io.tmpdir=/tmp –outfile $CATALINA_HOME/logs/ atalina.out \ –errfile ‘&1’ $CATALINA_OPTS \ –cp $CLASSPATH org.apache.catalina.startup.Bootstrap This command is part of the /etc/local.d/tomcat script, and is discussed in the Startup / Shutdown Scripts section of this document. 4. You should now be able to access DSpace with either of: http://qspace.library.queensu.ca https://qspace.library.queensu.ca 5. DSpace admin interface: https://qspace.library.queensu.ca/dspace-admin QSpace Installation SOP 21 13.0 Configuring Tomcat for SSL 1. Edit $CATALINA_HOME/conf/server.xml: Setup a connector for port 443: Note: the keystorePass variable (above) must match password used when creating keystore below. 2. Create a new keystore from scratch, containing a single self-signed Certificate (see the SSL Config HOWTO in the Tomcat 5 documentation bundle for more detailed instructions): Dspace% cd ~dspace Dspace% $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA Enter password: password File .keystore will be written to ~dspace/.keystore. QSpace Installation SOP 22 14.0 Configure Tomcat with Certificate from Entrust Configuring Tomcat for SSL is a prerequisite to installing a Certificate from Entrust. 1. Create Certificate Signing Request (CSR). Running the following command in dspace home, the location of the .keystore file, will create file certreq.csr. dspace% cd ~dspace dspace% keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr \ -keystore .keystorre 2. Request an Entrust certificate from Don Coleman (ITS-Dupuis). Be prepared to provide an account code to bill against. Don will forward a link to a form to be used to submit the CSR (certreq.csr) created in previous step. 3. A CSR may take a couple days. An email will be delivered with a link to the new SSL Certificate. Follow the link to collect the Certificate. 4. Entrust Certificate: Domain: qspace.library.queensu.ca Expiry: Sep 28, 2005 5. Import the SSL Cretificate: dspace% JAVA_HOME/bin/keytool -import -alias tomcat -keystore .keystore trustcacerts -file .Entrust_certificate Enter password: password Certificate reply was installed in keystore QSpace Installation SOP 23 15.0 Handle server setup The DSpace instructions for Handle sever setup are very confusing. Use these instructions instead: 1. Make the handle server, after setting appropriate parameters in dspace.cfg. Appendix B illustrates a sample dspace.cfg file. You will not be able to supply a “handle-prefix” in dspace.cfg yet (see step 6). dspace% cd $DSPACE/bin dspace%./make-handle-config 2. This generates a number of files, including a setup file that needs to be sent to CNRI. Find the file: $DSPACE/handle-server/sitebndl.zip 3. Email sitebundle.zip to hdladmin@cnri.reston.va.us at CNRI requesting a Handle Prefix. 4. Once you receive the return email, you must edit the Handle configuration file ($DSPACE/handle-server/config.dct). Just as the DSpace instructions say, make the "storage_type" = "CUSTOM" change, as well as the "storage_class" = "org.dspace.handle.HandlePlugin" change. 5. While still in config.dct, update any lines like YOUR_NAMING_AUTHORITY with the appropriate number as sent to you in the email from CNRI. This change must be made in three places, under server_admins, backup_admins, and replication_admins. 6. Edit $DSPACE/config/dspace.cfg, setting handle.prefix = 1974, and setting handle.dir = $DSPACE/handle-server. 7. Start handle server: dspace% $DSPACE/bin/start-handle-server 8. Stop handle server: dspace% ps –edf | grep log4j-handle dspace% kill -9 [PID] 9. Startup / Shutdown commands are part of the /etc/local.d/handle script, and are discussed in the Startup / Shutdown Scripts section of this document. QSpace Installation SOP 24 16.0 OAI-PMH The QSpace OAI-PMH interface is available at the address: https://qspace.library.queensu.ca/dspace-oai No configuration was necessary to have OAI interface work. Try the following requests to ensure it is behaving correctly: https://qspace.library.queensu.ca/dspace-oai/request?verb=Identify https://qspace.library.queensu.ca/dspace-oai/request?verb=ListSets QSpace Installation SOP 25 17.0 Cron Jobs The following crontab entries for dspace and postgres users should be added. 17.1 dspace crontab entries: # Clean up deleted bitstreams at 12.00pa every day 0 0 * * * /export/home/dspace/dspace/bin/cleanup > /dev/null 2>&1 # Run the media filter at 01:00 every day 0 1 * * * /export/home/dspace/dspace/bin/filter-media > /dev/null 2>&1 # Send out QSpace subscription e-mails at 02:00 every day 0 2 * * * /export/home/dspace/dspace/bin/sub-daily > /dev/null 2>&1 17.2 postgres crontab entries: # Clean up PostgreSQL db nightly at 4 am 0 4 * * * /export/home/postgres/bin/vacuumdb_wrapper > /dev/null 2>&1 17.3 root crontab entries: The root crontab will compile and email a daily report including disk usage, and certificate expiry information to dspace-admin (see Email Aliases). There are also two temporary crontab entires for root to address a connection exhaustion problem with DSpace 1.2.0. The problem has been fixed in DSpace 1.2.1. When QSpace is migrated to DSpace 1.2.1, theese root crontab entries can be removed. # QSpace - stop/start tomcat to free up hung connections # temp fix to a connection exhaustion bug # bug fix is expected in DSpace 1.2.1 # QSpace_connExhaustRestart.sh hard – forced restart # QSpace_connExhaustRestart.sh hard – conditional restart # 0 3 * * * /export/home/dspace/bin/QSpace_connExhaustRestart.sh hard 5,10,15,20,25,30,35,40,45,50,55 * * * * /export/home/dspace/bin/QSpace_connExhaustRestart.sh soft # # QSpace - send daily report of disk usage and ssl certificates 0 4 * * * /export/home/dspace/bin/QSpace_dailyReport.sh > /dev/null 2>&1 QSpace Installation SOP 26 18.0 Startup / Shutdown Scripts The following startup and shutdown script links were created. Solaris during startup, shutdown, or reboot will use the links in /etc/rc2.d/ to startup or shutdown daemon processes. The actual scripts reside in /etc/local.d/. 18.1 /etc/rc2.d lrwxrwxrwx 1 root lrwxrwxrwx 1 root lrwxrwxrwx 1 root lrwxrwxrwx 1 root lrwxrwxrwx 1 root lrwxrwxrwx 1 root 18.2 /etc/local.d -rwxr-xr-x -rwxr-xr-x -rwxr-xr-x -rwxr-xr-x 1 root 1 root 1 root 1 root other other other other handle* postgres* sshd* tomcat* other other other other other other K89postgres -> /etc/local.d/postgres* K90tomcat -> /etc/local.d/tomcat* K91handle -> /etc/local.d/handle* S89postgres -> /etc/local.d/postgres* S90tomcat -> /etc/local.d/tomcat* S91handle -> /etc/local.d/handle* QSpace Installation SOP 27 18.3 /etc/local.d/handle #!/bin/sh # # Startup for DSpace handle server # # created 04/11/26 SR case "$1" in 'start') echo "\nHandle Server starting..." /bin/su - dspace -c "/export/home/dspace/dspace/bin/start-handle-server" ;; 'stop') echo "\nHandle Server stopping..." PID=`/usr/bin/ps -ef | grep log4j-handle | awk '{print $2}'` if [ ! -z "$PID" ] ; then bin/su - dspace -c "/usr/bin/kill -9 ${PID}" fi ;; *) echo "Usage: $0 { start | stop }" ;; esac exit 0 QSpace Installation SOP 28 18.4 /etc/local.d/postgres #!/bin/sh # # Startup for PostgreSQL 7.3.2 # # created 04/11/26 SR case "$1" in 'start') if [ -f /export/home/postgres/pgsql/bin/pg_ctl ] ; then echo "\n PostgreSQL 7.3.2 starting..." /bin/su - postgres -c "/export/home/postgres/pgsql/bin/pg_ctl \ -D /export/home/postgres/pgsql/data -l logfile start" fi ;; 'stop') if [ -f /export/home/postgres/pgsql/bin/pg_ctl ] ; then echo "\n PostgreSQL 7.3.2 stopping..." /bin/su - postgres -c "/export/home/postgres/pgsql/bin/pg_ctl \ -m fast stop" fi ;; *) echo "Usage: $0 { start | stop }" ;; esac exit 0 QSpace Installation SOP 29 18.5 /etc/local.d/tomcat #!/bin/sh # # Start/stop Tomcat using jsvc. To have Tomcat run on port 80 modify # server.xml: # # # JAVA_HOME=/usr/j2se CATALINA_HOME=/export/home/dspace/tomcat/jakarta-tomcat-5.0.28 DAEMON_HOME=/export/home/dspace/tomcat/jakarta-tomcat-5.0.28/bin TOMCAT_USER=dspace TMP_DIR=/tmp CATALINA_OPTS= CLASSPATH=$JAVA_HOME/lib/tools.jar:$CATALINA_HOME/bin/commonsdaemon.jar:$CATALINA_HOME/bin/bootstrap.jar case "$1" in start) $DAEMON_HOME/jsvc -debug -pidfile $CATALINA_HOME/jsvc.pid \ -user $TOMCAT_USER -home $JAVA_HOME \ -Dcatalina.home=$CATALINA_HOME -Djava.io.tmpdir=$TMP_DIR \ -outfile $CATALINA_HOME/logs/catalina.out -errfile '&1' \ $CATALINA_OPTS -cp \ $CLASSPATH org.apache.catalina.startup.Bootstrap ;; stop) PID=`cat $CATALINA_HOME/jsvc.pid` kill $PID rm $CATALINA_HOME/jsvc.pid ;; *) echo "Usage: $0 { start | stop }" exit 1;; esac QSpace Installation SOP 30 19.0 Email Aliases The following email aliases have been configured: post.queensu.ca /etc/mail/aliases qspace-noreply: qspace-help: qspace-info: ryan ryan qspace carrick.its.queensu.ca /etc/mail/aliases dspace-admin: ryan@post.queensu.ca The qspace-noreply and qspace-help should be aliased to the QSpace technical lead, while qspace-info should be aliased to the project lead. The dspace-admin email can be used for system tasks on carrick.its.queensu.ca related to QSpace. An example is emailing reports, status, or alerts. QSpace technical lead has root access to change dspace-admin. After editing the file, run newaliases as root to force a reread of alias file. To change the aliases on post.queenus.ca contact the Post administrator at ITS. QSpace Installation SOP 31 Appendix A – .cshrc file shared by dspace and postgres users umask 022 stty erase ^H stty kill ^u setenv EDITOR vi # ========================================== # PATH notes: # gcc 3.4.1 /opt/csw/gcc3/bin must precede # gcc 2.8.1 /opt/local/bin # ant 1.6.2 /opt/csw/bin/ant must precede # ant 1.4.1 /usr/sfw/bin # ========================================== set path = ( . ) set path = ($path ~/bin) set path = ($path /usr/bin) set path = ($path /usr/sbin) set path = ($path /opt/csw/gcc3/bin) set path = ($path /opt/local/bin) set path = ($path /etc) set path = ($path /usr/openwin/bin) set path = ($path /usr/local/bin) set path = ($path /usr/dt/bin) set path = ($path /usr/ccs/bin) set path = ($path /usr/ccs/lib) set path = ($path /usr/ucb) set path = ($path /opt/csw/bin) set path = ($path /opt/csw/include) set path = ($path /usr/sfw/bin) setenv LD_LIBRARY_PATH /export/home/postgres/pgsql/lib:/opt/csw/lib: /opt/csw/gcc3/lib:/usr/local/lib setenv MANPATH "/export/home/postgres/pgsql/man:/usr/j2se/man:/opt/local/man: /usr/openwin/share/man:/usr/dt/man:/usr/man:/usr/sfw/man:/opt/csw/share/man: /usr/local/man" # APACHE ANT 1.6.2 # ---------------setenv ANT_HOME /opt/csw/ # JAVA 2 SECOND EDITION # --------------------setenv JAVA_HOME /usr/j2se setenv CLASSPATH .:/usr/j2se/jre:/usr/j2se/lib/tools.jar: /opt/csw/lib/ant/ant.jar:/export/home/dspace/lib/postgresql.jar: /export/home/dspace/tomcat/jakarta-tomcat-5.0.28/common/lib set path = ($JAVA_HOME/bin $path) # POSTGRES 7.4.5 # -------------setenv PG_HOME /export/home/postgres setenv PG_SRC $PG_HOME/postgresql-7.4.5 setenv PGSQL $PG_HOME/pgsql setenv PGDATA $PGSQL/data QSpace Installation SOP 32 set path = ($path $PGSQL/bin) QSpace Installation SOP 33 # TOMCAT 5.0.28 # ------------setenv JAVA_OPTS "-Xmx512m -Xms64M -Dfile.encoding=UTF-8" setenv CATALINA_HOME /export/home/dspace/tomcat/jakarta-tomcat-5.0.28 set path = ($path $CATALINA_HOME/bin) setenv JSSE_HOME $JAVA_HOME/jre/lib # DSPACE 1.2 # ========== setenv DSPACE_SRC /export/home/dspace/dspace_src/dspace-1.2-source setenv DSPACE /export/home/dspace/dspace set path = ($path $DSPACE/bin) # Set prompt if ( $?prompt ) then set history=1000 savehist=50 filec alias cd 'chdir \!* ; setprompt' alias setprompt 'set prompt="`whoami`@`hostname` ($cwd:t) \! % "' setprompt endif # TCSH set autoexpand set autocorrect set autolist set correct=all set fignore=(.o, .OLD) set rmstar set noclobber set filec # File Completion source /export/home/dspace/.alias QSpace Installation SOP 34 Appendix B– dspace.cfg # DSpace Configuration # Revision: $Revision: 1.34 $ # Date: $Date: 2004/06/17 17:33:44 $ ##### Basic information ###### # DSpace installation directory dspace.dir = /export/home/dspace/dspace # DSpace base URL. Include port number etc., but NOT trailing slash dspace.url = https://qspace.library.queensu.ca # DSpace host name - should match base URL. dspace.hostname = qspace.library.queensu.ca # Name of the site dspace.name = QSpace at Queen's University ##### Destinations for configuration files for other tools ##### # Comment out any lines corresponding to files you don't need, so they # don't get copied # Example Apache HTTPD configuration # config.template.apache13.conf = /export/home/dspace/dspace/config/httpd.conf config.template.log4j.properties = /export/home/dspace/dspace/config/log4j.properties config.template.log4j-handle-plugin.properties = /export/home/dspace/dspace/config/log4j-handle-plugin.properties config.template.oaicat.properties = /export/home/dspace/dspace/config/oaicat.properties ##### Database settings ##### # URL for connecting to database db.url = jdbc:postgresql://localhost:5432/dspace # JDBC Driver db.driver = org.postgresql.Driver # Database username and password db.username = dspace db.password = password # Connection pool parameters # Maximum number of DB connections in pool #db.maxconnections = 30 # <=DEFAULT db.maxconnections = 100 # Max wait before giving up if all connections in pool are busy (millisec) #db.maxwait = 5000 # <=DEFAULT db.maxwait = 10000 Do not include port number QSpace Installation SOP 35 # Maximum number of idle connections in pool (-1 = unlimited) #db.maxidle = -1 # <=DEFAULT #db.maxidle = 30 ##### Email settings ###### # SMTP mail server mail.server=post.queensu.ca # From address for mail mail.from.address = qspace-noreply@post.queensu.ca # Currently limited to one recipient! feedback.recipient = qspace@post.queensu.ca # General site administration (Webmaster) e-mail mail.admin = qspace-help@post.queensu.ca # Recipient for server errors and alerts alert.recipient = qspace-help@post.queensu.ca ##### File Storage ###### # Asset (bitstream) store number 0 (zero) assetstore.dir = /export/home/dspace/dspace/assetstore # Specify extra asset stores like this, counting from 1 upwards: # assetstore.dir.1 = /second/assetstore # assetstore.dir.2 = /third/assetstore # Specify the number of the store to use for new bitstreams with this property # The default is 0 (zero) which corresponds to the 'assetstore.dir' above # assetstore.incoming = 1 # Directory for history serializations history.dir = /export/home/dspace/dspace/history # Where to put search index files search.dir = /export/home/dspace/dspace/search # Where to put the logs log.dir = /export/home/dspace/dspace/log # Where to temporarily store uploaded files upload.temp.dir = /tmp # Maximum size of uploaded files in bytes, must be positive # 512Mb upload.max = 536870912 ##### Handle settings ###### # CNRI Handle prefix QSpace Installation SOP 36 handle.prefix = 1974 # Directory for installing Handle server files handle.dir = /export/home/dspace/dspace/handle-server ##### Web UI Settings ###### # Site authenticator - must implement org.dspace.app.webui.SiteAuthenticator webui.site.authenticator = org.dspace.app.webui.SimpleAuthenticator # Certificate authority webui.cert.ca = /export/home/dspace/dspace/etc/certificate-ca.pem # If a user presents a valid Web certificate, but does not have an e-person # record, should they automatically be given a new e-person record? webui.cert.autoregister = true # Should the submit UI block submissions marked as theses? webui.submit.blocktheses = false ##### SFX Server ##### # SFX query is appended to this URL. If this property is commented out or # omitted, SFX support is switched off. # sfx.server.url = http://sfx.myu.edu:8888/sfx? ##### Ingest settings ##### # Default language for content of submissions default.language = en_US ##### Media Filter settings ##### # maximum width and height of generated thumbnails thumbnail.maxwidth 80 thumbnail.maxheight 80 #### Creative Commons settings ###### # are Creative Commons licenses used in submission? webui.submit.enable-cc = false #### Proxy Settings ###### # uncomment and specify both properties if proxy server required # proxy server for external http reqsts - use regular hostname without port # #http.proxy.host = # port number of proxy server #http.proxy.port QSpace Installation SOP 37