User:Bourke/Sandbox

Richard Bourke Sandbox

Pubman 628 Local Installation Setup

Purpose of Document This Document is written to give fuller information on the steps to set up a locally running Pubman 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 reasonable PC skills, who wish to see for themselves what Pubman and EsciDoc may offer for benefits, and look behind the scenes at the infrastructure involved.

Scope and dependencies of this Document This Document is written in July/August 2011 and is based on the then current tested Pubman Production and Demonstration Environment. Pubman Release: 6.2.8 EsciDoc Core-Services: 1.2 Oracle Java 6 SDK: 1.6_24 JBoss Application Server: 4.2.2 Postgres: 8.4.8

Limits of this Document Time constraints prevent the documentation of a installation instructions for all tested Pubman and Escidoc Environment. Specifically, this document only describes installation of Pubman 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 (Postgres 8.4).

Current Documentation

Here is the at time of writing current documentation on Pubman and Escidoc standalone installation, upon which this document attempts to expand.

Pubman Download Page retrieved July 2011

which makes reference to the EsciDoc Core-Services Installation page. Regrettably at time of writing the dependencies listed on the first page are out of date. Pubman 6.2.8 has a prerequisite of ESciDoc Core-Services Release 1.2, not Release 1.1.3 / 1.1.4 as stated there. The downloads listed on the page are, however, correct and up to date.

Installation of Oracle/Sun Java 6 JDK

Installation on Windows

Download the latest version of the JDK (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 Java Developer Kit, once to install the Java Runtime Environment.

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

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#1 Choice of Download

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#2 Location of JDK

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#3 JDK OPtions to install

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#4 location of JRE

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#5 Options

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

Verification of JDK Installation

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

 java -version

Installation of PostgreSQL 8.4

Installation on Linux

The exact syntax varies depending on Linux Distribution. In the case of Ubuntu 10_04 (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 tips. 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.x 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 ESciDoc 1.2.x makes changes to database settings that fail to work with the 8.4.x default setup. So Use of 8.3 is recommended.

Notes on the following screenshots. Postgres uses both an OS Userid (Machinename)\postgres on windows and a DB-internal userid postgres. Confusingly, both are called "postgres". Only the OS 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 OS-User password in the installation procedure described here, and there is no need to normally set the database-userid. Take care to remember this password, which is needed several times latest in the installation.

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

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#1 Select Installation Directory

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#2 Select Database Directory

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#3 Leave Portnumber of DatabaseServer at default

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#4 Set the OS-Userid "postgres" password

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#5 Set the Locale of the DB to default

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#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. you will see a range of example and catalog databases installed

Caution: Use of SQL from PGAdmin III with the superuser account postgres to change either catalog or Escidoc or Pubman data will work, and 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 integrity. 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.

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

the connection properties to connect to the catalog

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

The catalog tables under pg_catalog expanded

Installation of Escidoc Core-Services 1.2.x (on both Linux and Windows)

Once you have downloaded the graphical install for ESciDoc 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

Since its a java program, it runs identically on both windows and unix, so there is no need for platform-specific screenshots.

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 DNS 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.
• 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.

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#1 Accept Opensource Escidoc License

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#2 Select hostname of server. See note above

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#3 Accept defaults for DB Connection

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#4 Escidoc Database Owner New userid

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#5 Existing PostgreSQL Superuser password from PG install

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#6 Fedora Repository Superuser New userid

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#7 Select Installation Directory

Error creating thumbnail: /bin/bash: line 1: /usr/bin/convert: No such file or directory Error code: 127

#8 Leave installed components at default

File:Escidoc xxx.png

#1 Select Installation Directory

File:Escidoc xxx.png

#1 Select Installation Directory

File:Escidoc xxx.png

#1 Select Installation Directory

File:Escidoc xxx.png

#1 Select Installation Directory

Troubleshooting the Installation

missing pubman.properties in jboss/server/default/conf

Software Development Kit

Open source Java EE-based application server

Enhanced Scientific Documentation

Java Development Kit

Java Runtime Environment

Operating System

Structured Query Language

Domain Name System

Flexible Extensible Digital Object Repository Architecture

Enterprise Archive File Formate