Installation Guide Structure_Matthias_03x - eSciDoc

gasownerΔιαχείριση Δεδομένων

31 Ιαν 2013 (πριν από 4 χρόνια και 9 μήνες)

219 εμφανίσεις

Installation Guide Structure







Version History

Date

Author

Version

Comment

2008
-
11
-
24

KST

0.2

Added OSX specifics























Table Of Contents

1

Introduction

................................
................................
................................
........................

5

1.1

Purpose

................................
................................
................................
........................

5

1.2

Scope and Organization of This Manual

................................
................................
......

5

1.3

Document Conventions

................................
................................
...............................

6

1.3.1

Typographic Conventions

................................
................................
.....................

6

1.3.2

Placeholders

................................
................................
................................
.........

6

1.3.3

Environment

................................
................................
................................
.........

7

1.3.4

Common

Directories

................................
................................
............................

7

1.3.5

Environment Variables

................................
................................
.........................

7

1.4

Acronyms, Abbreviations, and Definitions

................................
................................
..

8

1.5

Reference Documents

................................
................................
................................
.

9

2

Installation Prerequisites
................................
................................
................................
....

9

2.1

Overview

................................
................................
................................
......................

9

2.2

Hardware Req
uirements

................................
................................
.............................

9

2.3

Supported Operation Systems
................................
................................
.....................

9

2.3.1

Linux

................................
................................
................................
.....................

9

2.3.2

Sun Solaris

................................
................................
................................
............

9

2.3.3

Mac OS X
................................
................................
................................
...............

9

2.3.4

Windows

................................
................................
................................
...............

9

2.4

Required Software Components

................................
................................
.................

9

2.4.1

Java

................................
................................
................................
.......................

9

2.4.2

Ant

................................
................................
................................
........................

9

2.5

Required User Account Privileges

................................
................................
...............

9

2.6

Recommended Directory Layout

................................
................................
.................

9

3

Simple Installation

................................
................................
................................
..............

9

3.1

Over
view

................................
................................
................................
......................

9

3.2

Step 2: Database Server
................................
................................
...............................

9

3.2.1

Setting up a Relational Database

................................
................................
.........

9

3.2.2

Configuring the Fedora Database

................................
................................
......

11

3.2.3

Configuring the eSciDoc Core Database

................................
.............................

11

3.3

Step 3: JBoss Application Server

................................
................................
................

12

3.3.1

Setting up JBoss Application Server

................................
................................
...

12

3.3.2

Configuring JBoss Application Server

................................
................................
.

13

3.4

Step 4: Fedora Commons

................................
................................
..........................

13

3.
4.1

Running the Fedora Commons Installer

................................
.............................

13

3.4.2

Deploying Fedora Commons

................................
................................
..............

13

3.4.3

Configuring Fedora Commons

................................
................................
............

13

3.5

Step 5: eSciDoc
Infrastructure

................................
................................
...................

15

3.5.1

Setting up the eSciDoc Infrastructure

................................
................................

15

3.5.2

Configuring the eSciDoc Infrastructure

................................
..............................

15

3.5.3

Creating and populating the database tables

................................
....................

16

3.6

Launching Infrastructure

................................
................................
...........................

16

3.7

Next Steps

................................
................................
................................
..................

17

4

Installation

of Optional Tools

................................
................................
...........................

17

4.1

eSciDoc Infrastructure Administration Tool

................................
..............................

17

4.1.1

Purpose

................................
................................
................................
...............

17

4.1.2

Setting up the eSciDoc Infrastructure
Administration Tool

...............................

17

4.1.3

Configuring the eSciDoc Infrastructure Administration Tool

.............................

17

4.2

Digilib Image Manipulation Service

................................
................................
...........

17

4.2.1

Purpose

................................
................................
................................
...............

17

4.2.2

Setting up the Digilib Image Manipulation Service

................................
............

17

4.2.3

Configuring the Digilib Image Manipulation Service

................................
..........

17

4.3

Duplicate Detection Service

................................
................................
......................

17

4.3.1

Purpose

................................
................................
................................
...............

17

4.3.2

Setting up the Duplicate Detection Service

................................
.......................

17

4.3.3

Configuring the Duplicate Detection Service

................................
.....................

17

4.4

PID Manager

................................
................................
................................
..............

17

4.4.1

Purpose

................................
................................
................................
...............

17

4.4.2

Setting up the PID Manager

................................
................................
...............

17

4.4.3

Configuring the PID Manager

................................
................................
.............

17

5

Advanced Installation Procedures
................................
................................
....................

17

5.1

Using an Existing Database Installation

................................
................................
.....

17

5.2

Using MySQL as Database Backend

................................
................................
...........

17

5.3

Multi
-
Server (Distributed) Setup

................................
................................
...............

17

5.4

Alternative Authentication and Authorization Methods

................................
..........

17

5.4.1

Directory Servers via Lightweight Directory Access Protocol
(LDAP)

................

17

5.4.2

Distributed Authentication via Shibboleth
................................
.........................

17

6

Testing the Installation

................................
................................
................................
.....

17

6.1

Starting the eSciDoc Infrastructure

................................
................................
...........

17

6.2

Ingesting Examples

................................
................................
................................
....

18

6.2.1

Download Example Resources

................................
................................
...........

1
8

6.2.2

Ingesting Examples (FOXML)

................................
................................
..............

18

6.2.3

Ingesting eSciDoc (eSciDoc XML representation)

................................
..............

18

6.3

Retrieving Example Objects

................................
................................
.......................

19

6.4

Checking Infrastructure

................................
................................
.............................

19

6.5

Shutting down the eSciDoc Infrastructure

................................
................................

20

7

Uninstalling eSciDoc

................................
................................
................................
.........

20

7.1

eSciDoc Software Only

................................
................................
...............................

20

7.2

eSciDoc and Database

................................
................................
...............................

21

7.3

eSciDoc, Database, and Data

................................
................................
.....................

21

8

Troubleshooting

................................
................................
................................
...............

22

8.1

Installation Issues

................................
................................
................................
......

22

8.1.1

Database not started

................................
................................
..........................

22

8.1.2

Missing Database Initialization
................................
................................
...........

22

8.1.3

Database without UTF
-
8 Support

................................
................................
.......

22

8.1.4

Database cannot be started as service

................................
..............................

22

8.1.5

Database cannot be accessed

................................
................................
............

22

8.2

Runtime Issues

................................
................................
................................
...........

22

8.2.1

Data
base not started or inaccessible

................................
................................
.

22

8.2.2

Server not accessible from other machines

................................
.......................

22

8.2.3

Ingestion of Examples fails

................................
................................
.................

22

8.2.4

Authentication fails

................................
................................
............................

22

8.2.5

Searches yield in empty result lists

................................
................................
....

22

8.2.6

Retrieval of a resource results in an exception

................................
..................

22

9

Appendixes

................................
................................
................................
.......................

22

9.1

Appendix A: Fedora Commons: fedora.fcfg

................................
..............................

22

9.2

Appendix B: eSciDoc Infrastructure: escidoc
-
core.properties

................................
..

22

9.3

Appendix C: Administration Tool: admin
-
tool.properties

................................
.........

22

10

Index

................................
................................
................................
................................
.

22









1

Introduction

1.1

Purpose

eSciDoc is an open
-
source e
-
Research environment. eSciDoc consists of a generic framework
(the “eSciDoc Infrastructure”) and end
-
user
-
facing applications (“eSciDoc Solutions”). All
eSciDoc Solutions require an installation of the eSciDoc Infrastructure as
a prerequisite for
their own installation.
The purpose of this document is to enable the reader to install eSciDoc

Infrastructure

Version 1.0
onto their server.


eSciDoc is a complex software stack, consisting of various software components. They have
to b
e installed step by step in the right order. These steps are covered in this document in
detail.
In some cases, it may be necessary to install and configure a runtime e
nvironment prior
to installing
the
eSciDoc
Infrastructure.

If this is an upgrade to a pr
eviously installed version of the Infrastructure, you may need to
migrate your repository. For detailed instructions, see the documentation that comes with the
eSciDoc Infrastructure Administration Tool.

1.2

Scope and Organization of This Manual

This document
includes step
-
by
-
step procedures for the eSciDoc
Infrastructure
installation
process
. It does not cover the installation of any eSciDoc Solution. Please refer to the
installation instructions that come with the respective solution for further information o
n how
to install them on the eSciDoc Infrastructure.

eSciDoc requires several software components (such as a Java SDK, Apache Ant, and a
relational database management system), which are not specific to eSciDoc. In this
Installation Guide, we will only hig
hlight the specific configuration settings for each of these
components as required by eSciDoc.

This document covers the installation process for Unix
-
like systems (Sun Solaris, Linux),
Mac OS X, and Windows (XP, Vista
). Sometimes, installation procedures differ between
operating systems. We will mention these differences in the context of these procedures. Be
careful to follow only the description that relates to your operating system.

This d
ocument is intended for us
e by s
ystem
a
dministrators
or experienced users
responsible
for installing the eSciDoc Infrastructure on their server.

Installing eSciDoc Infrastructure
requires familiarity with command
-
line operations and installation of third
-
party software
packages.

Ch
apter 1, “Introduction”, describes purpose of the manual, its scope and its intended
audience. It explains the typographic and other conventions used throughout this document,
and lists reference documents (including online resources) that may be of intere
st to you.

Chapter 2, “Installation Prerequisites”, discusses hardware and user privilege requirements as
well as software that need to be installed on your server as a prerequisite for the eSciDoc
Infrastructure installation process.

Chapter 3, “Simple In
stallation”, explains the default installation process from scratch (with
no preexisting software components) in four steps.

Chapter 4, “Optional Tools”, describe s additional tools and services that you may optionally
install with the eSciDoc Infrastructu
re. For each tool/service, detailed installation instructions
are given.

Chapter 5, “Advanced Installation Procedures”, discusses non
-
default installation processes,
including using a pre
-
installed database, using MySQL instead of PostgreSQL, installing th
e
software onto more than one server, and configuring alternative authentication and
authorization methods.

Chapter 6, “Testing the Installation”, describes procedures for testing the installation,
including ingesting and retrieving example resources.

Chap
ter 7, “Uninstalling eSciDoc Infrastructure”, explains how to uninstall the software
components from your machine(s). Options include keeping the data and/or software
components used by other software packages (RDBMS, Java, Ant).

Chapter 8, ”Troubleshootin
g”

Chapter 9, “Apendixes”

1.3

Document Conventions

1.3.1

Typographic Conventions

This document uses the following typographic conventions:

Example

Description

http://www.escidoc.org/

Hyperlink to an online resource

C:
\
Users
\
escidoc>echo %FEDORA_HOME%

Enter a
command at the command line
(your input is printed in bold)

$FEDORA_HOME

Environment variable

<username>

Placeholder

${escidoc.dir}

Common directory

1.3.2

Placeholders

Placeholders are used in this document to identify settings that can be changed by you during
the installation process. If you decide to change some or all of these settings, please make sure
to note your chosen values carefully, because you will need them

several times during the
installation process.

Placeholder

Description

<install_source>

Source of the installation files and the documents

<host_fedora>

Canonical name
of

the machine onto w
hich Fedora is
being installed

<port_fedora>

Port on which
Fedora listens for incoming requests

<ESCIDOC_USERNAME>

Username of the escidoc
-
core database

<ESCIDOC_PASSWORD>

Password for the escidoc
-
core database user

<FEDORA_USERNAME>

Username for the Fedora database

<FEDORA_PASSWORD>

Password for the Fedora

database user

<DATABASE_SUPERUSER>

Name of the database user (role).

<DATABASE_SUPERUSER_PASSWORD>

Password of the database superuser

<server_escidoc>

Canonical name
of

the machine onto w
hich the
eSciDoc Infrastructure is being installed

<port_escidoc
>

Port on which the eSciDoc Infrastrucutre listens for
incoming requests

<temp directory>

Location of initial software download and where it is
then installed from

1.3.3

Environment

Environment variables are in this document further used in Unix stile.

Variab
le

Value

$ESCIDOC_DIR

Base directory of eSciDoc on the installation target machine.
This is usually the directory where all software components
are installed.

default: /srv/escidoc/

$FEDORA_HOME

Base directory of Fedora on the installation target machine

Default: $ESCIDOC_DIR/fedora/

$JBOSS_HOME

Base directory of JBoss Application server on the installation
target machine


Default: $ESCIDOC_DIR/jboss/


1.3.4

Common Directories

Common directories are placeholders as well. They refer to directories in the
file system of
the target machine for the installation. The actual value for the common directories may vary
depending on your operating system and your personal preferences. Please make sure to
remember the chosen values for these directories carefully, a
s you will have to replace the
placeholders with the actual value in several places throughout the installation process.

Common Directories

Description

${fedora.dir}

Base directory of Fedora on the installation target machine

(default: escidoc/fedora/)

${jboss.dir}

Base directory of JBoss Application server on the installation
target machine

${escidoc.dir}

Base directory of eSciDoc on the installation target machine

1.3.5

Environment Variables

Environment variables

are a set of dynamic values that can affect the way running processes
will behave on a computer. Installing the eSciDoc Infrastructure includes the setting if several
environment variables.

Environment variables
are usually referenced by putting special
symbols in front of or around
the variable name. For instance, to display the
installation directory

of Fedora
on a Windows
system,
you

could type in this command:


Microsoft Windows:

C:
\
Users
\
escidoc>
echo %FEDORA_HOME%

On a Unix
-
like system, you could
type in this command:

Unix
-
like System

escidoc@server01:/opt/escidoc>
echo $FEDORA_HOME

Setting environment variables differs as well between operating systems. Unix
-
like systems
usually come with several command shells, which again differ in setting these
variables. To
set the environment variable FEDORA_HOME on a Windows system, you could type in this
command:

C:
\
Users
\
escidoc>
set FEDORA_HOME=C:
\
Program Files
\
escidoc
\
fedora

On a Unix
-
like system with a Bourne, bash, and related shells, you could type in th
is
command:

escidoc@server01:/opt/escidoc>
export FEDORA_HOME=/opt/escidoc/fedora

On a Unix
-
like system with a csh and related shells, you could type in this command:

escidoc@server01:/opt/escidoc>
setenv FEDORA_HOME=/opt/escidoc/fedora

For the sake of reada
bility, we will use the bash
-
like notation (
$FEDORA_HOME
) throughout
this document. If you use another shell or the Windows operation system, please keep in mind
to adapt this notation accordingly.

1.4

Acronyms, Abbreviations, and Definitions

Term / Abbreviati
on

Definition

API

A
pplication programming interface
:

a set of functions,
procedures, methods, classes or protocols that an operating
system, library or service provides to support requests made
by computer programs.

Application Server

An
application
server
, in an n
-
tier architecture, is a server that
hosts an API to expose business logic and business processes
for use by third
-
party applications
.

DBMS

Database Management System: computer software designed
for the purpose of managing databases. The
role of a DBMS in
a larger system is to allow other software, or users, to store
and retrieve data in a structured way.


EAR

Enterprise Archive Research: a file format used to package
Java programming language applications
.

Fedora

F
lexible
E
xtensible
D
igital
O
bject
R
epository
A
rchitecture
:
Open
-
source repository management software provided by the
non
-
profit organization

Fedora Commons.



RDBMS

Relational
Database Management System: a
database
management system

(DBMS) that is based on the
relational
model
,
in which data is stored in the form of tables and the
relation
ship among the data is also stored in the form of tables.

WAR

Web
A
pplication Archive
:

file format used to package Java
applications
.


1.5

Reference Documents

T
echnical details of the various components can be found at
http://www.escidoc
-
project.de/JSPWiki/en/InstallationForRelease1.0
.

2

Installation Prerequisites

2.1

Overview

2.2

Hardware Requirements

2.3

Supported Operation Systems

2.3.1

Linux

2.3.2

Sun Solaris

2.3.3

Mac

OS X

2.3.4

Windows

2.4

Required Software Components

2.4.1

Java

2.4.2

Ant

2.5

Required User Account Privileges

2.6

Recommended Directory Layout

3

Simple Installation

3.1

Overview

3.2

Step 2: Database Server

The eSciDoc infrastructure requires PostgreSQL or MySQL database.

This document describes

the installation of PostgreSQL version 8.3 or higher.

3.2.1

Setting up a Relational Database (Linux)

The Linux platform gives usually different ways to install software. It is recommended to use
a distribution specific software management tool. This differs from distribution to distribution
and has mostly a graphical interface. See documentation of your L
inux distribution to handle
this.


The following method describes a command line method which should work on the most
Linux systems. Using the command line package installer (rpm or deb).


Linux

Step

Action

1

Download the PostgreSQL
rpm or deb

package from the your distributers repository
or from
http://www.postgresql.org/ftp/binary/

and store it into the TMP folder

2

Make sure that you have super user permissions for your Operating System.

(e.g.
~> su
-

)

3

Run the
RPM
installer

rpm
-
ihv $TMP/NAME_OF_PACKAGE.rpm

4

Setup XML2 module

5

Setup UTF
-
8 encoding

Configurer DB superuser password (postgres)

6

Start Service

~>
/etc/init.d/postgres start



3.2.2

Setting up a Relational Database (Mac OS X)


Mac OS X

Step

Action

1

There are several ways of installing PostgreSQL on Mac OSX. Either use a package
manager like Fink (
http://www.finkproject.org/
, see also the installation instruction
from Apple
http://developer.apple.com/internet/opensource/postgres.html
) or
MacPorts (
http://www.macports.org/
). Alternatively compile and install PostgreSQL
from source.

2

A
n administrative user called “postgres”

must be added. This user has to be the owner
of the PostgreSQL Database.

3

Make sure that the XML2 module is
installed along with PostgreSQL.

4

Ensure that the charset of the database used for eSciDoc and Fedora is set to UTF
-
8.

5

Start the PostgreSQL service.


3.2.3

Setting up a Relational Database (Microsoft Windows)


Microsoft Windows

Step

Action

1

Download the

postgresql Installer from the link

http://www.postgresql.org/download/

2

Unzip the Installer and double click to start the installer.

3

Follow the installation instructions described in the link

http://pginstaller.projects.postgresql.org/

IMPORTANT: Ensure the following options in the following steps are selected.

4

PostgreSQL Installer Step: 6.Initdb

Make the following choices:


Encoding (Server):

UTF8

Encoding (Client):

UTF8

Superuser name:
<DAT
ABASE_SUPERUSER>

Password:

<DATABASE_SUPERUSER
_PASSWORD
>


5

PostgreSQL Installer Step: 8.Contrib modules

Enable XML 2

6

PostgreSQL Installer Step: 11.Finished

Uncheck Launch Stack Builder at exit


7

Start the PostgreSQL Service


Programs
-
> PostgreSQL
8.x
-
> Start service


3.2.4

Configuring the Fedora Database

The following steps creates Fedora specific databases and role.

All Operating Systems

Step

Action

1

Start your favorite database client (e.g. the command line tool ‘psql’ or a graphical tool
like ‘pgAdmin’)


2

Lo
g
i
n

and execute following SQL commands.

3

CREATE ROLE "
<FEDORA_USERNAME>
" LOGIN PASSWORD
'
<FEDORA_PASSWORD>
"

NOINHERIT CREATEDB VALID UNTIL
'infinity';


4

Create Databases for Fedora

CREATE DATABASE "fedora31" WITH ENCODING='UTF8'
OWNER="
<FEDORA_USERNAME>
";


CREATE DATABASE "riTriples" WITH ENCODING='SQL_ASCII'
OWNER="
<FEDORA__USERNAME>
";



3.2.5

Configuring the
eSciDoc Core Database

The following steps creates Fedora specific databases and role.

All Operating Systems

Step

Action

1

Start your favorite database client (e.g. the command line tool ‘psql’ or a graphical
tool like ‘pgAdmin’)


2

Lo
g
i
n

and execute following SQL commands.

3

CREATE ROLE "
<ESCIDOC_USERNAME>
" LOGIN PASSWORD
'
<ESCIDOC_PASSWORD>
' NOINHERIT CREATEDB VALID UNTIL
'infinity';


4

CREATE DATABASE "escidoc
-
core" WITH ENCODING='UTF8'
OWNER="
<ESCIDOC_USERNAME>

";


3.3

Step 3: JBoss
Application Server

3.3.1

Setting up JBoss Application Server

JBoss is an open
-
source Java EE
-
based application server. Because it is Java
-
based, the JBoss
application server is cross
-
platform, usable on any operating system that supports. All
eSciDoc components
are deployed in the JBoss server.

All Operating System

Step

Action

1

Download Jboss Application Server 4.2.3 GA from
http://www.jboss.org/jbossas/downloads/

2

Extract the contents of jboss
-
4.2.3 GA.zip to the directory you wish to install JBoss.
In this document referred to as <JBOSS_INSTALL_DIR>

*Note for Linux and Mac OS X: For JBoss Version 4.2.3 GA there is a minor issue
when starting up the server which will result in the following error message:

./run.sh: line 89: ulimit: open files: cannot modify limit: Invalid

argument

run.sh: Could not
set maximum file descriptor limit: unlimited


This Bug is noncritical and can be solved using the patch provided at:
https://jira.jboss.org/jira/browse/JBAS
-
4948


3

Increase memory settings for
JBoss

Either set JBoss memory options via JAVA_OPTS command line parameter or by
editing JAVA_OPTS within $JBOSS_HOME/bin/run.conf (values in run.conf are
only used if no JAVA_OPTS are defined).

Minium values should be:


Xmx768m
-
Xm512m
-
XX:MaxPermSize=312
m

Note Windows: Change the JAVA_OPTS in the run.bat file


3.3.2

Configuring JBoss Application Server

** can be removed **

3.4

Step 4: Fedora Commons

3.4.1

Running the Fedora Commons Installer

All Operating Systems

Step

Action

1

Download the Installer for Fedora 3.1 from

the link

http://www.fedora
-
commons.org/developers/fedora.php


2

Run the installer

from the command line of your Operating System

java

jar fedora
-
3.1
-
installer.jar

3

Following are the options to be chosen during the installation process,

Options :
quick, custom, client


custom

Fedora home directory



Directory where Fedora to be installed.
Referred in this document with placeholder $FEDORA_HOME

Fedora administrator password


fedoraAdmin

Fedora server host



default(localhost)

Authentication re
quirement for API
-
A

default(false)

SSL availability




false

Servlet engine





other

Use JBoss?





true

Database





postgresql

Postgresql JDBC driver



default(included)

Database username




<FEDORA_USERNAME>

Database password




<FEDORA_PASSWORD>

JDBC URL





default(jdbc:postgresql://localhost/fedora31)

JDBC Driver Class



default(org.postgresql.Driver)

Enable Resource Index


true

Enable REST
-
API



default(false)

Enable Messaging



default(false)

Deploy local services and demos

false

4

Set

the environment variable
FEDORA_HOME

and ensure that this variable is permanent so
that it is still there after rebooting the system..


3.4.2

Deploying Fedora Commons

3.4.3

Configuring Fedora Commons

All Operating Systems

Step

Action

1

Open the
$FEDORA_HOME/server/config/fedora.fcfg

file to modify the following
entries


Change ‘pidNamespace’ f
rom original e
ntry:

<param name="pidNamespace" value="changeme">

To
:

<param name="pidNamespace" value="escidoc">


Change ‘datastore’ from o
riginal e
ntry:

<p
aram name="datastore" value="localMulgaraTriplestore">


<comment>(required)

Name of the triplestore





</comment>

</param>

To:

<param name="datastore" value="localPostgresMPTTriplestore">


<comment>
(required) Name of the triplestore





</comment>

</param>


2

Deploy into JBoss

Copy $FEDORA_HOME/install/fedora.war to $JBOSS_HOME/server/default/deploy/

3

Initiate Fedora

Start JBoss to initiate Fedora data structure. This will create the
necessary database
tables and the security policies for Fedora.

~> $JBOSS_HOME/bin/run. [sh|bat]

b 0.0.0.0

You could also v
erify that Fedora is running by opening
Fedoras description page
under following link:


http://localhost:8080/fedora/describe



4

Create a new policy
with access restrictions


Download XACML rule from
http://www.escidoc
-
project.de/software/fedora/deny
-
everything
-
if
-
not
-
administrato
r.xml

and store it under

$FEDORA_HOME/data/fedora
-
xacml
-
policies/repository
-
policies/


If the target directory not exists, go back to step 7.

5

Empty the contents of log4j.properties

Open $FEDORA_HOME/server/config/log4j.properties

Comment out all log4j
configurations

6

Stop JBoss

~> $JBOSS_HOME/bin/shutdown. [sh|bat]

S


3.5

Step 5: eSciDoc Infrastructure

3.5.1

Setting up the eSciDoc Infrastructure

All Operating Systems

Step

Action

1

Download eScidoc Infrastructure from link

http://www.escidoc
-
project.de/JSPWiki/en/Download


Choose Latest release of
eSciDoc
Core Infrastructure


2

Unzip escidoc
-
core
-
bin.zip to an appropriate directory. This base directory of e
scidoc
will be referred to as
$
TMP


3

Deploy escidoc infrastructure by c
opying
$TMP

\
ear
\
escidoc
-
core.ear to
$JBOSS_HOME

\
server
\
default
\
deploy



3.5.2

Configuring the eSciDoc Infrastructure

All Operating Systems

Step

Action

1

All changed and additional
configuration
-
files are located in the jboss
-
patch
-
release

Click on the link
of

latest
-
release

and save the file jboss
-
patch
-
release.zip


2

Extract the contents of jboss
-
patch
-
release.zip on to
$JBOSS_HOME

The following are the files added or replaced:

Added:

$JBOSS_HOME
/server/default/conf/props/defaultRoles.properties

$
JBOSS_HOME
/server/default/conf/props/defaultUsers.properties

Replaced:

$JBOSS_HOME
/server/default/conf/login
-
config.xml

Added:

$
JBOSS_HOME
/server/default/conf/escidoc
-
core.properties

$
JB
OSS_HOME
/server/default/conf/escidoc
-
login.xml

$JBOSS_HOME
/server/default/conf/tme

$JBOSS_HOME
/server/default/conf/tme
/jhove.conf

$JBOSS_HOME/

server/default/lib/wstx
-
asl
-
3.2.4.jar

$JBOSS_HOME/

server/default/lib/commons
-
logging.jar


3.5.3

Creating and
populating the database tables

All Operating Systems

Step

Action

1

Edit

the file
$TMP
/
etc
/
database
.properties

to verify/
change the default values of
the properties matching your
database

instance
.

2

Initialize eSciDoc database tables by running the following script


~> ant

f
$TMP
/bin/init
-
db.xml



3.6

Launching Infrastructure

Step

Action

1

Start

Database System

Windows: Programs
-
> PostgreSQL 8.x
-
> Start service

Linux: ~> /etc/init.d/postgres start

Mac OSX: Use launchctl or Pg_ctl to start the service

2

Start JBoss

~> $JBOSS_HOME/bin/run.[sh|bat]

b 0.0.0.0

3

Refer Chapter 6 to test the
installed infrastructure


3.7

Next Steps

4

Installation of Optional Tools

4.1

eSciDoc Infrastructure Administration Tool

4.1.1

Purpose

4.1.2

Setting up the eSciDoc Infrastructure Administration Tool

4.1.3

Configuring the eSciDoc Infrastructure Administration Tool

4.2

Digilib Image Mani
pulation Service

4.2.1

Purpose

4.2.2

Setting up the Digilib Image Manipulation Service

4.2.3

Configuring the Digilib Image Manipulation Service

4.3

Duplicate Detection Service

4.3.1

Purpose

4.3.2

Setting up the Duplicate Detection Service

4.3.3

Configuring the Duplicate Detection Service

4.4

PID
Manager

4.4.1

Purpose

4.4.2

Setting up the PID Manager

4.4.3

Configuring the PID Manager

5

Advanced Installation Procedures

5.1

Using an Existing Database Installation

5.2

Using MySQL as Database Backend

5.3

Multi
-
Server (Distributed) Setup

5.4

Alternative Authentication and Authorization
Methods

5.4.1

Directory Servers via Lightweight Directory Access Protocol (LDAP)

5.4.2

Distributed Authentication via Shibboleth

6

Testing the Installation

6.1

Starting the eSciDoc Infrastructure

See section 3.6 to launch the infrastructure.

6.2

Ingesting Examples

eSciDoc provi
des a package with example objects to give a brief overview about the
infrastructure and allow easy first steps. We recommend an installation of these examples.

The examples are dist
ributed in the Fedora

XML data structure

(FOXML). This requires an
ingest
directly to Fedora and not through the eSciDoc interface!

6.2.1

Download Example Resources

All Operating Systems

Step

Action

1

Download escidoc
-
core
-
examples
-
release.zip package from eSciDoc webpage.

2

Unzip escidoc
-
core
-
examples
-
release.zip

~> unzip
escidoc
-
core
-
examples
-
release.zip


6.2.2

Ingesting Examples (FOXML)

All Operating Systems

Step

Action

1

Ingest all examples from the example package FOXML directory into your Fedora repository
either by FedoraAdmin

~> fedora
-
admin.sh


Open
File|Ingest|Multiple Objects|From Directory, select the folder where you extracted the
examples and click ingest.


or by Fedoras command line tool

~> fedora
-
ingest.sh d <EXAMPLE_FOLDER> info:fedora/fedora
-
system:FOXML
-
1.1 <FEDORA_HOSTNAME>:<FEDORA_PORT> <F
EDORA_USERNAME>
<FEDORA_PASSWORD> http “Example Package”


Example:

fedora
-
ingest.sh d ./examples/foxml info:fedora/fedora
-
system:FOXML
-
1.1 localhost:8082 fedoraAdmin fedoraAdmin http “Example Package”

2

Recache eSciDoc resource Database. (requires
AdminTool)

Execute java

jar $ESCIDOC_HOME/tools/adminTool/escidoc
-
admin
-
tool.jar
recache


6.2.3

Ingesting eSciDoc (eSciDoc XML representation)

Step

Action

1

???

2


3



6.3

Retrieving Example Objects

6.4

Checking Infrastructure

Step

Action

1

Check Database


1. Login to the escidoc database with the role escidoc.

2. Check if the database contains tables.
???

2

Check JBoss


Request
Fehler! Hyperlink
-
Referenz ungültig.

It is an indication that eSciDoc infrastructure is well deployed if the eSciDoc startpage
appears.


If you receiving the JBoss start page
instead ob eSciDoc page
redeploy eSciDoc EAR again.


3

Check Fedora


Fedora is configured to allow only access from

localhost (either you not followed the
instruction of this document). Therefore you need to request the Fedora interface from the
installed system.


Open a web browser and request which you have to confirm with the username and password
for your Fedora i
nstallation (<FEDORA_USERNAME>, <FEDORA_PASSWORD>).

Fehler! Hyperlink
-
Referenz ungültig.

???


If Fedora runs well you get a page like this:


If you can retrieve the page without Authentication request make sure to secure the Fedora
interface like described in Fedora Installation section.

4

Request example Item via Browser


Fehler! Hyperlink
-
Referenz ungültig.



you should receive a web page with a representation of eSciDoc Item Example 5



You can retrieve further

eSciDoc Exmaple Container: /ir/container/escidoc:ex7

eSciDoc Exmaple Organizational Unit: /ir/organizational
-
unit/escidoc:ex1

5

Test Search Function


http://escidev6:8080/srw/search/escidoc_all?
\

query=escidoc.public
-
status%3Dreleased*


You should retrieve a search response which contains all released resources. If the
respository contains only the example objects that are these one Item (escidoc:ex5
) and one
Container (escidoc:ex7)

6

Check eSciDoc and JBoss logfile

$JBOSS_HOME/server/default/log/escidoc
-
core.log

$JBOSS_HOME/server/default/log/server.log


for errors.


6.5

Shutting down the eSciDoc Infrastructure

Step

Action

1

Shutdown JBoss

~>
$JBOSS_HOME/bin/shutdown.[sh.bat]
-
S


7

Uninstalling eSciDoc

7.1

eSciDoc Software Only

All Operating Systems

Step

Action

1

Shutdown JBoss

~> $JBOSS_HOME/bin/shutdown.[sh.bat]
-
S

3

Remove eSciDoc from JBoss

Delete escidoc
-
core.ear from
$JBOSS_HOME/server/deault/deploy/ directory.

4

Delete $ESCIDOC_HOME/escidoc
-
infrastructure Directory


7.2

eSciDoc and Database

All Operating Systems

Step

Action

1

Shutdown JBoss

~> $JBOSS_HOME/bin/shutdown.[sh.bat]
-
S

2

Delete Database

Login to Database
management System (either via command line or graphical tool)
and drop the database by calling SQL command.

DROP DATABASE “escidoc
-
core”;

DELETE ROLE escidoc;

3

Remove eSciDoc from JBoss

Delete escidoc
-
core.ear from $JBOSS_HOME/server/deault/deploy/
directory.

4

Delete $ESCIDOC_HOME/escidoc
-
infrastructure directory


7.3

eSciDoc, Database, and Data

All Operating Systems

Step

Action

1

Shutdown JBoss

~> $JBOSS_HOME/bin/shutdown.[sh.bat]

S

2

Delete Databases

Login to Database management System (either
via command line or graphical tool)
and drop the database by calling SQL command.

DROP DATABASE “escidoc
-
core”;

DROP DATABASE “riTriples”;

DROP DATABASE “fedora31”;

DELETE ROLE escidoc;

DELETE ROLE fedoraAdmin;

3

Delete $ESCIDOC_HOME directory


8

Troubleshooting

8.1

Installation Issues

8.1.1

Database not started

8.1.2

Missing Database Initialization

8.1.3

Database without UTF
-
8 Support

8.1.4

Database cannot be started as service

8.1.5

Database cannot be accessed

8.2

Runtime Issues

8.2.1

Database not started or inaccessible

8.2.2

Server not
accessible from other machines

8.2.3

Ingestion of Examples fails

8.2.4

Authentication fails

8.2.5

Searches yield in empty result lists

8.2.6

Retrieval of a resource results in an exception

9

Appendixes

9.1

Appendix A: Fedora Commons: fedora.fcfg

9.2

Appendix B: eSciDoc Infrastructure: esci
doc
-
core.properties

9.3

Appendix C: Administration Tool: admin
-
tool.properties

10

Index