SUNScholar/Prepare Ubuntu

It is vitally essential that you have first completed the installation of Ubuntu with the LAMP stack.

If you have not, please do so now.

Introduction

Before Dspace can be installed and setup we have to prepare the server with the software needed by Dspace. Because Dspace is essentially a Java Webapp that uses a SQL database, the following steps simply setup the Ubuntu Server as a Java Webapp server with a SQL database server. Unfortunately the Ubuntu server does not come with a default Java Webapp SQL Database Server setup, so we have to do it manually.

Step 1. Login to the remote server

On your client PC with the Ubuntu desktop live CD, click on: Applications => Accessories => Terminal to open a command line terminal.

Login to your remote server as the "dspace" user by typing as follows in the terminal.

ssh dspace@%hostname%

Replace %hostname% with the hostname of your server.

Step 2. Become the "root" user

To install all the Dspace dependencies become the "root" user by typing the following in terminal.

sudo -i

Step 3. Install Java Software Dependencies

Step 3.1: Install Java 6 Development Kit

Type as follows:

aptitude install openjdk-6-jdk

Afterwards make it available system wide:

update-java-alternatives -s java-6-openjdk

Step 3.2: Install Java Ant Compiler

Type as follows:

aptitude install ant ant-optional

Step 4. Setup Maven2 Java Installer

Step 4.1: Install Maven2

Type as follows:

aptitude install maven2

Step 4.2: Create the Maven2 home folder

Type the following;

mkdir /home/dspace/.m2

Give the "dspace" user full ownership of the folder by typing the following:

chown dspace.dspace -R /home/dspace/.m2

Step 4.3: Setup the Maven config file

The Maven 2 proxy configuration file is only needed if your connection to the internet is via a campus proxy server. You can skip this step if you have a direct connection to the internet.

Maven proxy notes

Use the proxy settings for your campus. Check with your IT department. You need to ensure that the following two sites are allowed to pass through your campus proxy server (i.e. add them to the ACL configuration on the Squid proxy server):

1. maven.apache.org
2. repo1.maven.org

More information about Maven can be found here at the following links:

• http://maven.apache.org/guides/mini/guide-configuring-maven.html
• http://maven.apache.org/guides/mini/guide-proxies.html

Maven proxy config file

Type the following to enable Maven proxy settings:

nano /home/dspace/.m2/settings.xml

Tip: It is always a good idea to maximise the open nano window so that the copy and paste of long lines does not wrap around.

Add the following:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository/>
  <interactiveMode/>
  <usePluginRegistry/>
  <offline/>
  <pluginGroups/>
  <servers/>
  <mirrors/>
  <proxies>
    <proxy>
      <id>Maties</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>lib-proxy.sun.ac.za</host>
      <port>3128</port>
      <username></username>
      <password></password>
      <nonProxyHosts></nonProxyHosts>
    </proxy>
  </proxies>
  <profiles/>
  <activeProfiles/>
</settings>

Save the file by pressing CTL+O and then CTL+X on the keyboard.

Step 5. Setup Tomcat Java Webapp Server

Step 5.1: Install Tomcat 6

Type the following:

aptitude install tomcat6

Step 5.2: Enable "authbind" for Tomcat

To enable Tomcat to listen on a privileged port below 100, we need to enable "authbind". Edit the /etc/default/tomcat6 file as follows:

nano /etc/default/tomcat6

Remove the hash sign from in front of the authbind parameter and change authbind to yes as follows

# If you run Tomcat on port numbers that are all higher than 1023, then you
# do not need authbind.  It is used for binding Tomcat to lower port numbers.
# NOTE: authbind works only with IPv4.  Do not enable it when using IPv6.
# (yes/no, default: no)
AUTHBIND=yes

Now we need to tell "authbind" that Tomcat6 is allowed to use lower port numbers. Type the following commands:

touch /etc/authbind/byport/80

touch /etc/authbind/byport/443

chmod 0755 /etc/authbind/byport/80

chmod 0755 /etc/authbind/byport/443

chown tomcat6.tomca6 /etc/authbind/byport/80

chown tomcat6.tomcat6 /etc/authbind/byport/443

Now Tomcat6 has permission to use ports 80 and 443.

Now we tell the Tomcat6 server to listen on these ports. Edit the following file.

nano /etc/tomcat6/server.xml

Find the connectors for port 8080 and change it to port 80, then enable the 8443 port connector and change it to 443. Save the file.

Step 5.3: Setup Tomcat admin users

Type as follows:

nano /etc/tomcat6/tomcat-users.xml

Delete all the contents of the file and add the following admin and manager roles with a password.

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="dspace" password="dspace" roles="admin,manager"/>
</tomcat-users>

Save the file by pressing CTL+O and then CTL+X on the keyboard.

Step 5.5: Restart the Tomcat server

Now restart the tomcat server as follows:

/etc/init.d/tomcat6 restart

Step 5.6: Post Tomcat installation checks

Now let's look if all went well:

netstat -tapn | grep java

Tomcat should be listening on ports 80 and 443:

root@server1:~# netstat -tapn | grep java
tcp        0      0 127.0.0.1:8005          0.0.0.0:*               LISTEN      8063/java       
tcp        0      0 0.0.0.0:80              0.0.0.0:*               LISTEN      8063/java       
tcp        0      0 0.0.0.0:443             0.0.0.0:*               LISTEN      8063/java       
tcp        0      0 127.0.0.1:34113         127.0.0.1:5432          ESTABLISHED 8063/java       
tcp        0      0 127.0.0.1:34112         127.0.0.1:5432          ESTABLISHED 8063/java 
root@server1:~#

Thats it, now you have a working Java webapp server.

Step 7. Install PostgreSQL

Dspace uses the PostgreSQL database server for the main catalog database. The following procedure installs the PostgreSQL server and creates the "dspace" database and "dspace" database user with the default password.

Step 7.1: Install PostgreSQL

aptitude install postgresql-8.4 libpg-java

Step 7.2: Setup PostgreSQL admin password

Change database user permissions to "trust" only.

sed -i 's/ident sameuser$/trust/' /etc/postgresql/8.4/main/pg_hba.conf

Restart database server.

/etc/init.d/postgresql-8.4 restart

Open a database shell...

psql -U postgres

... and set the password:

alter role postgres with password 'dspace';

Quit the database shell.

\q

Change database user permissions from "trust" to "md5" password.

sed -i 's/trust$/md5/' /etc/postgresql/8.4/main/pg_hba.conf

Restart database server.

/etc/init.d/postgresql-8.4 restart

Step 7.3: Create the PostgreSQL 'dspace' database

Create the "dspace" database with the "dspace" database user.

sudo -u dspace createdb -U dspace -E UNICODE dspace

Step 7.4: Create the PostgreSQL 'dspace' user

Create the "dspace" database user with full privileges.

sudo -u postgres createuser -U postgres -d -A -P dspace

If asked the following:

Shall the new role be allowed to create more new roles? (y/n) y

Answer "y" for yes.

Step 7.5: Setup database host and user access permissions

Type the following:

echo "host dspace dspace 127.0.0.1/32 md5" >> /etc/postgresql/8.4/main/pg_hba.conf

Step 7.6: Setup number of client connections

Edit the postgresql config file:

nano /etc/postgresql/8.4/main/postgresql.conf

Change the number of "max_connections" to 300, save the file and exit.

Step 7.7: Increase the kernel shared memory for postgresql connections

Edit the "/etc/sysctl.conf" file:

nano /etc/sysctl.conf

Copy and paste the following:

 # Postgres connections
kernel.shmmax = 500000000
kernel.shmall = 500000000

Type the following in a terminal:

sudo sysctl -p

Step 7.8: Restart the PostgreSQL server

Type the following:

/etc/init.d/postgresql-8.4 restart

Step 8 - Setup the Postfix mail server

Step 8.1: Install the software

In order to be able to use email with your Dspace server install the postfix mail server as follows:

sudo aptitude install postfix

sudo dpkg --purge exim4

Step 8.2: Setup the mail server config files

Next we edit the Postfix main.cf file as follows:

sudo nano /etc/postfix/main.cf

Tip: It is always a good idea to maximise the open nano window so that the copy and paste of long lines does not wrap around.

See below for an example of the config file:

# See /usr/share/postfix/main.cf.dist for a commented, more complete version


# Debian specific:  Specifying a file name will cause the first
# line of that file to be used as the name.  The Debian default
# is /etc/mailname.
#myorigin = /etc/mailname

smtpd_banner = $myhostname ESMTP $mail_name (Ubuntu)
biff = no

# appending .domain is the MUA's job.
append_dot_mydomain = no

# Uncomment the next line to generate "delayed mail" warnings
#delay_warning_time = 4h

readme_directory = no

# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/%hostname%.pem
smtpd_tls_key_file=/etc/ssl/certs/%hostname%.key
smtpd_use_tls=yes
smtpd_tls_session_cache_database = btree:${data_directory}/smtpd_scache
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache

# See /usr/share/doc/postfix/TLS_README.gz in the postfix-doc package for
# information on enabling SSL in the smtp client.

myhostname = %hostname%
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
myorigin = /etc/mailname
mydestination = %hostname% localhost
relayhost = %relay-hostname%
mynetworks = %my-subnet% 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128
mailbox_size_limit = 0
recipient_delimiter = +
inet_interfaces = all

1. Change the %hostname% to the hostname of your server.
2. Change the %relay-hostname% to the hostname of your campus email server which sends and delivers email.
3. Add the subnet of your campus TCP/IP network %my-subnet% to the mynetworks parameter.
4. Ensure mydestination = %hostname% localhost to prevent your mail server becoming a spam email relay.

Talk to the campus system administrator about these settings.

Also see: http://www.postfix.org/SMTPD_ACCESS_README.html and http://en.wikipedia.org/wiki/Subnet_Mask.

Step 8.3: Setup default mailname

Now we edit the servers mailname as follows:

sudo nano /etc/mailname

Add one line only which should be the hostname of your server.

Now we restart Postfix:

sudo /etc/init.d/postfix restart

Step 8.4: Setup "root" email alias

The "root" email address is setup as follows:

sudo nano /etc/aliases

See below for an example:

# Added by installer for initial user
root:   me@myedu.ac.za

Change the me@myedu.ac.za to your email address. Then save and exit "nano".

To activate the new aliases type the following:

sudo newaliases

Step 8.5: Send a test email to root

Install the command line mailer program as follows:

sudo aptitude install mailx

Now we can send a test email to the root user by typing as follows:

mail -s "Test Email from root" root

Press the "Enter" key and type some message content. Press CTL+D and then Enter to send the mail.

Check the following log for any delivery errors as follows:

sudo tail -n 40 /var/log/mail.info

If there are no delivery errors your mail server is setup. Well done.

Step 9. Setup the environment variables

Step 9.1 Java settings for Tomcat6

To setup the environment variables for Tomcat java web applications, type the following:

nano /etc/default/tomcat6

Check the following for comparison:

# Run Tomcat as this user ID. Not setting this or leaving it blank will use the
# default of tomcat6.
#TOMCAT6_USER=tomcat6

# Run Tomcat as this group ID. Not setting this or leaving it blank will use
# the default of tomcat6.
#TOMCAT6_GROUP=tomcat6

# The home directory of the Java development kit (JDK). You need at least
# JDK version 1.5. If JAVA_HOME is not set, some common directories for 
# OpenJDK, the Sun JDK, and various J2SE 1.5 versions are tried.
#JAVA_HOME=/usr/lib/jvm/openjdk-6-jdk

# Directory where the Tomcat 6 binary distribution resides.  This a read-only
# directory that can be shared by all Tomcat instances running on the machine.
# Default: /usr/share/tomcat6
#CATALINA_HOME=/usr/share/$NAME

# Directory for per-instance configuration files and webapps. It contains the
# directories conf, logs, webapps, work and temp. See RUNNING.txt for details.
# Default: /var/lib/tomcat6
#CATALINA_BASE=/var/lib/$NAME

# You may pass JVM startup parameters to Java here. If unset, the default
# options (-Djava.awt.headless=true -Xmx128m) will be used.
#JAVA_OPTS="-Djava.awt.headless=true -Xmx128m"

JAVA_OPTS="-Djava.awt.headless=true -Xms1024m -Xmx2048m -XX:MaxPermSize=512m"

# Use a CMS garbage collector for improved response time
JAVA_OPTS="${JAVA_OPTS} -XX:+UseConcMarkSweepGC"

# When using the CMS garbage collector, you should enable the following option
# if you run Tomcat on a machine with exactly one CPU chip that contains one
# or two cores.
#JAVA_OPTS="${JAVA_OPTS} -XX:+CMSIncrementalMode"

# To enable remote debugging uncomment the following line.
# You will then be able to use a java debugger on port 8000.
#JAVA_OPTS="${JAVA_OPTS} -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n"

# Java compiler to use for translating JavaServer Pages (JSPs). You can use all
# compilers that are accepted by Ant's build.compiler property.
#JSP_COMPILER=javac

# Use the Java security manager? (yes/no, default: no)
#TOMCAT6_SECURITY=no

# Number of days to keep logfiles in /var/log/tomcat6. Default is 14 days.
#LOGFILE_DAYS=14

# Location of the JVM temporary directory
# WARNING: This directory will be destroyed and recreated at every startup !
#JVM_TMP=/tmp/tomcat6-temp

# If you run Tomcat on port numbers that are all higher than 1023, then you
# do not need authbind.  It is used for binding Tomcat to lower port numbers.
# NOTE: authbind works only with IPv4.  Do not enable it when using IPv6.
# (yes/no, default: no)
#AUTHBIND=no

Step 9.2 Java settings for applications such as the Handle server

To setup the environment variables for Tomcat java web applications, type the following:

nano /etc/default/environment

Check the following for comparison:

PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games"
JAVA_HOME="/usr/lib/jvm/java-6-openjdk"
JAVA_OPTS="-Djava.awt.headless=true -Xmx512m"

Step 10. Check the installation

Type the following to reboot the server:

sudo reboot

When the server has started up again, start a web browser session on another machine and type the following in the address bar:

http://%hostname%/manager/html

Replace %hostname% with your sites Dspace server address. Use the credentials you specified with the Tomcat installation step above. You should now be connected to the admin interface for Tomcat.

Next Procedure

Well done with the setup of the server for the Dspace installation later !!

If everything is OK, then proceed to the installation of Dspace itself.