Server Setup Guide - Table of Contents

  1. System Requirements
  2. Downloading the required files
  3. Setting up environment variables
  4. Configuration
  5. Building From Source
  6. Deployment to Tomcat
  7. Bootstrapping the Database
  8. Testing your own installation

System Requirements

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.

Downloading the Required Files

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

The directory 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.

The source package includes all other dependecies (libraries) that are required, except for libraries provided by the JWSDP and the application server itself.

Binary packages are not available currently. However, the source distribution comes ready to be built and deployed.

Alternatively, you may check out the latest source tree from the CVS repository CVS checkoutprovides you with latest bug fixes and features. However latest CVS bits may be less stable than a packaged release. You may use the following command:

cvs -z3 -d:pserver:anonymous@ebxmlrr.cvs.sourceforge.net:/cvsroot/ebxmlrr co -P omar

Yet another option is to use NetBeans to get the files from CVS for you. Check here how to configure it.

Setting up environment variables

Variable
Description
Unix Example
Windows Example
JAVA_HOME The home directory for JDK installation.  /usr/java/j2sdk1.4.2_08 c:\j2sdk1.4.0_08

Make sure the Java runtime environment executable (e.g. <JAVA_HOME>/jre/bin/java.exe for Windows) and Java compiler executable (e.g. <JAVA_HOME>/bin/javac.exe for Windows) are in the environment variable PATH.

Configuration

There are several configuration properties within several configuration files for omar. They are described in details here. Each property file is self documenting and describes each property within it.

While there is a large number of configuration properties, fortunately the defaults suffice in most cases. Here are some properties you might want to change:

Property
Configuration File
Description
Database configuration
  • omar.persistence.rdb.databaseURL
  • omar.persistence.rdb.databaseDriver
  • omar.persistence.rdb.databaseUser
  • omar.persistence.rdb.databaseUserPassword
omar.propertiesThe properties are used to connect to the database via JDBC. The default configuration is for Derby database, you don't need to change it if you want to use it. Property sets for other databases are available in build.properties.

** This porperties will be set from build.properties at build time.
Registry Administrator Role Assignment:
  • omar.security.authorization.registryAdministrators
omar.propertiesConfigures the set of users that should be assigned the role of RegistryAdministrator and its associated "superuser" like privileges. This is useful if you are a registry administrator and want to add addition registry administrator.
Configuring a test user:

  • jaxr-ebxml.security.alias
  • jaxr-ebxml.security.keypass
  • jaxr-ebxml.security.guestPrincipalName

jaxr-ebxml.propertiesThe properties used to configure a user that is used by the automated regression tests. This is necessary only if you run automated regression tests. You should run regression tests if you are making code changes and submitting a patch to the project team for a bug fix or RFE.

Configuring Build Properties

  1. Make a copy of <omar.basedir>/build.properties.template and rename it to build.properties. Keep this in the same directory. Note that this file is to control the deployment parameters, but since some parameters are shared (i.e., database) by runtime they get copied to omar.properties and other runtime configuration files.
  2. Open build.properties with a text editor and edit following properties:
Property
Configuration File
Description
JWSDP configuration
  • jwsdp.home
build.propertiesJWSDP home directory (e.g. /opt/jwsdp-1.6).
Tomcat (servlet container) configuration
  • catalina.home
build.propertiesTomcat's home directory. In Windows environment, Tomcat path may include white spaces (e.g. c:\\Program Files\\Apache Tomcat 5.0.19\\) and things will still work if you leave spaces. Note that you MUST use either '/' or '\\' instead of '\'.
Database configuration
  • jdbcDriver
  • jdbURL
  • jdbUsername
  • jdbPassword
  • jdbcClassName
build.properties

The properties are used to connect to the database via JDBC. The default configuration is for Derby database, you don't need to change it if you want to use it. Example property sets for other databases are available in build.properties.

There are a few JDBC drivers in misc/lib directory (for source distribution or checkout from CVS), or you can get an updated copy of the driver for your database. You may need to consult the documentation of your database to find out the syntax of the URL.

Search the FAQ for database specific entries.

Building From Source

You need to build the source distribution in order to deploy OMAR. It can also be built directly from the CVS repository. Apache ant is used as scripting language and these are the steps to use it:

  1. change current directory to <omar.basedir>.
  2. type "build compile". If you are using Unix/Linux and Korn shell is available, type "./build.sh" instead. Also on Unix platforms you may need to make build.sh executable by typing "chmod 755 build.sh".
  3. type "build jars" and you'll get the compiled binaries packed in jar files, in <omar.basedir>/build/lib.
  4. type "build war" and you'll get a war file built to <omar.basedir>/build.

Deployment to Tomcat

  1. Shutdown Tomcat first.
  2. Type "build deploy" in <omar.basedir>. It will create a Web application "omar" in Tomcat with all the required files.
  3. The databasec connection properties in build.properties is irrelevant after deployment to Tomcat. In case you need to change something, either change build.properties and re-deploy or change the omar.xml deployment descriptor in <TOMCAT_HOME>/conf/Catalina/localhost
  4. If you want to enable debugging output, one option is to set the environment variable CATALINA_OPTS to -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog . You can set the variable e.g. in the Tomcat startup script. See  SimpleLog and  Commons Logging for more options that you can configure.
  5. 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.
  6. Restart Tomcat.

Bootstrapping the database

Configuring database connection properties

If you just want to try it out, you can use OMAR with preconfigured Derby database. For a production environment, you are recommended to use PostgreSQL version 7.1 or above as the database. There are (old) instructions on this page to setup PostgreSQL on Windows, although newer PostgreSQL should install in windows without any extra complications. Setup a database with name "omar_registry".

Open the text file <omar.basedir>/build.properties, which is created in section 6. Note that build.properties only takes effect at installation time (the runtime parameters are specified by omar.properties, omar-common.properties, repository.datasource.cfg and omar.xml deployment description in the AppServer). You should be able to find the following properties:

jdbcDriver

dbURL

dbUsername

dbPassword

jdbcClassName

Change them accordingly. The meaning of the properties in the above lines are as follows:

 

Property
Description
Example
jdbcDriver Path of the JDBC driver jar PostgreSQL: 

jdbcDriver=${build.home}/lib/postgresql.jar 

Oracle: 

jdbcDriver=C:/oracle/ora92/jdbc/lib/classes12.jar

dbURL URL for connecting the database via JDBC PostgreSQL: 

dbURL=jdbc:postgresql://localhost:5432/registry 

Oracle: 

dbURL=jdbc:oracle:thin:@localhost:1521:test

dbUsername Username for connecting the database dbUsername=omar
dbPassword Password for connecting the database dbPassword=omar
jdbcClassName The fully qualified name of the JDBC driver PostgreSQL: 

jdbcClassName=org.postgresql.Driver 

Oracle: 

jdbcClassName=oracle.jdbc.driver.OracleDriver

Loading the sample data

  1. Change current directory to <omar.basedir>.
  2. Make sure that tomcat has been restarted.
  3. Type "build genKeys" to generate private keys for signing the requests. It will also generate certificates for authenticating the predefined users.
  4. Make sure omar.persistence.rdb.ExternalLinkDAO.checkURLs and omar.persistence.rdb.ServiceBindingDAO.checkURLs are set to false (default) because the demo data may contain some invalid URLs. According to the specifications, the validity of the URLs should be checked. After going through all the setup procedures, you should set them to true. (//TODO: Fix invalid URLs in demoDB).
  5. Type "build cleandb" to clean the database. It will delete all the tables for omar in the database.
  6. Type "build createDemoDB". The predefined users, standard classification schemes (e.g. ISO 3166) and some other demo data will be loaded into the database after running it.

Testing your own installation

Now we are going to submit a request to your own installation.

In <omar.basedir>/build.xml, we can see a target "test":

If the registry server is installed in somewhere other than localhost or port, replace url=http://localhost:8080/omar/registry/soap accordingly. It will send a AdhocQueryRequest to the server. The request file, SQLQuery_1.xml, is located in <omar.basedir>/misc/samples.

Type "build test". Open <omar.basedir>/response.xml. It is the response from your registry server. You can see the content of response.xml similar to this:

If your installation is successful, you can see that the responses encloses a <AdhocQueryResponse> element with status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success", which is the code for status of "Success".

Finally you should subscribe to the mailing list ebxmlrr-tech@lists.sourceforge.net by filling the form at http://lists.sourceforge.net/lists/listinfo/ebxmlrr-tech . Any update will be sent to this mailing list.

Feedback

If you have any comments or queries, please feel free to send an email to ebxmlrr-tech@lists.sourceforge.net