Page History
...
DSpace
...
System
...
Documentation:
...
Installation
...
Table of Contents |
---|
...
|
For the Impatient
Since some users might want to get their test version up and running as fast as possible, offered below is an unsupported outline of getting DSpace to run quickly.
Only experienced unix admins should even attempt the following without going to Section 3.3
Warning | |||
---|---|---|---|
=true}
h2. For the Impatient
Since some users might want to get their test version up and running as fast as possible, offered below is an _unsupported_ outline of getting DSpace to run quickly.
Only experienced unix admins should even attempt the following without going to Section 3.3
{warning}
{code}
|
Prerequisite Software
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.
...
UNIX-like
...
OS
...
or
...
Microsoft
...
Windows
...
- UNIX-like
...
- OS
...
- (Linux,
...
- HP/UX
...
- etc)
...
- :
...
- Many
...
- distributions
...
- of
...
- Linux/Unix
...
- come
...
- with
...
- some
...
- of
...
- the
...
- dependencies
...
- below
...
- pre
...
- installed
...
- or
...
- easily
...
- installed
...
- via
...
- updates,
...
- you
...
- should
...
- consult
...
- your
...
- particular
...
- distributions
...
- documentation
...
- to
...
- determine
...
- what
...
- is
...
- already
...
- available. 
...
- Microsoft
...
- Windows:
...
- (see
...
- full
...
- Windows
...
- Instructions
...
- for
...
- full
...
- set
...
- of
...
- prerequisites)
...
Oracle
...
Java
...
JDK
...
6
...
or
...
later
...
(standard
...
SDK
...
is
...
fine,
...
you
...
don't
...
need
...
J2EE)
...
DSpace
...
now
...
requires
...
Oracle
...
Java
...
6
...
or
...
greater
...
because
...
of
...
usage
...
of
...
new
...
language
...
capabilities
...
introduced
...
in
...
5
...
and
...
6
...
that
...
make
...
coding
...
easier
...
and
...
cleaner.
...
Java
...
can
...
be
...
downloaded
...
from
...
the
...
following
...
location:
...
http://java.sun.com/javase/downloads/index.jsp
...
Only Oracle's
...
Java
...
has
...
been
...
tested
...
with
...
each
...
release
...
and
...
is
...
known
...
to
...
work
...
correctly.
...
Other
...
flavors
...
of
...
Java
...
may
...
pose
...
problems.
...
Apache Maven 2.0.8
...
or
...
later
...
(Java
...
build
...
tool)
...
Wiki Markup |
---|
Maven is necessary in the first stage of the build process to assemble the installation package for your DSpace instance. It gives you the flexibility to customize DSpace using the exisitng Maven projects found in the _\[dspace-source\]/dspace/modules_ directory or by adding in your own Maven project to build the installation package for DSpace, and apply any custom interface "overlay" changes. |
...
Maven
...
can
...
be
...
downloaded
...
from
...
the
...
following
...
location:
...
http://maven.apache.org/download.html
...
Configuring a Proxy
You can configure a proxy to use for some or all of your HTTP requests in Maven 2.0. The username and password are only required if your proxy requires basic authentication (note that later releases may support storing your passwords in a secured keystore—in the mean time, please ensure your settings.xml file (usually ${user.home}/.m2/settings.xml
...
)
...
is
...
secured
...
with
...
permissions
...
appropriate
...
for
...
your
...
operating
...
system).
...
Example:
Code Block |
---|
}<settings> . . <proxies> <proxy> <active>true</active> <protocol>http</protocol> <host>proxy.somewhere.com</host> <port>8080</port> <username>proxyuser</username> <password>somepassword</password> <nonProxyHosts>www.google.com|*.somewhere.com</nonProxyHosts> </proxy> </proxies> . . </settings> {code} h3. Apache Ant |
Apache Ant 1.7
...
or
...
later
...
(Java
...
build
...
tool)
...
Wiki Markup |
---|
Apache Ant is still required for the second stage of the build process. It is used once the installation package has been constructed in _\[dspace-source\]/dspace/target/dspace-<version>-build.dir_ and still uses some of the familiar ant build targets found in the 1.4.x build process. |
...
Ant
...
can
...
be
...
downloaded
...
from
...
the
...
following
...
location:
...
...
Relational Database: (PostgreSQL or Oracle).
- PostgreSQL 8.1 to 8.4 PostgreSQL can be downloaded from the following location: http://www.postgresql.org/
...
- . It is highly recommended that you try to work with Postgres 8.4 or greater, however, 8.1 or greater should still work. Unicode (specifically UTF-8) support must be enabled. This is enabled by default in 8.0+.
...
- Once
...
- installed,
...
- you
...
- need
...
- to
...
- enable
...
- TCP/IP
...
- connections
...
- (DSpace
...
- uses
...
- JDBC).
...
- In
...
- postgresql.conf
...
- :
...
- uncomment
...
- the
...
- line
...
- starting:
...
- listen_addresses
...
- =
...
- 'localhost'
...
- .
...
- Then
...
- tighten
...
- up
...
- security
...
- a
...
- bit
...
- by
...
- editing
...
- pg_hba.conf
...
- and
...
- adding
...
- this
...
- line:
...
- host
...
- dspace
...
- dspace
...
- 127.0.0.1
...
- 255.255.255.255
...
- md5
...
- .
...
- Then
...
- restart
...
- PostgreSQL.
...
- Oracle
...
- 10g
...
- or
...
- greater
...
- Details
...
- on
...
- acquiring
...
- Oracle
...
- can
...
- be
...
- downloaded
...
- from
...
- the
...
- following
...
- location:
...
...
- .
...
- You
...
- will
...
- need
...
- to
...
- 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.
...
- You
...
- will
...
- also
...
- need
...
- to
...
- create
...
- a
...
- user
...
- account
...
- for
...
- DSpace
...
- (e.g.
...
- dspace
...
- )
...
- and
...
- ensure
...
- that
...
- it
...
- has
...
- permissions
...
- to
...
- add
...
- and
...
- remove
...
- tables
...
- in
...
- the
...
- database.
...
- Refer
...
- to
...
- the
...
- Quick
...
- Installation
...
- for
...
- more
...
- details.
...
- NOTE:
...
- DSpace
...
- uses
...
- sequences
...
- to
...
- generate
...
- unique
...
- object
...
- IDs
...
- — beware
...
- Oracle
...
- sequences,
...
- which
...
- are
...
- said
...
- to
...
- lose
...
- their
...
- values
...
- when
...
- doing
...
- a
...
- database
...
- export/import,
...
- say
...
- restoring
...
- from
...
- a
...
- backup.
...
- Be
...
- sure
...
- to
...
- run
...
- the
...
- script
...
- etc/update-sequences.sql
...
- .
...
- For
...
- people
...
- interested
...
- in
...
- switching
...
- from
...
- Postgres
...
- to
...
- Oracle,
...
- I
...
- know
...
- of
...
- no
...
- tools
...
- that
...
- would
...
- do
...
- this
...
- automatically.
...
- You
...
- will
...
- need
...
- to
...
- recreate
...
- the
...
- community,
...
- collection,
...
- and
...
- eperson
...
- structure
...
- in
...
- the
...
- Oracle
...
- system,
...
- and
...
- then
...
- use
...
- the
...
- item
...
- export
...
- and
...
- import
...
- tools
...
- to
...
- move
...
- your
...
- content
...
- over.
...
Servlet
...
Engine:
...
(Apache
...
Tomcat
...
5.5
...
or
...
6,
...
Jetty,
...
Caucho
...
Resin
...
or
...
equivalent).
...
- Apache
...
- Tomcat
...
- 5.5
...
- or
...
- later.
...
- Tomcat
...
- can
...
- be
...
- downloaded
...
- from
...
- the
...
- following
...
- location:
...
...
- .
- 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'. Set the environment variable TOMCAT_USER appropriately.
- You need to ensure that Tomcat has a) enough memory to run DSpace and b) uses UTF-8 as its default file encoding for international character support. So ensure in your startup scripts (etc) that the following environment variable is set: JAVA_OPTS="-Xmx512M
...
- -Xms64M
...
- -Dfile.encoding=UTF-8"
...
Wiki Markup *Modifications in* *_\[tomcat\]/conf/server.xml{_}*: You also need to alter Tomcat's default configuration to support searching and browsing of multi-byte UTF-8 correctly. You need to add a configuration option to the _<Connector>_ element in _\[tomcat\]/config/server.xml_: _URIEncoding="UTF-8"_ e.g. if you're using the default Tomcat config, it should read:
...
Code Block
...
<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 --> <Connector port="8080" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" redirectPort="8443" acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true" URIEncoding="UTF-8"/>
...
You
...
- may
...
- change
...
- the
...
- port
...
- from
...
- 8080
...
- by
...
- editing
...
- it
...
- in
...
- the
...
- file
...
- above,
...
- and
...
- by
...
- setting
...
- the
...
- variable
...
- CONNECTOR_PORT
...
- in
...
- server.xml
...
- .
...
- Jetty
...
- or
...
- Caucho
...
- Resin
...
- DSpace
...
- will
...
- also
...
- run
...
- on
...
- an
...
- equivalent
...
- servlet
...
- Engine,
...
- such
...
- as
...
- Jetty
...
- (
...
...
- )
...
- or
...
- Caucho
...
- Resin
...
- (
...
...
- .
...
- Jetty
...
- and
...
- Resin
...
- are
...
- configured
...
- for
...
- correct
...
- handling
...
- of
...
- UTF-8
...
- by
...
- default.
...
Wiki Markup |
---|
Perl (required for \[dspace\]/bin/dspace-info.pl) |
...
Installation Options
Overview of Install Options
With the advent of a new Apache Maven 2 based build architecture in DSpace 1.5.x,
...
you
...
now
...
have
...
two
...
options
...
in
...
how
...
you
...
may
...
wish
...
to
...
install
...
and
...
manage
...
your
...
local
...
installation
...
of
...
DSpace.
...
If
...
you've
...
used
...
DSpace
...
1.4.x,
...
please
...
recognize
...
that
...
the
...
initial
...
build
...
procedure
...
has
...
changed
...
to
...
allow
...
for
...
more
...
customization.
...
You
...
will
...
find
...
the
...
later
...
'Ant
...
based'
...
stages
...
of
...
the
...
installation
...
procedure
...
familiar.
...
Maven
...
is
...
used
...
to
...
resolve
...
the
...
dependencies
...
of
...
DSpace
...
online
...
from
...
the
...
'Maven
...
Central
...
Repository'
...
server.
...
It
...
is
...
important
...
to
...
note
...
that
...
the
...
strategies
...
are
...
identical
...
in
...
terms
...
of
...
the
...
list
...
of
...
procedures
...
required
...
to
...
complete
...
the
...
build
...
process,
...
the
...
only
...
difference
...
being
...
that
...
the
...
Source
...
Release
...
includes
...
"more
...
modules"
...
that
...
will
...
be
...
built
...
given
...
their
...
presence
...
in
...
the
...
distribution
...
package.
...
- Default
...
- Release
...
- (dspace-<version>-release.zip)
...
- This
...
- distribution
...
- will
...
- be
...
- adequate
...
- for
...
- most
...
- cases
...
- of
...
- running
...
- a
...
- DSpace
...
- instance.
...
- It
...
- is
...
- intended
...
- to
...
- be
...
- the
...
- quickest
...
- way
...
- to
...
- get
...
- DSpace
...
- installed
...
- and
...
- running
...
- while
...
- still
...
- allowing
...
- for
...
- customization
...
- of
...
- the
...
- themes
...
- and
...
- branding
...
- of
...
- your
...
- DSpace
...
- instance.
...
-  
...
- This
...
- method
...
- allows
...
- you
...
- to
...
- customize
...
- DSpace
...
- configurations
...
- (in
...
- dspace.cfg)
...
- or
...
- user
...
- interfaces,
...
- using
...
- basic
...
- pre-built
...
- interface
...
- "overlays". 
...
- It
...
- downloads
...
- "precompiled"
...
- libraries
...
- for
...
- the
...
- core
...
- dspace-api,
...
- supporting
...
- servlets,
...
- taglibraries,
...
- aspects
...
- and
...
- themes
...
- for
...
- the
...
- dspace-xmlui,
...
- dspace-xmlui
...
- and
...
- other
...
- webservice/applications. 
...
- This
...
- approach
...
- exposes
...
- the
...
- parts
...
- of
...
- the
...
- application
...
- that
...
- the
...
- DSpace
...
- committers
...
- would
...
- prefer
...
- to
...
- see
...
- customized.
...
- All
...
- other
...
- modules
...
- are
...
- downloaded
...
- from
...
- the
...
- 'Maven
...
- Central
...
- Repository' The
...
- directory
...
- structure
...
- for
...
- this
...
- release
...
- is
...
- the
...
- following:
...
Wiki Markup _\[dspace-source\]_
...
- dspace/
...
- -
...
- DSpace
...
- 'build'
...
- and
...
- configuration
...
- module
- pom.xml
...
- -
...
- DSpace
...
- Parent
...
- Project
...
- definition
...
- Source
...
- Release
...
- (dspace-<version>-src-release.zip)
...
- This
...
- method
...
- is
...
- recommended
...
- for
...
- those
...
- who
...
- wish
...
- to
...
- develop
...
- DSpace
...
- further
...
- or
...
- alter
...
- its
...
- underlying
...
- capabilities
...
- to
...
- a
...
- greater
...
- degree. 
...
- It
...
- contains
...
- all
...
- dspace
...
- code
...
- for
...
- the
...
- core
...
- dspace-api,
...
- supporting
...
- servlets,
...
- taglibraries,
...
- aspects
...
- and
...
- themes
...
- for
...
- Manakin
...
- (dspace-xmlui),
...
- and
...
- other
...
- webservice/applications.
...
- Provides
...
- all
...
- the
...
- same
...
- capabilities
...
- as
...
- the
...
- normal
...
- release. The
...
- directory
...
- structure
...
- for
...
- this
...
- release
...
- is
...
- more
...
- detailed:
...
Wiki Markup _\[dspace-source\]_
...
- dspace/
...
- -
...
- DSpace
...
- 'build'
...
- and
...
- configuration
...
- module
- dspace-api/
...
- -
...
- Java
...
- API
...
- source
...
- module
- dspace-jspui/
...
- -
...
- JSP-UI
...
- source
...
- module
- dspace-oai
...
- -
...
- OAI-PMH
...
- source
...
- module
- dspace-xmlui
...
- -
...
- XML-UI
...
- (Manakin)
...
- source
...
- module
- dspace-lni - Lightweight Network Interface source module
- dspace-sword – SWORD (Simple Web-serve Offering Repository Deposit) deposit service source module
- dspace-test – DSpace Tests (Unit and Integration Tests)
- pom.xml - DSpace Parent Project definition
Overview of DSpace Directories
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:
Wiki Markup *The installation directory*, referred to as __\[dspace\]__ . This is the location where DSpace is installed and running off of it is the location that gets defined in the dspace.cfg as "dspace.dir". It is where all the DSpace configuration files, command line scripts, documentation and webapps will be installed to.
...
Wiki Markup *The source directory*, referred to as __\[dspace-source\]__ . This is the location where the DSpace release distribution has been unzipped into. It usually has the name of the archive that you expanded such as _dspace-<version>_{_}{-}release{-}_ or _dspace<version>-src-release_. It is the directory where all of your "build" commands will be run.
...
Wiki Markup *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_). For details on the contents of these separate directory trees, refer to directories.html. _Note that the \_\[dspace-source\]_ and _\[dspace\]_ directories are always separate\!\_
...
Installation
This method gets you up and running with DSpace quickly and easily. It is identical in both the Default Release and Source Release distributions.
- Create the DSpace user. This needs to be the same user that Tomcat (or Jetty etc.) will run as. e.g. as root run:
Code Block useradd -m dspace
...
- Download the latest DSpace release There are two version available with each release of DSpace: (dspace-1.x-release.
...
- and
...
- dspace-1.x-src-release.xxx
...
- );
...
- you
...
- only
...
- need
...
- to
...
- choose
...
- one.
...
- If
...
- you
...
- want
...
- a
...
- copy
...
- of
...
- all
...
- underlying
...
- Java
...
- source
...
- code,
...
- you
...
- should
...
- download
...
- the
...
- dspace-1.x-src-release.xxx
...
- Within
...
- each
...
- version,
...
- you
...
- have
...
- a
...
- choice
...
- of
...
- compressed
...
- file
...
- format.
...
- Choose
...
- the
...
- one
...
- that
...
- best
...
- fits
...
- your
...
- environment.
...
- Unpack
...
- the
...
- DSpace
...
- software
...
- .
...
- After
...
- downloading
...
- the
...
- software,
...
- based
...
- on
...
- the
...
- compression
...
- file
...
- format,
...
- choose
...
- one
...
- of
...
- the
...
- following
...
- methods
...
- to
...
- unpack
...
- your
...
- software:
...
- Zip
...
- file
...
- .
...
- If
...
- you
...
- downloaded
...
- dspace-1.6-release.zip
...
- do
...
- the
...
- following:
...
Code Block
...
unzip dspace-1.7-release.zip
...
- .gz
...
- file
...
- .
...
- If
...
- you
...
- downloaded
...
- dspace-1.6-release.tar.gz
...
- do
...
- the
...
- following:
...
Code Block
...
gunzip -c dspace-1.7-release.tar.gz | tar -xf -
...
- .bz2
...
- file
...
- .
...
- If
...
- you
...
- downloaded
...
- _dspace-1.6-release.tar.bz2_do
...
- the
...
- following:
...
Code Block
...
bunzip2 dspace-1.7-release.tar.bz | tar -xf
...
-
Wiki Markup For ease of reference, we will refer to the location of this unzipped version of the DSpace release as _\[dspace-source\]_ in the remainder of these instructions.After unpacking the file, the user may which to change the ownership of the _dspace-1.6-release_ to the 'dspace' user. (And you may need to change the group).
...
- Database
...
- Setup
PostgreSQL:
...
- A
...
- PostgreSQL
...
- 8.1-404
...
- jdbc3
...
- driver
...
- is
...
- configured
...
- as
...
- part
...
- of
...
- the
...
- default
...
- DSpace
...
- build.
...
- You
...
- no
...
- longer
...
- need
...
- to
...
- copy
...
- any
...
- PostgreSQL
...
- jars
...
- to
...
- get
...
- PostgreSQL
...
- installed.
...
- Create
...
- a
...
- dspace
...
- database,
...
- owned
...
- by
...
- the
...
- dspace
...
- PostgreSQL
...
- user
...
- (you
...
- are
...
- still
...
- logged
...
- in
...
- at
...
- 'root')
...
- :
...
Code Block
...
createuser -U postgres -d -A -P dspace ; createdb -U dspace -E UNICODE dspace
...
You
...
- will
...
- be
...
- prompted
...
- for
...
- a
...
- password
...
- for
...
- the
...
- DSpace
...
- database.
...
- (This
...
- isn't
...
- the
...
- same
...
- as
...
- the
...
- dspace
...
- user's
...
- UNIX
...
- password.)
...
Oracle:- Setting up oracle is a bit different now. You will need still need to get a Copy of the oracle JDBC driver, but instead of copying it into a lib directory you will need to install it into your local Maven repository. You'll need to download it first from this location: http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/htdocs/jdbc_10201.html
...
- $
...
- mvn
...
- install:install-file
...
- -Dfile=ojdbc14.jar
...
- -DgroupId=com.oracle
...
- \
...
- -DartifactId=ojdbc14
...
- -Dversion=10.2.0.2.0
...
- -Dpackaging=jar
...
- -DgeneratePom=true
...
- 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.
...
Wiki Markup Edit the _\[dspace-source\]/dspace/config/dspace.cfg_ database settings:
...
Code Block
...
db.name = oracle db.url = jdbc:oracle:thin:@//host:port/dspace db.driver = oracle.jdbc.OracleDriver
...
Wiki Markup *Initial Configuration*Edit_\[dspace-source\]/dspace/config/dspace.cfg_, in particular you'll need to set these properties:*{*}{_}dspace.dir{_}* *\-\- must be set to the* *_\[dspace\]_* *(installation) directory.*{*}{_}dspace.url{_}* *\-\- complete URL of this server's DSpace home page.*{*}{_}dspace.hostname{_}* *\-\- fully-qualified domain name of web server.*{*}{_}dspace.name{_}* *\-\- "Proper" name of your server, e.g. "My Digital Library".*{*}{_}db.password{_}* *\-\- the database password you entered in the previous step.*{*}{_}mail.server{_}* *\-\- fully-qualified domain name of your outgoing mail server.*{*}{_}mail.from.address{_}* *\-\- the "From:" address to put on email sent by DSpace.*{*}{_}feedback.recipient{_}* *\-\- mailbox for feedback mail.*{*}{_}mail.admin{_}* *\-\- mailbox for DSpace site administrator.*{*}{_}alert.recipient{_}* *\-\- mailbox for server errors/alerts (not essential but very useful\!)*{*}{_}registration.notify{_}* *\-\- mailbox for emails when new users register (optional) \*NOTE:* You can interpolate the value of one configuration variable in the value of another one. For example, to set _feedback.recipient_ to the same value as _mail.admin_, the line would look like:
...
Code Block
...
feedback.recipient = ${mail.admin}
...
Refer
...
- to
...
- 5.2.
...
- General
...
- Configuration
...
- for
...
- details
...
- and
...
- examples
...
- of
...
- the
...
- above.
...
Wiki Markup \*DSpace Directory*Create the directory for the DSpace installation (i.e. _\[dspace\]_). As _root_ (or a user with appropriate permissions), run:
...
Code Block
...
mkdir [dspace] chown dspace [dspace]
...
(Assuming
...
- the
...
- dspace
...
- UNIX
...
- username.)
...
Wiki Markup \*Installation Package*As the _dspace_ UNIX user, generate the DSpace installation package in the _\[dspace-source\]/dspace_ directory:
...
Code Block
...
cd [dspace-source]/dspace/ mvn package
...
Note:
...
- without
...
- any
...
- extra
...
- arguments,
...
- the
...
- DSpace
...
- installation
...
- package
...
- is
...
- initialized
...
- for
...
- PostgreSQL. 
...
- If
...
- you
...
- want
...
- to
...
- use
...
- Oracle
...
- instead,
...
- you
...
- should
...
- build
...
- the
...
- DSpace
...
- installation
...
- package
...
- as
...
- follows:
...
Code Block
...
mvn -Ddb.name=oracle package
...
Wiki Markup \*Build DSpace and Initialize Database*As the _dspace_ UNIX user, initialize the DSpace database and install DSpace to _\[dspace\]_:
...
Code Block
...
cd [dspace-source]/dspace/target/dspace-[version]-build.dir ant fresh_install
...
To
...
- see
...
- a
...
- complete
...
- list
...
- of
...
- build
...
- targets,
...
- run:
...
- ant
...
- help
...
- The
...
- most
...
- likely
...
- thing
...
- to
...
- go
...
- wrong
...
- here
...
- is
...
- the
...
- database
...
- connection.
...
- See
...
- the
...
- _3.7
...
- Common
...
- Problems
...
- Section
...
- .
...
- Deploy
...
- Web
...
- Applications.
...
You
...
- have
...
- two
...
- choices
...
- or
...
- techniques
...
- for
...
- having
...
- Tomcat/Jetty/Resin
...
- serve
...
- up
...
- your
...
- web
...
- applications.
...
Wiki Markup |
---|
*Technique A.* Simple and complete. You copy only (or all) of the DSpace Web application(s) you wish to use from the {{*\[dspace\]/webapps{*}}} directory to the appropriate directory in your Tomcat/Jetty/Resin installation. For example: |
...
Wiki Markup {{{*}cp \-R \[dspace\]/webapps/\* \[tomcat\]/webapps{*}}} (This will copy all the web applications to Tomcat).
...
Wiki Markup {{{*}cp \-R \[dspace\]/webapps/jspui \[tomcat\]/webapps{*}}} (This will copy only the jspui web application to Tomcat.)
...
Wiki Markup |
---|
*Technique B.* 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: |
Code Block |
---|
}<!-- Define the default virtual host Note: XML Schema validation will not work with Xerces 2.2. --> <Host name="localhost" appBase="[dspace]/webapps" ....{code} # \*Administrator Account *Create an initial administrator account:{code} |
- *Administrator Account *Create an initial administrator account:
Code Block [dspace]/bin/dspace create-administrator
...
- Initial Startup! 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.)
...
...
- XML User Interface (aka.
...
- Manakin)
...
- -
...
- (e.g.)
...
...
- OAI-PMH
...
- Interface
...
- -
...
- (e.g.)
...
...
- (Should
...
- return
...
- an
...
- XML-based
...
- response)
...
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.
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.
'cron' Jobs
A couple of DSpace features require that a script is run regularly – the e-mail subscription feature that alerts users of new items being deposited, and the new 'media filter' tool, that generates thumbnails of images and extracts the full-text of documents for indexing.
To set these up, you just need to run the following command as the dspace UNIX user:
Code Block |
---|
crontab -e |
Then add the following lines:
Code Block |
---|
h2. 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. h3. 'cron' Jobs A couple of DSpace features require that a script is run regularly -- the e-mail subscription feature that alerts users of new items being deposited, and the new 'media filter' tool, that generates thumbnails of images and extracts the full-text of documents for indexing. To set these up, you just need to run the following command as the _dspace_ UNIX user: {code}crontab -e{code} Then add the following lines: {code}# Send out subscription e-mails at 01:00 every day 0 1 * * * [dspace]/bin/dspace sub-daily # Run the media filter at 02:00 every day 0 2 * * * [dspace]/bin/dspace filter-media # Run the checksum checker at 03:00 0 3 * * * [dspace]/bin/dspace checker -lp # Mail the results to the sysadmin at 04:00 0 4 * * * [dspace]/bin/dspace checker-emailer -c {code} |
Naturally
...
you
...
should
...
change
...
the
...
frequencies
...
to
...
suit
...
your
...
environment.
...
PostgreSQL
...
also
...
benefits
...
from
...
regular
...
'vacuuming',
...
which
...
optimizes
...
the
...
indexes
...
and
...
clears
...
out
...
any
...
deleted
...
data.
...
Become
...
the
...
postgres
...
UNIX
...
user,
...
run
...
crontab
...
-e
...
and
...
add
...
(for
...
example):
Code Block |
---|
}# Clean up the database nightly at 4.20am 20 4 * * * vacuumdb --analyze dspace > /dev/null 2>&1{code} |
In
...
order
...
that
...
statistical
...
reports
...
are
...
generated
...
regularly
...
and
...
thus
...
kept
...
up
...
to
...
date
...
you
...
should
...
set
...
up
...
the
...
following
...
cron
...
jobs:
Code Block |
---|
}# Run stat analysis 0 1 * * * [dspace]/bin/dspace stat-general 0 1 * * * [dspace]/bin/dspace stat-monthly 0 2 * * * [dspace]/bin/dspace stat-report-general 0 2 * * * [dspace]/bin/dspace stat-report-monthly{code} |
Obviously,
...
you
...
should
...
choose
...
execution
...
times
...
which
...
are
...
most
...
useful
...
to
...
you,
...
and
...
you
...
should
...
ensure
...
that
...
the
...
report
...
scripts
...
run
...
a
...
short
...
while
...
after
...
the
...
analysis
...
scripts
...
to
...
give
...
them
...
time
...
to
...
complete
...
(a
...
run
...
of
...
around
...
8
...
months
...
worth
...
of
...
logs
...
can
...
take
...
around
...
25
...
seconds
...
to
...
complete);
...
the
...
resulting
...
reports
...
will
...
let
...
you
...
know
...
how
...
long
...
analysis
...
took
...
and
...
you
...
can
...
adjust
...
your
...
cron
...
times
...
accordingly.
...
Multilingual Installation
Wiki Markup |
---|
In order to deploy a multilingual version of DSpace you have to configure two parameters in _\[dspace-source\]/config/dspace.cfg:_ |
...
default.locale
...
,
...
e.
...
g.
...
default.locale
...
=
...
en
webui.supported
...
locales
...
,
...
e.
...
g.
...
webui.supported.locales
...
=
...
en,
...
de
...
The
...
Locales
...
might
...
have
...
the
...
form
...
country,
...
country_language,
...
country_language_variant.
...
According
...
to
...
the
...
languages
...
you
...
wish
...
to
...
support,
...
you
...
have
...
to
...
make
...
sure,
...
that
...
all
...
the
...
i18n
...
related
...
files
...
are
...
available
...
see
...
the
...
Multilingual
...
User
...
Interface
...
Configuring
...
MultiLingual
...
Support
...
section
...
for
...
the
...
JSPUI
...
or
...
the
...
Multilingual
...
Support
...
for
...
XMLUI
...
in
...
the
...
configuration
...
documentation.
...
DSpace over HTTPS
If your DSpace is configured to have users login with a username and password (as opposed to, say, client Web certificates), then you should consider using HTTPS. Whenever a user logs in with the Web form (e.g.
...
dspace.myuni.edu/dspace/password-login
...
)
...
their
...
DSpace
...
password
...
is
...
exposed
...
in
...
plain
...
text
...
on
...
the
...
network.
...
This
...
is
...
a
...
very
...
serious
...
security
...
risk
...
since
...
network
...
traffic
...
monitoring
...
is
...
very
...
common,
...
especially
...
at
...
universities.
...
If
...
the
...
risk
...
seems
...
minor,
...
then
...
consider
...
that
...
your
...
DSpace
...
administrators
...
also
...
login
...
this
...
way
...
and
...
they
...
have
...
ultimate
...
control
...
over
...
the
...
archive.
...
The
...
solution
...
is
...
to
...
use
...
HTTPS
...
(HTTP
...
over
...
SSL,
...
i.e.
...
Secure
...
Socket
...
Layer,
...
an
...
encrypted
...
transport),
...
which
...
protects
...
your
...
passwords
...
against
...
being
...
captured.
...
You
...
can
...
configure
...
DSpace
...
to
...
require
...
SSL
...
on
...
all
...
"authenticated"
...
transactions
...
so
...
it
...
only
...
accepts
...
passwords
...
on
...
SSL
...
connections.
...
The
...
following
...
sections
...
show
...
how
...
to
...
set
...
up
...
the
...
most
...
commonly-used
...
Java
...
Servlet
...
containers
...
to
...
support
...
HTTP
...
over
...
SSL.
...
To
...
enable
...
the
...
HTTPS
...
support
...
in
...
Tomcat
...
5.0:
...
- For
...
- Production
...
- use:
...
- Follow
...
- this
...
- procedure
...
- to
...
- set
...
- up
...
- SSL
...
- on
...
- your
...
- server.
...
- Using
...
- a
...
- "real"
...
- server
...
- certificate
...
- ensures
...
- your
...
- users'
...
- browsers
...
- will
...
- accept
...
- it
...
- without
...
- complaints.
...
- In
...
- the
...
- examples
...
- below,
...
- $CATALINA_BASE
...
- is
...
- the
...
- directory
...
- under
...
- which
...
- your
...
- Tomcat
...
- is
...
- installed.
...
- Create
...
- a
...
- Java
...
- keystore
...
- for
...
- your
...
- server
...
- with
...
- the
...
- password
...
- changeit
...
- ,
...
- and
...
- install
...
- your
...
- server
...
- certificate
...
- under
...
- the
...
- alias
...
- "tomcat"
...
- .
...
- This
...
- assumes
...
- the
...
- certificate
...
- was
...
- put
...
- in
...
- the
...
- file
...
- server.pem
...
- :
...
Code Block
...
$JAVA_HOME/bin/keytool -import -noprompt -v -storepass changeit -keystore $CATALINA_BASE/conf/keystore -alias tomcat -file myserver.pem
...
- Install the CA (Certifying
...
- Authority)
...
- certificate
...
- for
...
- the
...
- CA
...
- that
...
- granted
...
- your
...
- server
...
- cert,
...
- if
...
- necessary.
...
- This
...
- assumes
...
- the
...
- server
...
- CA
...
- certificate
...
- is
...
- in
...
- ca.pem
...
- :
...
Code Block
...
$JAVA_HOME/bin/keytool -import -noprompt -storepass changeit -trustcacerts -keystore $CATALINA_BASE/conf/keystore -alias ServerCA -file ca.pem
...
- Optional – ONLY if you need to accept client certificates for the X.509 certificate stackable authentication module See the configuration section for instructions on enabling the X.509 authentication method. Load the keystore with the CA (certifying authority) certificates for the authorities of any clients whose certificates you wish to accept. For example, assuming the client CA certificate is in client1.pem:
Code Block $JAVA_HOME/bin/keytool -import -noprompt -storepass changeit -trustcacerts -keystore $CATALINA_BASE/conf/keystore -alias client1 -file client1.pem
...
- Now add another Connector tag to your server.xml
...
- Tomcat
...
- configuration
...
- file,
...
- like
...
- the
...
- example
...
- below.
...
- The
...
- parts
...
- affecting
...
- or
...
- specific
...
- to
...
- SSL
...
- are
...
- shown
...
- in
...
- bold.
...
- (You
...
- may
...
- wish
...
- to
...
- change
...
- some
...
- details
...
- such
...
- as
...
- the
...
- port,
...
- pathnames,
...
- and
...
- keystore
...
- password)
...
Code Block
...
<Connector port="8443" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" debug="0" scheme="https" secure="true" sslProtocol="TLS" keystoreFile="conf/keystore" keystorePass="changeit" clientAuth="true" - ONLY if using client X.509 certs for authentication! truststoreFile="conf/keystore" trustedstorePass="changeit" />
...
Also,
...
- check
...
- that
...
- the
...
- default
...
- Connector
...
- is
...
- set
...
- up
...
- to
...
- redirect
...
- "secure"
...
- requests
...
- to
...
- the
...
- same
...
- port
...
- as
...
- your
...
- SSL
...
- connector,
...
- e.g.:
...
-  
...
Code Block
...
<Connector port="8080" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" redirectPort="8443" acceptCount="100" debug="0" />
...
- Quick-and-dirty
...
- Procedure
...
- for
...
- Testing:
...
- If
...
- you
...
- are
...
- just
...
- setting
...
- up
...
- a
...
- DSpace
...
- server
...
- for
...
- testing,
...
- or
...
- to
...
- experiment
...
- with
...
- HTTPS,
...
- then
...
- you
...
- don't
...
- need
...
- to
...
- get
...
- a
...
- real
...
- server
...
- certificate.
...
- You
...
- can
...
- create
...
- a
...
- "self-signed"
...
- certificate
...
- for
...
- testing;
...
- web
...
- browsers
...
- will
...
- issue
...
- warnings
...
- before
...
- accepting
...
- it
...
- but
...
- they
...
- will
...
- function
...
- exactly
...
- the
...
- same
...
- after
...
- that
...
- as
...
- with
...
- a
...
- "real"
...
- certificate.
...
-  In
...
- the
...
- examples
...
- below,
...
- $CATALINA_BASE
...
- is
...
- the
...
- directory
...
- under
...
- which
...
- your
...
- Tomcat
...
- is
...
- installed.
...
- Optional – ONLY if you don't
...
- already
...
- have
...
- a
...
- server
...
- certificate.
...
- Follow
...
- this
...
- sub-procedure
...
- to
...
- request
...
- a
...
- new,
...
- signed
...
- server
...
- certificate
...
- from
...
- your
...
- Certifying
...
- Authority
...
- (CA): 
...
- Create a new key pair under the alias name "tomcat"
...
- .
...
- When
...
- generating
...
- your
...
- key,
...
- give
...
- the
...
- Distinguished
...
- Name
...
- fields
...
- the
...
- appropriate
...
- values
...
- for
...
- your
...
- server
...
- and
...
- institution.
...
- CN
...
- should
...
- be
...
- the
...
- fully-qualified
...
- domain
...
- name
...
- of
...
- your
...
- server
...
- host.
...
- Here
...
- is
...
- an
...
- example:
...
Code Block
...
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keysize 1024 \ -keystore $CATALINA_BASE/conf/keystore -storepass changeit -validity 365 \ -dname 'CN=dspace.myuni.edu, OU=MIT Libraries, O=Massachusetts Institute of Technology, L=Cambridge, S=MA, C=US'
...
- Then,
...
- create
...
- a
...
- CSR
...
- (Certificate
...
- Signing
...
- Request)
...
- and
...
- send
...
- it
...
- to
...
- your
...
- Certifying
...
- Authority.
...
- They
...
- will
...
- send
...
- you
...
- back
...
- a
...
- signed
...
- Server
...
- Certificate.
...
- This
...
- example
...
- command
...
- creates
...
- a
...
- CSR
...
- in
...
- the
...
- file
...
- tomcat.csr
...
Code Block $JAVA_HOME/bin/keytool -keystore $CATALINA_BASE/conf/keystore -storepass changeit \ -certreq -alias tomcat -v -file tomcat.csr
...
- Before importing the signed certificate, you must have the CA's
...
- certificate
...
- in
...
- your
...
- keystore
...
- as
...
- a
...
- trusted
...
- certificate
...
- .
...
- Get
...
- their
...
- certificate,
...
- and
...
- import
...
- it
...
- with
...
- a
...
- command
...
- like
...
- this
...
- (for
...
- the
...
- example
...
- mitCA.pem
...
- ):
...
Code Block
...
$JAVA_HOME/bin/keytool -keystore $CATALINA_BASE/conf/keystore -storepass changeit \ -import -alias mitCA -trustcacerts -file mitCA.pem
...
- Finally,
...
- when
...
- you
...
- get
...
- the
...
- signed
...
- certificate
...
- from
...
- your
...
- CA,
...
- import
...
- it
...
- into
...
- the
...
- keystore
...
- with
...
- a
...
- command
...
- like
...
- the
...
- following
...
- example:
...
- (cert
...
- is
...
- in
...
- the
...
- file
...
- signed-cert.pem
...
- )
...
Code Block
...
$JAVA_HOME/bin/keytool -keystore $CATALINA_BASE/conf/keystore -storepass changeit \ -import -alias tomcat -trustcacerts -file signed-cert.pem
...
Since
...
- you
...
- now
...
- have
...
- a
...
- signed
...
- server
...
- certificate
...
- in
...
- your
...
- keystore,
...
- you
...
- can,
...
- obviously,
...
- skip
...
- the
...
- next
...
- steps
...
- of
...
- installing
...
- a
...
- signed
...
- server
...
- certificate
...
- and
...
- the
...
- server
...
- CA's
...
- certificate. 
...
- Create
...
- a
...
- Java
...
- keystore
...
- for
...
- your
...
- server
...
- with
...
- the
...
- password
...
- changeit
...
- ,
...
- and
...
- install
...
- your
...
- server
...
- certificate
...
- under
...
- the
...
- alias
...
- "tomcat"
...
- .
...
- This
...
- assumes
...
- the
...
- certificate
...
- was
...
- put
...
- in
...
- the
...
- file
...
- server.pem
...
- :
...
Code Block
...
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore $CATALINA_BASE/conf/keystore -storepass changeit
...
When
...
- answering
...
- the
...
- questions
...
- to
...
- identify
...
- the
...
- certificate,
...
- be
...
- sure
...
- to
...
- respond
...
- to
...
- "First
...
- and
...
- last
...
- name"
...
- with
...
- the
...
- fully-qualified
...
- domain
...
- name
...
- of
...
- your
...
- server
...
- (e.g.
...
- test-dspace.myuni.edu
...
- ).
...
- The
...
- other
...
- questions
...
- are
...
- not
...
- important.
...
- Optional – ONLY if you need to accept client certificates for the X.509
...
- certificate
...
- stackable
...
- authentication
...
- module
...
- See
...
- the
...
- configuration
...
- section
...
- for
...
- instructions
...
- on
...
- enabling
...
- the
...
- X.509
...
- authentication
...
- method.
...
- Load
...
- the
...
- keystore
...
- with
...
- the
...
- CA
...
- (certifying
...
- authority)
...
- certificates
...
- for
...
- the
...
- authorities
...
- of
...
- any
...
- clients
...
- whose
...
- certificates
...
- you
...
- wish
...
- to
...
- accept.
...
- For
...
- example,
...
- assuming
...
- the
...
- client
...
- CA
...
- certificate
...
- is
...
- in
...
- client1.pem
...
- :
...
Code Block
...
$JAVA_HOME/bin/keytool -import -noprompt -storepass changeit -trustcacerts -keystore $CATALINA_BASE/conf/keystore -alias client1 -file client1.pem
- Follow the procedure in the section above to add another Connector tag, for the HTTPS port, to your server.xml file.
To use SSL on Apache HTTPD with mod_jk:
If you choose Apache HTTPD as your primary HTTP server, you can have it forward requests to the Tomcat servlet container via Apache Jakarta Tomcat Connector. This can be configured to work over SSL as well. First, you must configure Apache for SSL; for Apache 2.0 see Apache SSL/TLS Encryption for information about using mod_ssl.
If you are using X.509 Client Certificates for authentication: add these configuration options to the appropriate httpd configuration file, e.g. ssl.conf, and be sure they are in force for the virtual host and namespace locations dedicated to DSpace:
Code Block |
---|
{code} ## Follow the procedure in the section above to add another Connector tag, for the HTTPS port, to your _server.xml_ file. h4. To use SSL on Apache HTTPD with mod_jk: If you choose [Apache HTTPD|http://httpd.apache.org/|Apache HTTPD] as your primary HTTP server, you can have it forward requests to the [Tomcat servlet container|http://tomcat.apache.org/|Tomcat servlet container] via [Apache Jakarta Tomcat Connector|http://tomcat.apache.org/connectors-doc/|Apache Jakarta Tomcat Connector]. This can be configured to work over SSL as well. First, you must configure Apache for SSL; for Apache 2.0 see [Apache SSL/TLS Encryption|http://httpd.apache.org/docs/2.0/ssl/|Apache SSL/TLS Encryption] for information about using [mod_ssl|http://httpd.apache.org/docs/2.0/mod/mod_ssl.html|mod_ssl]. *{_}If you are using X.509 Client Certificates for authentication:_* add these configuration options to the appropriate _httpd_ configuration file, e.g. _ssl.conf_, and be sure they are in force for the virtual host and namespace locations dedicated to DSpace: {code} ## SSLVerifyClient can be "optional" or "require" SSLVerifyClient optional SSLVerifyDepth 10 SSLCACertificateFile path-to-your-client-CA-certificate SSLOptions StdEnvVars ExportCertData {code} |
Now
...
consult
...
the
...
...
...
...
...
documentation
...
to
...
configure
...
the
...
mod_jk
...
(note:
...
NOT
...
mod_jk2
...
)
...
module.
...
Select
...
the
...
AJP
...
1.3
...
connector
...
protocol.
...
Also
...
follow
...
the
...
instructions
...
there
...
to
...
configure
...
your
...
Tomcat
...
server
...
to
...
respond
...
to
...
AJP.
...
To
...
use
...
SSL
...
on
...
Apache
...
HTTPD
...
with
...
mod_webapp
...
consult
...
the
...
DSpace
...
1.3.2
...
documentation.
...
Apache
...
have
...
deprecated
...
the
...
mod_webapp
...
connector
...
and
...
recommend
...
using
...
mod_jk
...
.
...
To
...
use
...
Jetty's
...
HTTPS
...
support
...
consult
...
the
...
documentation
...
for
...
the
...
relevant
...
tool.
...
The Handle Server
First a few facts to clear up some common misconceptions:
- You don't have to use CNRI's Handle system. At the moment, you need to change the code a little to use something else (e.g PURLs) but that should change soon.
- You'll notice that while you've been playing around with a test server, DSpace has apparently been creating handles for you looking like hdl:123456789/24 and so forth. These aren't really Handles, since the global Handle system doesn't actually know about them, and lots of other DSpace test installs will have created the same IDs.They're only really Handles once you've registered a prefix with CNRI (see below) and have correctly set up the Handle server included in the DSpace distribution. This Handle server communicates with the rest of the global Handle infrastructure so that anyone that understands Handles can find the Handles your DSpace has created. 
If you want to use the Handle system, you'll need to set up a Handle server. This is included with DSpace. Note that this is not required in order to evaluate DSpace; you only need one if you are running a production service. You'll need to obtain a Handle prefix from the central CNRI Handle site.
A Handle server runs as a separate process that receives TCP requests from other Handle servers, and issues resolution requests to a global server or servers if a Handle entered locally does not correspond to some local content. The Handle protocol is based on TCP, so it will need to be installed on a server that can broadcast and receive TCP on port 2641.
Wiki Markup To configure your DSpace installation to run the handle server, run the following command: _\[dspace\]/bin/dspace make-handle-config_Ensure that \_\[dspace\]/handle-server_ matches whatever you have in _dspace.cfg_ for the _handle.dir_ property.
...
Wiki Markup Edit the resulting _\[dspace\]/handle-server/config.dct_ file to include the following lines in the _"server_config"_ clause:
...
Code Block
...
"storage_type" = "CUSTOM" "storage_class" = "org.dspace.handle.HandlePlugin"
...
This
...
- tells
...
- the
...
- Handle
...
- server
...
- to
...
- get
...
- information
...
- about
...
- individual
...
- Handles
...
- from
...
- the
...
- DSpace
...
- code. 
...
- Once
...
- the
...
- configuration
...
- file
...
- has
...
- been
...
- generated,
...
- you
...
- will
...
- need
...
- to
...
- go
...
- to
...
...
- to
...
- upload
...
- the
...
- generated
...
- sitebndl.zip
...
- file.
...
- The
...
- upload
...
- page
...
- will
...
- ask
...
- you
...
- for
...
- your
...
- contact
...
- information.
...
- An
...
- administrator
...
- will
...
- then
...
- create
...
- the
...
- naming
...
- authority/prefix
...
- on
...
- the
...
- root
...
- service
...
- (known
...
- as
...
- the
...
- Global
...
- Handle
...
- Registry),
...
- and
...
- notify
...
- you
...
- when
...
- this
...
- has
...
- been
...
- completed.
...
- You
...
- will
...
- not
...
- be
...
- able
...
- to
...
- continue
...
- the
...
- handle
...
- server
...
- installation
...
- until
...
- you
...
- receive
...
- further
...
- information
...
- concerning
...
- your
...
- naming
...
- authority.
...
Wiki Markup When CNRI has sent you your naming authority prefix, you will need to edit the _config.dct_ file. The file will be found in _/\[dspace\]/handle-server_. Look for _"300:0.NA/YOUR_NAMING_AUTHORITY"_Replace \_YOUR_NAMING_AUTHORITY_ with the assigned naming authority prefix sent to you.
...
- Now
...
- start
...
- your
...
- handle
...
- server
...
- (as
...
- the
...
- dspace
...
- user): 
...
Code Block
...
[dspace]/bin/start-handle-server
...
Note
...
- that
...
- since
...
- the
...
- DSpace
...
- code
...
- manages
...
- individual
...
- Handles,
...
- administrative
...
- operations
...
- such
...
- as
...
- Handle
...
- creation
...
- and
...
- modification
...
- aren't
...
- supported
...
- by
...
- DSpace's
...
- Handle
...
- server.
...
Updating
...
Existing
...
Handle
...
Prefixes
Wiki Markup |
---|
If you need to update the handle prefix on items created before the CNRI registration process you can run the _\[dspace\]/bin/dspace update-handle-prefix script_. You may need to do this if you loaded items prior to CNRI registration (e.g. setting up a demonstration system prior to migrating it to production). The script takes the current and new prefix as parameters. For example: |
Code Block |
---|
}[dspace]/bin/dspace update-handle-prefix 123456789 1303 {code} |
This
...
script
...
will
...
change
...
any
...
handles
...
currently
...
assigned
...
prefix
...
123456789
...
to
...
prefix
...
1303,
...
so
...
for
...
example
...
handle
...
123456789/23
...
will
...
be
...
updated
...
to
...
1303/23
...
in
...
the
...
database.
...
Google and HTML sitemaps
To aid web crawlers index the content within your repository, you can make use of sitemaps. There are currently two forms of sitemaps included in DSpace; Google sitemaps and HTML sitemaps.
Sitemaps allow DSpace to expose it's content without the crawlers having to index every page. HTML sitemaps provide a list of all items, collections and communities in HTML format, whilst Google sitemaps provide the same information in gzipped XML format.
Wiki Markup |
---|
To generate the sitemaps, you need to run _\[dspace\]/bin/generate-sitemaps_ This creates the sitemaps in _\[dspace\]/sitemaps/_ |
...
The
...
sitemaps
...
can
...
be
...
accessed
...
from
...
the
...
following
...
URLs:
...
...
- -
...
- Index
...
- sitemap 
...
...
- -
...
- First
...
- list
...
- of
...
- items
...
- (up
...
- to
...
- 50,000) 
...
...
- -
...
- Subsequent
...
- lists
...
- of
...
- items
...
- (e.g.
...
- 50,0001
...
- to
...
- 100,000)
...
- etc... 
...
HTML
...
- sitemaps
...
- follow
...
- the
...
- same
...
- procedure:
...
...
- -
...
- Index
...
- sitemap 
...
- etc... 
...
Wiki Markup |
---|
When running _\[dspace\]/bin/generate-sitemaps_ the script informs Google that the sitemaps have been updated. For this update to register correctly, you must first register your Google sitemap index page (_/dspace/sitemap_) with Google at [http://www.google.com/webmasters/sitemaps/|http://www.google.com/webmasters/sitemaps/|http://www.google.com/webmasters/sitemaps/]. If your DSpace server requires the use of a HTTP proxy to connect to the Internet, ensure that you have set _http.proxy.host_ and _http.proxy.port_ in _\[dspace\]/config/dspace.cfg_ |
...
Wiki Markup |
---|
The URL for pinging Google, and in future, other search engines, is configured in _\[dspace-space\]/config/dspace.cfg_ using the _sitemap.engineurls_ setting where you can provide a comma-separated list of URLs to 'ping'. |
...
You
...
can
...
generate
...
the
...
sitemaps
...
automatically
...
every
...
day
...
using
...
an
...
additional
...
cron
...
job:
Code Block |
---|
} # Generate sitemaps 0 6 * * * [dspace]/bin/generate-sitemaps {code} h3. DSpace Statistics DSpace uses the Apache Solr application underlaying the statistics. There is no need to download any separate software. All the necessary software is included. To understand all of the configuration property keys, the user should refer to |
DSpace Statistics
DSpace uses the Apache Solr application underlaying the statistics. There is no need to download any separate software. All the necessary software is included. To understand all of the configuration property keys, the user should refer to 5.2.35
...
DSpace
...
Statistic
...
Configuration
...
for
...
detailed
...
information.
...
- DSpace
...
- Configuration
...
- for
...
- Accessing
...
- Solr.
...
- In
...
- the
...
- dspace.cfg
...
- file
...
- review
...
- the
...
- following
...
- fields
...
- to
...
- make
...
- sure
...
- they
...
- are
...
- uncommented:
...
Code Block
...
solr.log.server = ${dspace.baseUrl}/solr/statistics solr.dbfile = ${dspace.dir}/config/GeoLiteCity.dat solr.spiderips.urls = http://iplists.com/google.txt, \ http://iplists.com/inktomi.txt, \ http://iplists.com/lycos.txt, \ http://iplists.com/infoseek.txt, \ http://iplists.com/altavista.txt, \ http://iplists.com/excite.txt, \ http://iplists.com/misc.txt, \ http://iplists.com/non_engines.txt
...
- DSpace logging configuration for Solr. If your DSpace instance is protected by a proxy server, in order for Solr to log the correct IP address of the user rather than of the proxy, it must be configured to look for the X-Forwarded-For
...
- header.
...
- This
...
- feature
...
- can
...
- be
...
- enabled
...
- by
...
- ensuring
...
- the
...
- following
...
- setting
...
- is
...
- uncommented
...
- in
...
- the
...
- logging
...
- section
...
- of
...
- dspace.cfg
...
- :
...
Code Block
...
useProxies = true
...
- DSpace configuration for fields indexed into Solr Event records for search. In the dspace.cfg file, review the following property keys to make sure they are uncommented:
Code Block statistics.items.dc.1=dc.identifier statistics.items.dc.2=dc.date.accessioned statistics.items.type.1=dcinput statistics.items.type.2=date statistics.default.start.datepick = 01/01/1977
...
- Configuration Control.
...
- In
...
- the
...
- dspace.cfg
...
- set
...
- the
...
- following
...
- property
...
- key:_statistics.item.authorization.admin=true_This
...
- will
...
- require
...
- the
...
- user
...
- to
...
- sign
...
- on
...
- to
...
- see
...
- that
...
- statistics.
...
- Setting
...
- the
...
- statistics
...
- to
...
- "false"
...
- will
...
- make
...
- them
...
- publicly
...
- available. 
...
- Final
...
- steps. 
...
- Perform
...
- the
...
- following
...
- step: 
...
Code Block
...
cd [dspace-source]/dspace mvn package cd [dspace-source]/dspace/target/dspace-<version>-build.dir ant -Dconfig=[dspace]/config/dspace.cfg update cp -R [dspace]/webapps/* [TOMCAT]/webapps
...
Wiki Markup If you only need to build the statistics, and don't make any changes to other web applications, you can replace the copy step above with: _cp \-R \[dspace\]/webapps/solr \[TOMCAT\]/webapps_
...
- Restart
...
- your
...
- webapps
...
- (Tomcat/Jetty/Resin) 
...
Windows Installation
Pre-requisite
...
Software
...
You'll
...
need
...
to
...
install
...
this
...
pre-requisite
...
software:
...
...
...
...
- or
...
- later
...
- (standard
...
- SDK
...
- is
...
- fine,
...
- you
...
- don't
...
- need
...
- J2EE)
...
...
...
...
- OR
...
...
...
...
...
- .
- If you install PostgreSQL, it's
...
- recommended
...
- to
...
- select
...
- to
...
- install
...
- the
...
- pgAdmin
...
- III
...
- tool
...
...
...
...
...
...
- .
...
- 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
...
...
...
Installation Steps
- Download the DSpace source from SourceForge and untar it (WinZip will do this)
- Ensure the PostgreSQL service is running, and then run pgAdmin III (Start -> PostgreSQL 8.0 -> pgAdmin III). Connect to the local database as the postgres user and:
- Create a 'Login Role' (user) called dspace with the password dspace
- Create a database called dspace owned by the user dspace, with UTF-8 encoding
Wiki Markup Update paths in _\[dspace-source\]\dspace\config\dspace.cfg_. *Note:* Use forward slashes / for path separators, though you can still use drive letters, e.g.:_dspace.dir = C:/DSpace_Make sure you change all of the parameters with file paths to suit, specifically: 
...
Code Block
...
dspace.dir config.template.log4j.properties config.template.log4j-handle-plugin.properties config.template.oaicat.properties assetstore.dir log.dir upload.temp.dir report.dir handle.dir
...
- Create the directory for the DSpace installation (e.g.
...
- C:\DSpace
...
- )
Wiki Markup Generate the DSpace installation package by running the following from command line (cmd) from your _\[dspace-source\]/dspace/_ directory:
...
Code Block
...
mvn package
...
Wiki Markup Note #1: This will generate the DSpace installation package in your _\[dspace-source\]/dspace/target/dspace-\[version\]-build.dir/_ directory.Note #2: Without any extra arguments, the DSpace installation package is initialized for PostgreSQL. If you want to use Oracle instead, you should build the DSpace installation package as follows: 
...
Code Block
...
mvn -Ddb.name=oracle package
...
Wiki Markup Initialize the DSpace database and install DSpace to _\[dspace\]_ (e.g. _C:\DSpace_) by running the following from command line from your _\[dspace-source\]/dspace/target/dspace-\[version\]-build.dir/_ directory:
...
Code Block
...
ant fresh_install
...
Note:
...
- to
...
- see
...
- a
...
- complete
...
- list
...
- of
...
- build
...
- targets,
...
- run
...
Code Block
...
ant help
...
Wiki Markup Create an administrator account, by running the following from your _\[dspace\]_ (e.g. _C:\DSpace_) directory_\[dspace\]\bin\dspace create-administrator_and enter the required information 
...
Wiki Markup Copy the Web application directories from _\[dspace\]\webapps to Tomcat's webapps dir, which should be somewhere like C:\Program Files\Apache Software Foundation\Tomcat 5.5\webapps_
...
Wiki Markup Alternatively, Tell your Tomcat 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):
...
Code Block
...
<!-- DEFINE A CONTEXT PATH FOR DSpace JSP User Interface --> <Context path="/jspui" docBase="[dspace]\webapps\jspui" debug="0" reloadable="true" cachingAllowed="false" allowLinking="true"/> <!-- DEFINE A CONTEXT PATH FOR DSpace OAI User Interface --> <Context path="/oai" docBase="[dspace]\webapps\oai" debug="0" reloadable="true" cachingAllowed="false" allowLinking="true"/>
...
- Start the Tomcat service
- Browse to either http://localhost:8080/jspui
...
- or
...
...
- .
...
- You
...
- should
...
- see
...
- the
...
- DSpace
...
- home
...
- page
...
- for
...
- either
...
- the
...
- JSPUI
...
- or
...
- XMLUI,
...
- respectively.
...
Checking Your Installation
The administrator needs to check the installation to make sure all components are working. Here is list of checks to be performed. In brackets after each item, it the associated component or components that might be the issue needing resolution.
Wiki Markup System is up and running. _User can see the DSpace home page. \[Tomcat/Jetty, firewall, IP assignment, DNS\]_
...
Wiki Markup Database is running and working correctly. _Attempt to create a user, community or collection \[PostgreSQL, Oracle\]_{_}Run the test database command to see if other issues are being report:__\[dspace\]/bin/dspace test-database_
...
Wiki Markup Email subsystem is running. The user can issue the following command to test the email system. t attempts to send a test email to the email address that is set in dspace.cfg (mail.admin). If it fails, you will get messages informing you as to why, will refer you to the DSpace documentation. _\[dspace\]/bin/test-email_
...
Known
...
Bugs
...
In
...
any
...
software
...
project
...
of
...
the
...
scale
...
of
...
DSpace,
...
there
...
will
...
be
...
bugs.
...
Sometimes,
...
a
...
stable
...
version
...
of
...
DSpace
...
includes
...
known
...
bugs.
...
We
...
do
...
not
...
always
...
wait
...
until
...
every
...
known
...
bug
...
is
...
fixed
...
before
...
a
...
release.
...
If
...
the
...
software
...
is
...
sufficiently
...
stable
...
and
...
an
...
improvement
...
on
...
the
...
previous
...
release,
...
and
...
the
...
bugs
...
are
...
minor
...
and
...
have
...
known
...
workarounds,
...
we
...
release
...
it
...
to
...
enable
...
the
...
community
...
to
...
take
...
advantage
...
of
...
those
...
improvements.
...
The
...
known
...
bugs
...
in
...
a
...
release
...
are
...
documented
...
in
...
the
...
KNOWN_BUGS
...
file
...
in
...
the
...
source
...
package.
...
Please
...
see
...
the
...
...
...
...
...
for
...
further
...
information
...
on
...
current
...
bugs,
...
and
...
to
...
find
...
out
...
if
...
the
...
bug
...
has
...
subsequently
...
been
...
fixed.
...
This
...
is
...
also
...
where
...
you
...
can
...
report
...
any
...
further
...
bugs
...
you
...
find.
...
Common Problems
In an ideal world everyone would follow the above steps and have a fully functioning DSpace. Of course, in the real world it doesn't always seem to work out that way. This section lists common problems that people encounter when installing DSpace, and likely causes and fixes. This is likely to grow over time as we learn about users' experiences.
- Database errors occur when you run ant fresh_install: There are two common errors that occur. If your error looks like this-- 
Code Block [java] 2004-03-25 15:17:07,730 INFO org.dspace.storage.rdbms.InitializeDatabase @ Initializing Database [java] 2004-03-25 15:17:08,816 FATAL org.dspace.storage.rdbms.InitializeDatabase @ Caught exception: [java] org.postgresql.util.PSQLException: Connection refused. Check that the hostname and port are correct and that the postmaster is accepting TCP/IP connections. [java] at org.postgresql.jdbc1.AbstractJdbc1Connection.openConnection(AbstractJd bc1Connection.java:204) [java] at org.postgresql.Driver.connect(Driver.java:139)
...
Wiki Markup it usually means you haven't yet added the relevant configuration parameter to your PostgreSQL configuration (see above), or perhaps you haven't restarted PostgreSQL after making the change. Also, make sure that the _db.username_ and _db.password_ properties are correctly set in _\[dspace-source\]/config/dspace.cfg_.An easy way to check that your DB is working OK over TCP/IP is to try this on the command line: 
...
Code Block
...
psql -U dspace -W -h localhost
...
Enter
...
- the
...
- dspace
...
- database
...
- password,
...
- and
...
- you
...
- should
...
- be
...
- dropped
...
- into
...
- the
...
- psql
...
- tool
...
- with
...
- a
...
- dspace=>
...
- prompt.Another
...
- common
...
- error
...
- looks
...
- like
...
- this: 
...
Code Block
...
[java] 2004-03-25 16:37:16,757 INFO org.dspace.storage.rdbms.InitializeDatabase @ Initializing Database [java] 2004-03-25 16:37:17,139 WARN org.dspace.storage.rdbms.DatabaseManager @ Exception initializing DB pool [java] java.lang.ClassNotFoundException: org.postgresql.Driver [java] at java.net.URLClassLoader$1.run(URLClassLoader.java:198) [java] at java.security.AccessController.doPrivileged(Native Method) [java] at java.net.URLClassLoader.findClass(URLClassLoader.java:186)
...
Wiki Markup This means that the PostgreSQL JDBC driver is not present in _\[dspace-source\]/lib_. See above.
...
- Tomcat
...
- doesn't
...
- shut
...
- down
...
- :
...
- If
...
- you're
...
- trying
...
- to
...
- tweak
...
- Tomcat's
...
- configuration
...
- but
...
- nothing
...
- seems
...
- to
...
- make
...
- a
...
- difference
...
- to
...
- the
...
- error
...
- you're
...
- seeing,
...
- you
...
- might
...
- find
...
- that
...
- Tomcat
...
- hasn't
...
- been
...
- shutting
...
- down
...
- properly,
...
- perhaps
...
- because
...
- it's
...
- waiting
...
- for
...
- a
...
- stale
...
- connection
...
- to
...
- close
...
- gracefully
...
- which
...
- won't
...
- happen.
...
- To
...
- see
...
- if
...
- this
...
- is
...
- the
...
- case,
...
- try:
...
Code Block
...
ps -ef | grep java
...
and
...
- look
...
- for
...
- Tomcat's
...
- Java
...
- processes.
...
- If
...
- they
...
- stay
...
- around
...
- after
...
- running
...
- Tomcat's
...
- shutdown.sh
...
- script,
...
- trying
...
- kill_ing
...
- them
...
- (with
...
- _-9
...
- if
...
- necessary),
...
- then
...
- starting
...
- Tomcat
...
- again.
...
- Database
...
- connections
...
- don't
...
- work,
...
- or
...
- accessing
...
- DSpace
...
- takes
...
- forever
...
- :
...
- If
...
- you
...
- find
...
- that
...
- when
...
- you
...
- try
...
- to
...
- access
...
- a
...
- DSpace
...
- Web
...
- page
...
- and
...
- your
...
- browser
...
- sits
...
- there
...
- connecting,
...
- or
...
- if
...
- the
...
- database
...
- connections
...
- fail,
...
- you
...
- might
...
- find
...
- that
...
- a
...
- 'zombie'
...
- database
...
- connection
...
- is
...
- hanging
...
- around
...
- preventing
...
- normal
...
- operation.
...
- To
...
- see
...
- if
...
- this
...
- is
...
- the
...
- case,
...
- try:
...
Code Block
...
ps -ef | grep postgres
...
You
...
- might
...
- see
...
- some
...
- processes
...
- like
...
- this:
...
Code Block
...
dspace 16325 1997 0 Feb 14 ? 0:00 postgres: dspace dspace 127.0.0.1 idle in transaction
...
This
...
- is
...
- normal--DSpace
...
- maintains
...
- a
...
- 'pool'
...
- of
...
- open
...
- database
...
- connections,
...
- which
...
- are
...
- re-used
...
- to
...
- avoid
...
- the
...
- overhead
...
- of
...
- constantly
...
- opening
...
- and
...
- closing
...
- connections.
...
- If
...
- they're
...
- 'idle'
...
- it's
...
- OK;
...
- they're
...
- waiting
...
- to
...
- be
...
- used.
...
- However
...
- sometimes,
...
- if
...
- something
...
- went
...
- wrong,
...
- they
...
- might
...
- be
...
- stuck
...
- in
...
- the
...
- middle
...
- of
...
- a
...
- query,
...
- which
...
- seems
...
- to
...
- prevent
...
- other
...
- connections
...
- from
...
- operating,
...
- e.g.:
...
Code Block
...
dspace 16325 1997 0 Feb 14 ? 0:00 postgres: dspace dspace 127.0.0.1 SELECT
...
This
...
- means
...
- the
...
- connection
...
- is
...
- in
...
- the
...
- middle
...
- of
...
- a
...
- SELECT
...
- operation,
...
- and
...
- if
...
- you're
...
- not
...
- using
...
- DSpace
...
- right
...
- that
...
- instant,
...
- it's
...
- probably
...
- a
...
- 'zombie'
...
- connection.
...
- If
...
- this
...
- is
...
- the
...
- case,
...
- try
...
- _kill_ing
...
- the
...
- process,
...
- and
...
- stopping
...
- and
...
- restarting
...
- Tomcat.