The document provides step-by-step instructions for installing and configuring DSpace, an open source digital repository software, on a Linux system. It describes installing and configuring required software components like Java, PostgreSQL, Apache Ant, Apache Tomcat, and DSpace itself. The instructions also cover configuring a mail server and setting cron jobs for maintenance tasks. Troubleshooting tips are provided for common errors.

1. RAJEEV KUMAR Computer Programming Officer SAARC Doc. Centre, New Delhi Dspce

2. Required Software Operating System: Linux: Redhat/Fedora, Suse,Mandrake, Debian etc. Unix: Solaris (Sun system) ‏ , HP-UX (Hewlett Packard) ‏ , AIX (IBM), Mac OS X Mail server (Sendmail/postfix) RDBMS (postgres/oracle) DSpace Java compiler (jdk) Java Servlet Container Ant Java build tool, similar to make in the world of ‘C’ Complies java programs of dspace source code, generates war files

3. Role of RDBMS Database backend (postgres/oracle) of DSpace, stores information on: Communities Collection Members - passwords E-groups etc.

4. Step1: Linux Installation Strongly advise to Load Linux fully unless you are a Linux Guru Make sure the following are installed Mail server Copy all the files provided on CD-ROM tar.gz files in /dspace directory Or Download the following (or latest) files from Internet jdk1.5.0_02.tar.gz (java compiler) apache-ant-1.7.0-bin.tar.gz (ant) postgresql-8.2.7.tar.gz (RDBMS) apache-tomcat-5.5.25.tar.gz (servlet container) postgresql-8.3-603.jdbc2.jar (jdbc driver for postgres) dspace-source-1.4.2.tar.gz (dspace software)

5. Step 2: Installation of Java Install Java 1.4 or later You need to login as Linux root user to install Use the command bellow to install #cd /dspace #tar –zxvf jdk1.5.0_02.tar.gz [to uncompress the file] #rm /usr/bin/java [remove the original java binary if any] #cd /usr/bin #ln -s /dspace/jdk1.5.0_02/bin/java java [create Symbolic link to newly installed java if any]

6. Step 2: Installation of Java (contd..) Define java home PATH by the commands: #JAVA_HOME=/dspace/jdk1.5.0_02 [ setting variable to point Java directory] #export JAVA_HOME To set the environment variable JAVA_HOME permanently (get set at the time of system boot) do the following #vi /etc/profile (open /etc/profile file) Add the two lines bellow at the end of the file. JAVA_HOME=/dspace/jdk1.5.0_02 export JAVA_HOME Save the file (press ESC :wq), this will set the variable JAVA_HOME when system boots

7. Step 3:Configuring Mail Server You may use any of the following mail servers Sendmail Postfix Exim Note: Here sendmail is explained

8. Step 3: Sendmail configuration: Simple approach Case I:If your organization has a mail server Open /etc/mail/sendmail.mc Replace the line having dnl define(`SMART_HOST', `smtp.your.provider')dnl Remove dnl and enter your mail server name Ex: define(`SMART_HOST', `nsdl.niscair.res.in')dnl

9. Step 3: sendmail configuration contd.. Case II: If you want to use the same system as mail server Comment the following line DAEMON_OPTIONS(`Port=smtp,Addr=127.0.0.1, Name=MTA')dnl Ex: dnl # DAEMON_OPTIONS(`Port=smtp,Addr=127.0.0.1, Name=MTA')dnl

10. Step 3: sendmail configuration contd.. Save the file (press ESC :wq) Run #m4 /etc/mail/sendmail.mc > /etc/mail/sendmail.cf #service sendmail restart OR #/etc/init.d/sendmail restart

11. Step 4: Apache-ant installation Check apache ant is already installed or not using the command: #which ant You need to login as Linux root user If not installed type the following commands to install #cd /dspace #tar -zxvf apache-ant-1.7.0-bin.tar (extract files)

12. Step 4: Apache-ant installation Define a path to the apache ant binary by the commands #PATH=$PATH:/dspace/apache-ant-1.7.0 /bin #export PATH To add apache-ant path in PATH variable permanently do the following Open the file /etc/profile and add the two line below towards the end of the file. #vi /etc/profile #PATH=$PATH:/dspace/apache-ant-1.7.0 /bin #export PATH Save the file (Press ESC :wq)

13. Step 5: PostgreSQL installation You need to become Linux root user to install postgresql Use the following commands to install #cd /dspace #tar -zxvf postgresql-8.2.7.tar.gz (extract files) #cd /dspace/postgresql-8.2.7 #./configure (it will install postgres in /usr/local/pgsql directory) #gmake #gmake install #useradd postgres [ create postgres user] #mkdir /usr/local/pgsql/data #chown -R postgres /usr/local/pgsql/data (change owner of the data directory to postgres) #su - postrgres

14. Step 5: PostgreSQL installation (contd..) Start posgres by doing the following $/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data $/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data start Create a dspace database, owned by the dspace –a PostgreSQL user by doing the following $/usr/local/pgsql/bin/createuser -U postgres -d -A -P dspace [Enter a password for the DSpace database] $/usr/local/pgsql/bin/createdb -U dspace -E UNICODE dspace $vi /usr/local/pgsql/data/postgresql.conf uncomment the line starting: listen_addresses = 'localhost' (i.e. delete # at the beginning of line) $vi /usr/local/pgsql/data/pg_hba.conf add follwing line in the section # IPv4-style local connections host dspace dspace 127.0.0.1 255.255.255.255 md5 Logout from postgres user #exit

15. Step 6: Installation of Apache Tomcat You have to become root user and type the following commands #cd /dspace #tar -zxvf apache-tomcat-5.5.25.tar.gz [extract files] Set the environment variable JAVA_OPTS="-Xmx512M -Xms64M -Dfile.encoding=UTF-8" by doing the following #JAVA_OPTS="-Xmx512M -Xms64M -Dfile.encoding=UTF-8" #export JAVA_OPTS To make it permanent do the following: # vi /etc/profile and add the two line below towards the end of the file. JAVA_OPTS="-Xmx512M -Xms64M -Dfile.encoding=UTF-8" export JAVA_OPTS Save the file (type ESC :wq)

16. Step 6: Installation of Apache Tomcat # vi /dspace/apache-tomcat-5.5.25/conf/server.xml locate the following section <!-- Define a non-SSL HTTP/1.1 Connector on port 8080 --> <Connector port=&quot;8080&quot; maxThreads=&quot;150&quot; minSpareThreads=&quot;25&quot; maxSpareThreads=&quot;75&quot; enableLookups=&quot;false&quot; redirectPort=&quot;8443&quot; acceptCount=&quot;100&quot; connectionTimeout=&quot;20000&quot; disableUploadTimeout=&quot;true&quot; /> and add the line URIEncoding=&quot;UTF-8&quot; in this section like <!-- Define a non-SSL HTTP/1.1 Connector on port 80 --> < Connector port=&quot;80&quot; maxThreads=&quot;150&quot; minSpareThreads=&quot;25&quot; maxSpareThreads=&quot;75&quot; enableLookups=&quot;false&quot; redirectPort=&quot;8443&quot; acceptCount=&quot;100&quot; connectionTimeout=&quot;20000&quot; disableUploadTimeout=&quot;true&quot; URIEncoding=&quot;UTF-8&quot; /> Save the file (press ESC :wq)

17. Step 7: Installation of Dspace You have to login as Linux root user Create the DSpace Linux user by using the commands #groupadd dspace [create group] #useradd dspace –g dspace [ create dspace user] #chown -R dspace.dspace /dspace/apache-tomcat-5.5.25 [ change the owner and group of tomcat directory to dspace, so as to run as dspace user #cd /dspace #tar -zxvf dspace-source-1.4.2.tar.gz It creates a directory name like dspace-1.4.2-source Copy jdbc driver for postgresql to /dspace/dspace-1.4.2-source/lib directory. To do this perform the following: Copy a jdbc driver for postgresql i.e. postgresql-8.3-603.jdbc2.jar file to /dspace/dspace-1.4.2-source/lib #cp /dspace/ postgresql-8.3-603.jdbc2.jarr /dspace/dspace-1.4.2-source/lib #chown -R dspace.dspace /dspace/dspace-1.4.2-source [ change the owner and group of dspace directory to dspace]

18. Step 7: Installation of Dspace contd.. #su -l dspace $cd /dspace/dspace-1.4.2-source Open the file /dspace/dspace-1.4.2-source/config/dspace.cfg and set the following properties $vi /dspace/dspace-1.4.2-source/config/dspace.cfg dspace.url = [like http://192.168.3.203/dspace] dspace.hostname = [hotsname or IP address of server] dspace.name =[ dspace name like name of your Institution eg. NISCAIR Digital Library] db.password = [the password you entered in the last step of postgesql installation] mail.server =[hostname or IP address of server ex. mail.niscair.res.in] mail.from.address = [email address] feedback.recipient =[email address] mail.admin = [email address of admin] alert.recipient =[email address (not essential but very useful!)] Save the file $cd /dspace/dspace-1.4.2-source

19. Step 7: Installation of Dspace contd.. Compile and install DSpace by doing the following $/dspace/apache-ant-1.7.0 /bin/ant fresh_install $cp /dspace/dspace-1.4.2-source/build/*.war /dspace/apache-tomcat-5.5.25/webapps/dspace/ Define CLASSPATH for dspace classes by doing following $vi /dspace/dspace-1.4.2-source/bin/dsrun Append following lines at the end of file CLASSPATH=$CLASSPATH:/dspace/apache-tomcat-5.5.25/webapps/dspace/WEB-INF/classes FULLPATH=$CLASSPATH:$jJARS:$DSPACEDIR/config Create an initial administrator account by the command $/dspace/dspace-1.4.2-source/bin/create-administrator You need to provide some information like admin user name, email ID and so on

20. Step 7: Installation of Dspace contd.. Start tomcat by the command $/dspace/apache-tomcat-5.5.25 /bin/startup.sh Point your browser to the URL: http://HOSTNAME_OR_IP_ADDRESS_OF_SERVER/dspace Access admin UI by point your browser to the URL: http://HOSTNAME_OR_IP_ADDRESS_OF_SERVER/dspace/dspace-admin eg. http://192.168.3.203/dspace

21. Installation of Dspace- Summary Dspace is based on open source technlogy The installation process is some what complex for new users The following components should properly work : Postgresql server Jdbc driver for postgres server Apache tomcat Initially there may be few errors related to above components if not properly installed

22. Cron jobs To perform certain task periodically we may use cron jobs by typing following command: # crontab -e # Send out subscription e-mails at 01:00 every day 0 1 * * * /dspace/bin/sub-daily # Run the media filter at 02:00 every day 0 2 * * * /dspace/bin/filter-media # Generate full-text index at 2.15 an 15 2 * * * /dspace/bin/index-all # Clean up the database nightly at 2.40am 40 2 * * * vacuumdb --analyze dspace > /dev/null 2>&1&quot; > /var/spool/cron/dspace * * * * * Minute 0-59 Hour 0-23 (0 = midnight) Day 1-31 Month 1-12 Weekday 0-6 (0 = Sunday) ‏

23. Starting apache tomcat on boot To make your repository start at the boot time adds the following to /etc/rc.d/rc.local su –l dspace –c ‘ /dspace/apache-tomcat-5.5.25/bin/startup.sh

24. Trouble shooting.. Check your environment variable by giving the following commands echo $PATH echo $JAVA_HOME See whether java’s bin directory is in your PATH JAVA_HOME is pointing to Java directory Change your /dspace/.bash_profile

25. Trouble shooting: while fresh_install Mostly you get database related errors, the cause could be You did not copy jdbc drivers in dspace-source/lib directory Or changes in the postgresql .conf file were not made at all, or done improperly

26. Trouble shooting: Once you launch DSpace If you do not see dspace on the screen Tomcat was not launched Or the port (8080) was already in use You started tomcat second time Solution Kill tomcat if you have started second time (using ps –a | grep java or killall java Change to another port in tomcat/config/server.xml Check $TOMCAT-HOME/logs/catalina.out For specific problem identification

27. Troubleshooting: Internal System Error Most common error message To generic and is not specific The reasons could be many Check /dspace/log/dspace.log file, which may provide the specific problem

28. Trouble-shooting: Fails to sendmal Mail configuration is wrong You did not make mail server entry in /dspace/conf/dspace.cfg file DNS problem You do not have FQDN (Fully Qualified Domain Name) for you system It should hostname.domainname Ex: localhost.localdomain (not just localhost) ‏ nsdl.niscair.res.in ( not jst nsdl) ‏

29. LOG FILES $TOMCAT_HOME/logs/catalina.out /dspace/log/dspace.log

30. Thanks