PubMan:Installation walk through

From MPDLMediaWiki
Jump to: navigation, search

DEPRECATED

These instructions are deprecated.

Please use installation instructions on http://pubman.mpdl.mpg.de/software/get_pubman/download.html


See also PubMan:2009 Installation walk through on Suse Linux 10

Installation Step-by-Step: PubManPublication Management 628 Local Installation

Purpose of Document This Document is written to give fuller information on the steps to set up a locally running PubManPublication Management 6.2.8 Server on your Local Machine, together with all the complicated software stack on which it depends. "Installation Verification Checks" at each stage are provided, and some links to further useful documentation.

Intended Audience of this Document Developers, Administrators or Archivists / Librarians with quite advanced computer skills, who wish to see for themselves what PubManPublication Management and EsciDoc may offer for benefits, and look for themselves behind the scenes at the software infrastructure involved.

Scope and dependencies of this Document This Document is written in July/August 2011 and is based on the then current tested PubManPublication Management Production and Demonstration Environment.

  • PubManPublication Management Release: 6.2.8
  • EsciDoc Core-Services: 1.2.3
  • Oracle/Sun Java 6 SDKSoftware Development Kit: 1.6_24 or later 1.6_xx maintenance release
  • JBossOpen source Java EE-based application server Application Server: 4.2.2, 4.2.3 (Later releases exist, but do not work with ESciDocEnhanced Scientific Documentation)
  • PostgreSQL: 8.3 or higher

Limits of this Document Time constraints prevent the documentation of a installation instructions for all tested PubManPublication Management and ESciDocEnhanced Scientific Documentation Environment. Specifically, this document only describes installation of PubManPublication Management 6.2.8 with two tested operating systems environments (Linux (Distribution: Ubuntu 10_04 Desktop 32 Bit) and Windows (Windows 7 Professional 32 Bit) and one tested Database environment (PostgresQL 8.3). It currently also does not include installation instructions on the ESciDocAdmin Application (which allows the creation of new PubManPublication Management / ESciDocEnhanced Scientific Documentation Users and similar administration tasks).

We will update this documentation to cover administration tasks in the future.

A note on the screenshots Severals of the installation steps use graphical installers of up to twenty screens. To preserve space, the screenshots are presented as thumbnails. Simply click on them to expand them back to full size. Use of yellow highlighter indicates that an important default was changed, or important information entered. Screens that simply present introductory information have not been included.

Current Documentation

Here is the at time of writing current documentation on PubManPublication Management and ESciDocEnhanced Scientific Documentation standalone installation, upon which this document attempts to expand.

Pubman Download Page (September 2012)

Installation of Oracle/Sun Java 6 JDKJava Development Kit

Installation on Linux

Neither PubManPublication Management, nor ESciDocEnhanced Scientific Documentation Core-Services, nor JBossOpen source Java EE-based application server Application Server, have been tested with the default java OpenJDK installed with Ubuntu 10.04 LTS "Lucid Lynx". So it's necessary to install the Closed-Source Oracle/Sun Java6 JDKJava Development Kit. There are various ways to do this, this document describes the approach from a gnome Terminal Window.

 sudo add-apt-repository “deb http://archive.canonical.com/ lucid partner”
 sudo apt-get update 
 sudo apt-get install sun-java6-jre sun-java6-plugin sun-java6-jdk

And remove OpenJdk just in case of clashes

  sudo apt-get remove openjdk-6-jre icedtea6-plugin openjdk-6-jre-headless icedtea-6-jre-cacao

Installation on Windows

Download the latest version of the Java Developer Kit (from now on called "JDKJava Development Kit") (alternative names, Java SE) from the Oracle Download Site and install to for example under c:\dev. Note that the download runs through twice. Once to install the JDKJava Development Kit, once to install the Java Runtime Environment ("JREJava Runtime Environment"). Note that Escidoc Core-Services and the JBossOpen source Java EE-based application server 4.2.x Application Server require the Java Developer Kit. A Java Runtime is not sufficient.

Here are some screenshots of this (use of highlighting indicates that default options were changed) :

Alt text
#1 Choice of Download
Alt text
#2 Location of JDKJava Development Kit
Alt text
#3 JDKJava Development Kit OPtions to install
Alt text
#4 location of JREJava Runtime Environment
Alt text
#5 Options


Please note that the registration of the product at Oracle is not in fact necessary, it works without registration too.

Verification of JDKJava Development Kit Installation

Open a command window / shell and verify that the following command returns a valid java version

 java -version

Installation of PostgreSQL 8.3

Installation on Linux

The exact syntax varies depending on Linux Distribution. In the case of Ubuntu 10_04 LTS (Lucid Lynx) the following installs and creates the PostgreSQL Server, clients, and graphical clients, and creates the initial database.

 user@hostname:~$ sudo apt-get install postgresql pgadmin3 postgresql-contrib

The Ubuntu Community Documentation gives further configuration help. At an absolute minimum, you will need to set the database password of the postgres DB-User to a known value for the later installation steps

Installation on Windows

The "Postgres Plus" 8.3.15.1 Download from Enterprisedb.com contains a good graphical installer. Pubman is not yet tested with the newer Version PostgreSQL 9.0. The 8.4.x Installer at the site also works, but the subsequent installation of ESciDocEnhanced Scientific Documentation 1.2.x makes changes to database settings that fail to work with the 8.4.x default setup. So Use of the 8.3 installer is recommended.

Notes on the following screenshots. Postgres uses both an OSOperating System Userid such as (Machinename)\postgres on windows and a DB-internal userid postgres. Confusingly, both are called "postgres". Only the OSOperating System postgres Userid can actually create the initial database. The database Postgres Userid is less needed in the default installation and can normally be ignored, but amongst other things functions as the database owner of the initial PostgreSQL Database catalog. You only get the option to set the OSOperating System-User password in the installation procedure described here, and there is no need to normally set the database-userid.

On some Windows machines, the graphical creation of the initial postgres database under the OSOperating System-Userid will fail unless the windows service "Secondary Login" is running. If necessary, start it via Windows Control Panel / Administration / Services.

Alt text
#1 Select Installation Directory
Alt text
#2 Select Database Directory
Alt text
#3 Leave Portnumber of DatabaseServer at default
Alt text
#4 Set the OSOperating System-Userid "postgres" password. Take care to remember this password, which is needed several times later in the installation.
Alt text
#5 Set the Locale of the DB to default
Alt text
#6 Do not run the "Stackbuilder" utility to install extra Posgres components

Verification of PostgreSQL Installation

On both Windows and Linux, the graphical query and managementclient pgAdmin III is now installed. You can use this to connect via the postgres DB-User and the password you set for this. Therefore click on menu "tools" and than "Connect". A server connection will be started. You will see a range of example and catalog databases installed.

Caution: Use of SQLStructured Query Language from PGAdmin III with the superuser account postgres to change either catalog or Escidoc or Pubman data will work, and that is very bad news. Because doing this will leave the data on the Postgresql Server in an inconsistent state, and is likely to lead to a necessity to reinstall the whole product stack or at minimum recreate the initial postgres database and reload all data from backup. Both EScidoc and Pubman are designed to maintain their own data consistency, and rely on that data being consistent. PostgreSQL utilities like this are merely used for administrative purposes (Database backup, restore, or in this case checking that the installation worked correctly). Changing data via these utilities is a very, very bad idea.

Alt text
the connection properties to connect to the catalog
Alt text
The catalog tables under pg_catalog expanded

Installation of ESciDocEnhanced Scientific Documentation Core-Services 1.2.x (on either Linux or on Windows)

Once you have downloaded the graphical install for ESciDocEnhanced Scientific Documentation Core-Services it can be run by opening a command-shell (CMD.EXE for windows), changing to the download directory and running

 java -jar ./escidoc-core-1.2.2-install.jar

(or .\escidoc-core-1.2.2-install.jar on windows) Since its a java program, it runs identically on both windows and unix, so there is no need for platform-specific screenshots. Please remember to start the PostgreSQL database server before installation.

The installation creates a total of 5 new users - make sure to remember the passwords - and some of the questions have far-reaching implications. In particular:

  • consider carefully before changing the default answer "localhost" to question #2, "Enter Hostname". If you simply want to create a test Pubman Server that only you will use, the default is almost certainly the right choice. However, the server will then only be reachable from the local machine. If you have a need to access the server remotely then by all means change the hostname to the DNSDomain Name System Hostname of the machine. But the server is then reachable for other users too, is therefore less secure, and its configuration defaults are not suitable for more than single-user operation. The screenshots further on in this article assume the server is running on localhost. If you change this here, you will need to change all later occurences of the "server-URLUniform Resource Locator" from http://localhost:8080 to http://yourhostname:8080
  • Changing the default installation directories on the other hand is a strong recommendation. Both on Unix and on Windows the defaults have long Directory Names and in some cases embedded blanks, that can cause lots of problems in delivered scripts.
Alt text
#1 Accept Opensource ESciDocEnhanced Scientific Documentation License
Alt text
#2 Select hostname of server. See note above
Alt text
#3 Accept defaults for DB Connection
Alt text
#4 ESciDocEnhanced Scientific Documentation Database Owner New userid
Alt text
#5 Existing PostgreSQL Superuser password from PG install
Alt text
#6 FedoraFlexible Extensible Digital Object Repository Architecture Repository Superuser New userid
Alt text
#7 Select Installation Directory
Alt text
#8 Leave installed components at default
Alt text
#9 ESciDocEnhanced Scientific Documentation Superuser New userid
Alt text
#10 ESciDocEnhanced Scientific Documentation Readonly User New userid
Alt text
#11 ESciDocEnhanced Scientific Documentation Depositor User New userid similar

Verification of ESciDocEnhanced Scientific Documentation Core-Services Installation

The steps for verification are described well in the readme.html file in the installation root directory. Essentially

  1. Open a Command Window / Shell Window. (For Windows, type cmd and hit return in the search box).
  2. Move to the ./jboss/bin directory ( .\jboss\bin for windows) und the Installation Directory. For example, if # you have installed in c:\pubman type cd \pubman\jboss\bin in the command window.
  3. run the run.sh (linux) or run.bat (windows) file by typing run run.bat into the command window.

Caution You may need to repeat this step: This step starts the JBossOpen source Java EE-based application server Server, which takes several minutes. The server will stop automatically when one of the following occurs.

  • You hit CTRL-C in the Command Window where the server is running
  • You close the command window where the server is running
  • You turn off the computer.

So for example if you're installing over several days, this step must be repeated.

Step 1. Verification that the JBossOpen source Java EE-based application server Application Server starts successfully

The server has started successfully when the following message (with varying timestamp) has appeared.


 14:35:14,438 INFO  [Server] JBossOpen source Java EE-based application server (MX MicroKernel) [4.2.3.GA (build: SVNTag=JBossOpen source Java EE-based application server_4_2_3_GA date=200807181417)] Started in 1m:6s:827ms

Then log on to the server with the Escidoc Superuser (sysadmin) in a browser on the following URLUniform Resource Locator

 http://localhost:8080/

If you changed the hostname of the server in the installation setup step #2 above, then replace localhost with your servername and potentially the domain name. For example, if you had installed on myhostname and you are running in a TCP/IPInternet Protocol Domain called yourdomain.org then one of the following URLs should work:

 http://myhostname:8080/
 http://myhostname.yourdomain.org:8080/

Step 2. Verification that that the Escidoc Datastores have initialised successfully

Verify that the database has initialised with PGAdmin III. You should see three new databases. escidoc-core (owner: escidoc); fedora3 (owner:fedoraAdmin) and riTriples(owner: fedoraAdmin)

Installation of Pubman 6.2.8 (on both Linux and Windows)

As mentioned above, the installation artefacts on the Pubman project installation page are up-to-date and valid for Release 6.2.8.

You should download the graphical installer. The graphical installer is useful in that it gives a description of many parameters that may be configured in a PubManPublication Management installation. All these parameters are taken from the installing user by the program and added to the pubman.properties file.

Note that for a first installation, we don't recommend changing many of them. Just notice that the appearance and functionality of Pubman is highly configurable, and perhaps make a note of interesting parameters for later use.

The installation of Pubman requires a running Escidoc Core-Services, so leave the server from the previous step running. On both Windows and Linux the java installer, once downloaded, can be run with the following command from the Downloads Directory:

 java -jar pubman_installer-standard.jar
Alt text
#1 Accept Opensource Pubman License
Alt text
#2 Deselect the Application Server for installation
Alt text
#3 Enter the Sysadmin Password, change Server hostname if necessary
Alt text
#4 Reenter the "Server-URLUniform Resource Locator", changing Server hostname if necessary. The question is asked twice to allow users to run PubManPublication Management on a different Server than ESciDocEnhanced Scientific Documentation Core-Services. We are not using this possibility in this case
Alt text
#5 For now, enter dummy information in all fields
Alt text
#6 Enter the postgres Userid and password to create the Cone Tables in the Database
Alt text
#7 Leave these at default
Alt text
#8 enter the initial password for the to-be-created default PubManPublication Management Userids pubman_depositor and pubman_moderator
Alt text
#9 Leave these at default
Alt text
#10 Leave these at default
Alt text
#11 Leave these at default
Alt text
#12 Leave these at default
Alt text
#13 Leave these at default
Alt text
#14 Enter the install directory for Escido
Alt text
#15 The summary of installation results. If successful, as here, then pressing next to continue and write the changed files to the disk


When run with these settings the following actions take place

  1. A valid pubman.properties will be written to the Escidoc Installation Directory under ./jboss/server/default/conf
  2. The Pubman EAREnterprise Archive File Formate and two license files will be written to the Escidoc Installation Directory unter ./jboss/server/default/deploy - the JBossOpen source Java EE-based application server Software will automatically detect these and initialise PubManPublication Management correctly.

Verification of Pubman 6.2.8

It should not be necessary to restart the JBossOpen source Java EE-based application server Server after the installation of the PubManPublication Management application - but this may be done if desired.

Test the PubManPublication Management application by accessing the following URLUniform Resource Locator from the Browser:

 http://localhost:8080/pubman

If you used a different hostname in steps 3 and 4 of the above PubManPublication Management installation, because you wished to install PubManPublication Management on a Server machine, replace "localhost" with the server name now.

First steps in using PubManPublication Management

The "initial dataset load" in the previous step (PubManPublication Management) installation has created the basic skeleton of technical Metadata to allow you to work with and learn PubManPublication Management. This initial skeleton consists of

  • Two defaults Userids:

pubman_depositor and pubman_moderator. The first deposits objects to be archived into PubManPublication Management, the second edits, validates, and "releases" the objects for indexing and automated cataloguing. You set the initial password for these during the PubManPublication Management installation step #8 above.

  • Two default Organisational Units

Default Pubman Organisation and External Organisation with which you can produce a basic model of the "Visibility" of the archived objects.

  • A default Context

In other words, PubManPublication Management is now ready to use.

However, if you wish to do the following tasks:

  • Create an Organisational Unit for your own organisation
  • Create your own Userids, or change passwords of existing Userids
  • Create your own Context

Then this requires an administration component. Currently - for existing PubManPublication Management customers - (for PubManPublication Management R.628, ESciDocEnhanced Scientific Documentation Core-Services R.122) these tasks are done via an internal component ESciDocAdmin. These data tend to be static, after all. The installation and configuration of this ESciDocAdmin component would approximately double or perhaps triple the length of time to install PubManPublication Management standalone as described, so this is currently not being documented here

As a note for the future. The internal ESciDocAdmin component that is used for these tasks is being replaced by extensions to the ESciDocEnhanced Scientific Documentation Core-Services Administration Console. These functions exist in the ESciDocEnhanced Scientific Documentation Core-Services Administration Console from Version 1.3.1, and we currently (September 2011) plan to move to ESciDocEnhanced Scientific Documentation Core Services 1.31 in the next pubman release.

Troubleshooting the Installation

Please register for the ESciDoc Developer mailing list and after registration ask any questions about troubleshooting on the list. We will gather any frequently asked questions together here.

Next Steps

(Windows only) Setup Pubman to run as a Windows Service

If you wish to set up the Pubman Service to run as a service under windows (for example to run automatically) then this is possible, but quite complicated. Here are the step-by-step instructions.

  1. Verify that everything is working properly when starting the JBossOpen source Java EE-based application server Application server (in the above steps) via the run.bat script in the jboss\bin directory from a command window. If it isn't working when run from run.bat, it cannot work from a windows service.
  2. Download the JBoss Native Extension for Windows Download. If you are running on 32-Bit Windows then you will need the "Win32" download link.
  3. extract the bin subdirectory of the zip archive to the jboss\bin directory under the pubman installation. So in addition to the run.bat in the jboss\bin directory you will have services.bat and several windows .exe files, that interface with service management and then behind the scenes call the run.bat file
  4. Open a new windows Command window as an Administrator. To do this,
    1. Open the windows start button and type cmd.exe into the search window
    2. Hover the mouse over the cmd.exe link in the start button window and right-click to get the context menu
    3. Select "Run as administrator". You will be prompted for a password.
  5. change to the jboss\bin directory under the pubman installation directory and type
 service install

Check that the service has been created in the way you normally would do so. From Control Panel / Administration/Services, via the NET START command from a command window, whatever you wish.

You can start the Service as normal too. If you wish to start the PubManPublication Management Server automatically, change the start type of Service "JBossOpen source Java EE-based application server Application Server 5.0" to "automatic" from "manual" in Control Panel / Administration / Services.

Caution: From the point of view of Windows Service Management, the Service will always start correctly in a few seconds. If however there is an error in configuration that means that Java cannot successfully start the server, you may have a running Service, but no running server behind the scenes. This is the reason for only making the windows service as the final change to the installation, once you know everything is working The simplest way to test for this is to wait 2-3 minutes and try to access PubManPublication Management from the browser.

A Slightly more complicated way is to to monitor the content of the file server.log under the jboss\server\default\log directory. The server has fully started when you see a message of this form.

[org.jboss.system.server.Server] JBossOpen source Java EE-based application server (MX MicroKernel) [4.2.3.GA (build:SVNTag=JBossOpen source Java EE-based application server_4_2_3_GA date=200807181417)] Started in 2m 12s:791ms

This message may look familiar to you. The server.log contains the same information that is printed as output in the Command Window during the ESciDocEnhanced Scientific Documentation Core-Service installation above. In the Case of a Service, there is no output in a Window, but the server.log file will help find errors.

However since checking cryptic log-file messages to find out whether PubManPublication Management has finished initialising is not exactly User-Friendly, you may want to automate this with the script below

A simple monitoring script

The following script is written for Windows and doesn't use "exotic" Batch Syntax so should be fine on all flavours of Windows from XP onwards. The approach is valid on Linux or Unix too, although there are syntactical differences - The twiddle utility on Unix is invoked with twiddle.sh for example.

The Order of the tests is significant as they trace the progress of initialization. When all tests run successfully, PubManPublication Management is available for use.

@echo off
rem set JAVA_HOME to the directory where the JDK (not the JRE) has been installed.
rem set PUBMAN_HOME to the directory where Pubman/ESciDoc-Core-Services has been installed
rem
set JAVA_HOME=c:\dev\jdk16_24
set PUBMAN_HOME=c:\dev\pubman628
set PATH=%PATH%;%JAVA_HOME%\bin;%PUBMAN_HOME%\jboss\bin
rem
rem test whether there is a local service running the JBoss application server. 
rem This test will only work on a service, not a command window
rem
net start |find /i  "jboss" >nul
if errorlevel 1 goto nojbossfound
echo EsciDoc / PuMman Process found
rem
rem check if escidoc-core has finished deploying using the jboss "twiddle" utility
rem
twiddle query "jboss.web.deployment:*"|find "escidoc-core.war" >nul
if errorlevel 1 goto noescidoccore
echo ESciDoc Core-Services is deployed
rem
rem check if pubman has finished deploying using the jboss "twiddle" utility
rem
twiddle query "jboss.web.deployment:*"|find "pubman_presentation" >nul
if errorlevel 1 goto nopubman
echo Pubman is deployed
rem
rem test whether the JBoss Application server is listening for connections - required for
rem logging in from a browser. Change the String "8080" below if you have set the server to run on a different port
rem
netstat -a |find "8080" >nul
if errorlevel 1 goto nolistenerfound
echo ESciDoc / PubMan Server is listening for connections
goto exit

:nojbossfound
echo no jboss found ... exiting
goto exit

:noescidoccore
echo escidoc core has not (yet) deployed ... exiting
goto exit

:nopubman
echo Pubman has not (yet) deployed ... exiting
goto exit

:nolistenerfound
echo Escidoc / PUbman Server is running, but not listening for connections ... exiting
goto exit

:exit

Using PubManPublication Management

Click the Help link in Pubman to get quite detailed online help. Here is a link to task-oriented Video tutorials.

Good Luck exploring PubManPublication Management, and please don't hesitate to use the mailing list forums.