Install

From Omar Wiki

Jump to: navigation, search

Contents

[edit]

How To Ask for Help

It takes a lot of effort for a small dev team to help the user community with all their questions. This section provides the ettiquette for asking for help in the most productive manner for everyone involved.

  1. Follow suggestions at: http://www.catb.org/~esr/faqs/smart-questions.html
  2. First check the freebXML Registry FAQ to see if your problem is already addressed (also, FAQ in wiki, under construction).
  3. Next check the freebXML Registry Wiki for information you seek. Use the search field on the left side of any wiki page.
  4. Next check the freebXML Registry User's mailing list archives. Search the archives for your problem before posting to the list. Note that sometimes the archives are not available due to a temporary outage at SourceForge.
  5. Finally, post your problem to the freebXML Registry User's mailing list. You MUST subscribe to the list before you can post to it. When posting a problem be sure to include the following:
  • Choose a subject title for your post that will aid in seraching for the problem in future. The best titles will include a copy paste of the most relevant part of the error message you are getting or will include a brief summary of the problem you are seeing. Avoid subject title's like "Need urgent help".
  • The version of freebXML Registry software being used (or latest CVS bits)
  • Server side stack trace if any. Copy paste the most relevant portions.
  • Client side stack trace if any. Copy paste the most relevant portions.
  • Steps to reproduce the problem. Be clear and concise.

If every one follows above guidelines then the dev team will be able to help much more effectively.

[edit]

System Requirements

  • JDK 1.4.2 or above (only SDK/JRE is not enough). JDK 5 or 6 is recommended over JDK 1.4. JDK 1.4 and JDK 6 require special instructions at the bottom of this page.
  • JWSDP 1.6 recommended, though JWSDP 1.5 can be used instead.
  • Tomcat 5.0.28 or more recent version. Other servlet engines may work, but have not tested. For instructions on how to configure Jetty follow this link.
  • A relational database that supports SQL-92 syntax. Derby and HSQLDB are included in the project distribution. Derby database, running in embedded mode, is the default and requires no special download or configuration steps in order to use it out-of-the-box. We have also tested the deployment to PostgreSQL 7.1 (How to setup PostgresSQL) and Oracle 9i.

Note: depending on your system, you might have to use the endorsed mechanism to overwrite the JVM JAXP/Xerces/Xalan libraries. Situations were that might be needed include JDK1.4.2 + JWSDP 1.6, or even older versions of JDK1.4.2 + JWSDP 1.5. In those cases, you need to copy JAXP libraries from JWSDP to <JDK_HOME>/jre/lib/endorsed. If the directory does not exist, you have to create it. Tomcat should also require the libs to be copied to <TOMCAT_HOME>/common/endorsed directory.

[edit]

Quick Start Guide

The purposes of this document is to give a minimal amount of steps to build ebXML RR and get it up and running. ebXML RR is a flexible product and as such can be build and deploy in a number of ways. This document does not have a goal to describe all possible ways to deploy ebXML RR. Instead it describes just one possible way to get it up and running using mostly the default configuration settings.

Note that that build.sh below needs to be replaced with build.bat on a windows system.

[edit]

Download and install Java Development Kit (JDK)

http://java.sun.com/j2se/1.5.0/download.jsp

  • Download and install JDK 5 (recommended). JDK 6 works great too. JDK 1.4.2 is usable but awith a few limitations such as inability to generate p12 files during user registration. JDK 1.4 also requires some special instructions to be followed.
  • Set JAVA_HOME environment variable to point to newly installed JVM. In Unix-based bash shell mode: 
 export JAVA_HOME=[path to JVM]
[edit]

Download and Install Tomcat

http://tomcat.apache.org/download-55.cgi#5.0.28

  • Install in ~/jakarta-tomcat-5.0.28. If different location then it will need to be specified in local.build.properties later using catalina.home property.
  • Remove all jars from {TOMCAT_HOME}/common/endorsed

The rest of the document refers to Tomcat installation location as {TOMCAT_HOME}

Notes:

[edit]

Set Environment Variables

On windows environment variables are set using instructions here. Unix syntax is used below:

  • Set JAVA_HOME environment variable to point to newly installed JVM. In Unix-based bash shell mode: 
 export JAVA_HOME=[path to JVM]
  • Set CATALINA_HOME to point to the location for Tomcat installation shared by multiple users. Note that this must match the catalina.home property in local.build.properties. 
 export CATALINA_HOME=~/jakarta-tomcat-5.0.28
  • Set CATALINA_BASE to point to the location for Tomcat installation for your specific user. Note that if you are the only user on the system you can set it to be same as CATALINA_HOME. Note that this must match the catalina.base property in local.build.properties. 
 export CATALINA_BASE=~/jakarta-tomcat-5.0.28
[edit]

Download and Install JWSDP 1.6

http://java.sun.com/webservices/downloads/1.6/index.html

Note that from time to time Sun's web site makes above link be unavailable or contain the wrong content. If that happens please download the following zip file and simply unzip in your home directory:

http://ebxmlrr.sourceforge.net/tmp/jwsdp-1.6.zip

  • Install in ~/jwsdp-1.6. If different location then it will need to be specified in local.build.properties later using jwsdp.home property.

If installing in Linux and the following error occurs: 

 "tail: cannot open `+xxx' for reading: No such file or directory"

where xxx is a number, then execute the installer like this: 

 _POSIX2_VERSION=199209 ./jwsdp-1_6-unix.sh

During installation:

  • Don't install web container
  • Choose typical installation
  • Don't put any jars in the endorse directory of JVM

The rest of the document refers to JWSDP installation location as {JWSDP_HOME}

[edit]

Download freebXML Registry Software

This section assumes you have already downloaded and installed the JDK, JWSDP and a web container such as Apache Tomcat as described in previous sections. Next you need to install the freebXML Registry software as described in this section. There are two ways (you need only one of these) to get freebXML Registry software:

  • Download the latest packaged release of freebXML Registry. This option is ideal if you want stability and do not mind living with known bugs and doing without newer features that may be available in latest CVS bits.
  • Checkout source code for freebXML Registry directly from CVS. This option is ideal if you want the latest features and bug fixes and are willing to risk a small potential for instability. Use this option if you are in a experimental or development phase for your project.

The highest level directory named "omar" containing the extracted files will be called omar.basedir for the rest of this document. 

 IMPORTANT: do not confuse omar.home and omar.basedir.
  • omar.basedir (or OMAR_BASEDIR): build time, OMAR project source directory.
  • omar.home (or OMAR_HOME): build and runtime, OMAR configurations and data directory.


[edit]

Download Latest Packaged Release

https://sourceforge.net/project/showfiles.php?group_id=37074

To obtain the latest stable releases you need to download source packages from the download section:

  • Windows Platform: Download file omar-<release_version>-src.zip and extract using a zip utility (like WinZip).
  • Unix Platform: Download file omar-<release_version>-src.tar.gz and extract using tar -xzf omar-<release_version>-src.tar.gz
[edit]

Alternative: Checkout Source Code from CVS

Base instructions are here: 

 http://sourceforge.net/cvs/?group_id=37074

Note that for freebXML Registry team member the instructions in above link are different and require use of SSH rather than pserver method for cvs authentication.

  • Set CVSROOT environment variable 
export CVSROOT=:pserver:anonymous@ebxmlrr.cvs.sourceforge.net:/cvsroot/ebxmlrr
  • Login to project CVS server. When prompted for a password simply press Enter

Note that this step need to be done only once for each user on every workstation 

cvs login
  • Checkout Omar source code. This command will create omar subdirectory which will contain all of the source code 
cvs -z3 co -P omar
[edit]

Build freebXML Registry Software From Source Code

  • Change to omar directory (omar.basedir) 
 cd omar
  • Create local.build.properties using a text editor. Never ever change build.properties. It should only be changed by dev team in CVS to account for changes in code. For windows platform see sepcial instructions here. 
#Note that if you use any property variable in this file then they MUST be dfeined in this file
#even if they are already defined in build.properties and not being overridden. Typically the following SHOULD be defined:
dist.version=3.0-final1
omar.name=omar
omar.home=${user.home}/${omar.name}/${dist.version}
omar.home.template=$user.home/${omar.name}/${dist.version}
omar.container.url=http://localhost:8080
  • Override the following properties in local.build.properties if your settings are different from the default values in build.properties 
catalina.home={TOMCAT_HOME} #Only change if different from default of ~/jakarta-tomcat-5.0.28
jwsdp.home={JWSDP_HOME} #Only change if different from default of ~/jwsdp-1.6
  • Compile the code. 
./build.sh compile

Note: If you are using windows platform use ".\build" instead of "./build.sh", type "./build.sh" instead. 
Also on Unix platforms you may need to make build.sh executable by typing "chmod 755 ./build.sh"

If compile fails, double check jwsdp.home location since many required libraries are fetched from there.

[edit]

Generate Server Keystore

The server keystore contains keys for registered users. This steps creates the server keystore and also stores the keys for certain pre-defined users. 

./build.sh genKeys
[edit]

Deploy freebXML Registry Software to Web Container

[edit]

Deploy to Tomcat Web Container

  • Make sure Tomcat is not running. 
 ./build.sh stop.tomcat
  • Deploy to tomcat 
 ./build.sh deploy

Note: If you are using a tomcat version other than 5.0.28 then there may be additional steps.

  • Configure HTTPS support for Tomcat, with RegistryOperator as trusted certificate authority. This step is required for user registration and publishing through Web UI. See Enabling HTTPS in Tomcat.
[edit]

Alternative: Deploy to Other Web Container Than Tomcat

This step is only needed if you are using a container other than tomcat. Create the war file containing the freebXML Registry server as follows: 

./build.sh jars
./build.sh war

Next deploy the war using container specific instructions.

[edit]

Starting and Stopping the Server

Many subsequent steps require starting or stopping the server. This is the same as starting or stopping the web container. The following steps assume the web container is Tomcat (default). These steps will be different if you use a container other than tomcat. You do not need to perform the following steps until subsequent instructions require it. 

./build.sh start.tomcat #Start the server
./build.sh jpda.tomcat #Start the server so it can be debugged using JPDA debugger (e.g. using NetBeans)
./build.sh stop.tomcat #Stop the server
./build.sh bounce.tomcat #Stop and restart the server
[edit]

Create Database for freebXML Registry Server

The following steps assume default settings in build.properties for Derby database running in embedded mode. For other databases or modes you will need to override the default properties by setting properties in local.build.properties. The database configuration properties are described by comments within build.properties file. Note that you should only provide the database specific properties for your chosen database in local.build.properties. 

 Caution: If you override properties or make changes to local.build.properties then be sure to do a clean build: ./build.sh clean deploy stop.tomcat start.tomcat

This step requires that the server is not running (stopped) if localCall=true. This is the default in build.properties. If you have set localCall=false in local.build.properties then the server MUST be running (started) and primeCacheEvent SHOULD be set to onFirstUse

  • Remove any previous database. Make sure you backup any existing database if you think you may need it. 
 ./build.sh cleandb
  • Create database schema and demo database content (if localCall was set to false, then start tomcat first) 
./build.sh createDemoDB
[edit]

Create Test User

These steps are needed if you wish to run our junit test suite as the tests require a pre-registered test user to be configured.

  • Start the server if not already started
  • Create TestUser that is used by unit tests. The web container (e.g. tomcat) must be running for this step. 
./build.sh createTestUser

If key for testuser already exists, then run the following command:
./build.sh loadTestUser
[edit]

Test installation

  • Start server if not already started
  • Start Java UI 
./build.sh run.browser

Search result should be seen in the “Search Result” pannel.

Similar test can be done using Web based UI by pointing a browser to

http://localhost:8080/omar/registry/thin/WelcomePage.jsp

[edit]

Using JDK 6

This section describes some special instructions when using JDK 1.6 with freebXML Registry. JDK 1.6 ships with newer versions of XWSS jars used for signing and verifying SOAP messages in OMAR 3. Due to backward compatibility issues in XWSS versions we need to follow some special instructions that make OMAR 3 use the correct version of XWSS adapter classes and libraries. The following instructions have not been tested yet and may not be perfect.

  • Download a local copy of
  • Edit user-build.properties and add the following settings to override defaults in build.properties: 
soapSecurityProviderDir=org/freebxml/omar/common/security/xwssec20FCS
libs.xws-security.jar=<path to downloaded xws-security.jar >
  • Rebuild omar from the begining includimg building the database
[edit]

Using JDK 1.4.X

This section describes some special instructions when using JDK 1.4.X with freebXML Registry.

  • Copy the JAXP related jars from JWSDP 1.6 to the $JAVA_HOME/jre/lib/endorsed directrory as follows: 
 #Note you may need to be root in order to do following command
 cp ~/jwsdp-1.6/jaxp/lib/jaxp-api.jar $JAVA_HOME/jre/lib/endorsed
 cp ~/jwsdp-1.6/jaxp/lib/endorsed/*.jar $JAVA_HOME/jre/lib/endorsed
  • Copy the JAXP related jars from JWSDP 1.6 to the tomcat endorsed dir if suing tomcat 
 cp ~/jwsdp-1.6/jaxp/lib/jaxp-api.jar $CATALINIA_HOME/common/endorsed/
 cp ~/jwsdp-1.6/jaxp/lib/endorsed/*.jar $CATALINIA_HOME/common/endorsed/
[edit]

Using JWSDP 1.5

This section describes how to use JWSDP 1.5 instead of JWSDP 1.6 (default) libraries with freebXML Registry.

  • Add the following properties into local.build.properties 
#Following props are needed in local.build.properties nearly always
dist.version=3.0-final1
omar.name=omar
omar.home=${user.home}/${omar.name}/${dist.version}
omar.home.template=$user.home/${omar.name}/${dist.version}
#
#Following props are needed in local.build.properties if you wish to use JWSDP 1.5
#
# Points to the installation of JWSDP 1.5 which must (*) be downloaded and installed
# separately from http://java.sun.com/webservices/downloads/webservicespack.html
# Alternatively, you can use JWSDP 1.6 which is teh default and does not require 
# any property overrides in local.build.properties
#
jwsdp.home=${user.home}/jwsdp-1.5
#
#
# For JWSDP 1.5, use the security jars from misc/lib instead.
#
libs.xws-security.jar=${omar.basedir}/misc/lib/xws-security.jar
libs.xmlsec.jar=${omar.basedir}/misc/lib/xmlsec.jar
#
# SOAP Security Provider specific properties. Needs to be coordinated with jwsdp.home
# for jwsdp-1.5 use: org/freebxml/omar/common/security/xwssec10
# for JES4 use: org/freebxml/omar/common/security/xwssec11
# for jwsdp-1.6 use: org/freebxml/omar/common/security/xwssec20
# for jwsdp-2.0 use: org/freebxml/omar/common/security/xwssec20FCS
#
soapSecurityProviderDir=org/freebxml/omar/common/security/xwssec10
  • Perform the following ant targets: clean, compile and deploy to rebuild the software using JWSDP 1.5 
./build.sh clean compile deploy
  • Bounce the server 
 ./build.sh bounce.tomcat
Retrieved from "http://ebxmlrr.sourceforge.net/wiki/index.php/Install"
Personal tools