Chapter 1: Getting Started

Table of Contents | Next Chapter >>

What is POMS?

POMS is a complete solution for running an efficient project office. It provides a multi-user environment for creating and managing projects. POMS can deliver substantial productivity gains in your projects by fully integrating a variety of tasks that you'd normally perform using multiple disparate software products that lack integration. These tasks include: POMS stores all its information in a central repository and provides user access to the information in a distributed computing environment. POMS gives you considerable flexibility in the way you deploy it in your environment, ranging from simple standalone to load-balanced four-tier client-server. In all cases (even when deployed over the Internet), POMS delivers exactly the same graphical user interface. This user interface is not browser-based, but rather is a superior native user interface, of the kind you're used to seeing on your desktop. The user interface is much more responsive and intuitive than browser-based interfaces.

Unique Architecture

POMS is a pure Java application. As such, it is platform independent.

The architecture of the application is unique, in that it utilizes a dynamic client that boots itself from the application server. The most important benefit of this architecture is ease of maintenance. Imagine that you have installed a POMS server and provided 100 users with POMS client to access the system. When a new release of POMS becomes available later on, and you wish to install it, all that you have to do is to install the new server software. None of the clients will require upgrading, because they will automatically upgrade themselves against the new server next time users login. This eliminates the burden of upgrading individual client installations -- a time-consuming and error-prone process that has frustrated users of competitor applications for decades!

Flexible Licensing

When you download POMS from our web site and install it, you can run it as freeware. This gives you the opportunity to evaluate the product functionality without buying a license. In freeware mode, however, the following restrictions apply: These restrictions are removed once you purchase a valid license.

For organizations that wish to evaluate the product without any restrictions, we offer a free 30-day evaluation license. You can request this by sending an email to sales@pragsoft.com. This offer is only available to organizations (such as companies, universities, government departments), but not private individuals.

POMS software licenses are floating: a multi-user license (of quantity n) allows up to n concurrent users to access the system. User n+1 is barred access until one of the connected users logs out of POMS.


Installing POMS

Before installing POMS, you need to decide your preferred deployment model. You have four deployment models to choose from. These are described in increasing order of sophistication.

Model 1: Standalone

This deployment model consists of a fat Client and a Database Server running on the same box. The advantage of this model is that it requires no networking. The disadvantage is that it can accommodate only one user.

Model 2: Two-tier Client-Server

This deployment model consists of:

This model is suitable for small-scale deployment over a LAN. Although simple, it lacks scalability (suitable for tens of concurrent users). Another limitation of this model is that it cannot support remote users via the Internet.

Model 3: Three-tier Client-Server

This deployment model consists of:

This model is suitable for up to a hundred concurrent users. More than one App Server can be deployed to provide automatic fail-over. The servers and clients can be deployed across a LAN or the Internet. Deployment over the Internet allows users to work from any remote location. Client and server side firewalls are optional; some organizations have them as a matter of policy for greater security. Use of a server-side firewall is transparent to POMS. Where a client-side firewall is used, POMS client can be configured to tunnel through it.

Model 4: Four-tier Client-Server

This deployment model consists of:

This model is similar to the previous model, except that it also contains Proxy Server(s) which play two important roles:

System requirements

Although POMS is Java based and platform independent, the current release has been packaged and tested for running on Windows operating system. A Linux installation will be offered in the near future.

The system requirements for various components of POMS are as follows.

Java Installation

J2SE JRE 1.4.2 (or higher) must be installed on every machine used for POMS deployment, including standalone, client, and servers machines. The only exception is the database server, which does not require Java installation.

If you intend to deploy a POMS server as a Windows Service, you must install the J2SE JDK instead of J2SE JRE on the server machine.

You can download the J2SE JRE and JDK installation executables from java.sun.com:

Database Installation

POMS uses the Firebird 1.5.2 open source database engine. This is a robust and efficient relational database system widely used throughout the world, and is free for commercial use. You can download Firebird from firebird.sourceforge.net. Firebird must be installed on the machine where you intend to keep your POMS database. Follow the installation instructions and configure Firebird to run as a Windows Service.

POMS Installation

You can download the POMS installation executable from www.pragsoft.com/poms. This installation program supports all deployment models described above.

During installation, you will be presented with the following screen.

You should tick the options relevant to the machine you're installing on:

Variations of the above are also possible. For example, you can event select all options and install everything on the same machine if you want to experiment with any or all of the four deployment models. Client and servers can be installed on the same machine for ease of experimentation.

Unless you've only selected the standalone option, the next installation screen asks you to enter the URL of your App/Proxy servers.

If you're installing a client, ask your system administrator for these URLs. The Proxy URL can be ignored if no proxy server is installed. Conversely, the App Server URL can be ignored if the server(s) have been setup to require everyone to go through the Proxy Server.

If you're installing a server, then you must enter the host name (or IP address) of the machine you're installing on, followed by colon, followed by a valid port number. If you're supporting POMS remote clients (connecting via the Internet), then we strongly advise that you:

Basically, the rules and recommended practices are very similar to the way web servers are setup for access via the Internet.

Example 1: You have installed a POMS App Server on a server named poms.acme.com and configured it for access via port 443. The end-users, must enter poms.acme.com:443 for the App Server URL and ignore the Proxy Server URL.

Example 2: You have installed a POMS Proxy Server on a server named poms.acme.com and configured it for access via port 443. You have also installed a POMS App Server on a server named pomsapp.acme.com and configured it for access via port 443. The end-users, must enter poms.acme.com:443 for the Proxy Server URL. End-users that have access to host pomsapp.acme.com (e.g., internal users) can enter pomsapp.acme.com:443 for the App Server URL.

Upgrades

We continually enhance POMS and make new releases. Please visit our web site, www.pragsoft.com, to download new releases as they become available.

If your deployment model is three-tier or four-tier client-server, when you install an upgrade, you only need to install on the server machine(s). The client machines do not require upgrade installation; they automatically upgrade themselves against the new server release when users log in next time.


Configuring POMS

The POMS installation has been packaged so that the default settings will give you an 'out of box' working system if you install all the components on the same machine. Proper deployment, however, especially across multiple machines, will require configuration.

Please read the following configuration instructions carefully.

Application Configuration

POMS (Standalone or App Server) has a configuration file named <root>/prag/po/profile.max, where <root> denotes the directory in which POMS is installed (default is C:\POMS). This file defines how the application is configured. Open it with a text editor and make the following changes.

Locate the following entry in the file. It specifies the details of the Firebird database server.

(poDb {
    (driver "org.firebirdsql.jdbc.FBDriver")
    (database "jdbc:firebirdsql:localhost/3050:C:/POMS/db/POMS.FDB")
    (username "sysdba")(password "masterkey")
})
Change jdbc:firebirdsql:localhost/3050:C:/POMS/db/POMS.FDB to reflect the correct path for your installation. The username and password reflect the default DBA account in a new Firebird installation. If you want to use a different database user account for POMS, make sure that you change these entries to match the ones you setup in Firebird.

Now locate the following entry in the file. It specifies the details of your email server.

(email {
    (hostname "localhost")(port 25)
    (from "\"POMS Admin\" <admin@acme.com>")
})
Enter the valid hostname (or IP address) and port number for your email server. Also change admin@acme.com to a valid email address for POMS admin user.

Now locate the following entries.

(pomsPublishPath (relative "prag/publish/"))
(pomsUserDocPath (relative "prag/userdocs/"))
//Alternatively:
//(pomsPublishPath "//YourSharedNetDrive/poms/publish/")
//(pomsUserDocPath "//YourSharedNetDrive/poms/userdocs/")
These specify the directories where publications and user documents will be held (should you decide to publish any documents via POMS). The default entries are suitable if you have only one App Server. Where multiple App Servers are deployed, you should use a shared network drive for this purpose. The commented-out lines illustrate the syntax for using a shared network drive.

Finally, you will see the following entry at the end of the file.

(fxConfig {
    (base "US")
    ("US" {(code "US")(sym "$")(name "US Dollar")(rate 1.0)(format "@S0,000.00")})
    (list ["US"])
    (readOnly t)
})
This entry specifies the default currency for POMS. POMS support multiple currencies. However, this feature is disabled by the last line. You can change your base currency to another currency by editing these lines. For example, the following will use Euro as the base currency:
(fxConfig {
    (base "EU")
    ("EU" {(code "EU")(sym "")(name "Euro")(rate 1.0)(format "@S0,000.00")})
    (list ["EU"])
    (readOnly t)
})

Proxy Server Configuration

The Proxy Server has a configuration file named <root>/prag/proxy/po/profile.max, where <root> denotes the directory in which POMS is installed (default is C:\POMS). This file defines how the Proxy Server is configured. Open it with a text editor and make the following changes.

Locate the following entry in the file. It specifies how the proxy server should distribute client load between App Servers.

(proxyServer (loadBalance
    ("localhost" 443 "ssl/POMS.jks" 1.0)
    ("althost" 443 "ssl/POMS.jks" 0.5)
))
The above entry specifies that the proxy server should distribute client traffic between two hosts: localhost:443 will receive 100% load and althost:443 will receive 50% load. In other words, two-thirds of traffic will go to localhost:443 and one-third to althost:443. You can have as many App Server entries as you like (minimum of one is required). The load parameter (at the end of each line) should be a positive real number <= 1.0. This parameter allows you to adjust the load for each server to reflect its processing power.

Use of multiple App Servers gives you two benefits. Firstly, it will distribute the load so that you can support more clients. Secondly, it will protect you against the impact of an App Server failing or having to be taken offline for maintenance. When an App Server becomes unavailable, the Proxy Server(s) will automatically route all new traffic to those App Servers that are available.

POMS even allows you to edit the above entry without having to restart the Proxy Server, by following these steps:

This technique is useful, for example, when you want to adjust the load parameters or add or remove an App Server from the list.

If all App Servers become unavailable, then the Proxy Server will deliver the following window when a new client attempts to connect.

You can customize this message by editing the file <root>/prag/proxy/po/Unavailable.html.

When an off-line App Server is brought back online and there is at least another working App Server, it will take up to 5 minutes before the former receives any new traffic. This is because upon detecting a non-responding App Server, the Proxy Server will avoid retrying it for 5 minutes, unless there is no other App Server available.

Fail-over Server Configuration

You can deploy multiple Proxy Servers (in a four-tier model) or App Servers (in a three-tier model) in fail-over fashion. When a client tries to connect to such a server, if the server is unavailable, an alternative server will be contacted instead.

To specify fail-over, edit the <root>/boot.max in every App Server installation. The file contents look like this.

{
    ("thehost:443" ("althost1:443" "althost2:443"))
}
Replace thehost:443 with the URL that clients are configured to use. Replace althost1:443 and althost2:443 with one or more alternative servers.

When a client attempts to connect to thehost:443, this file is automatically copied to the client-side. After that, each time the client is run, it will look up the alternative hosts and try them in order if it fails to connect to thehost:443.

You can also specify multiple such lines in the file. During a run, any lines that do not begin with the host (that the client is configured to contact) will be ignored.

Client Configuration

Some client sites use local Internet proxy servers. In such cases, a POMS client must be configured to tunnel through the Internet proxy server. Otherwise, it will not be able to access a POMS server. To configure a client, choose the POMS Client (config) command from the PragSoft POMS menu of Windows Start menu. This will show the boot dialog as usual, however, the dialog contents will be editable.

If the Server Host field is up-to-date leave it unchanged. Otherwise, enter the correct address for a POMS server. In the Proxy Host field enter the address of the Internet Proxy Server (e.g., myproxy.acme.com:8080). Some Internet proxy servers require a login account (but most don't). If your Internet proxy server requires a login, complete the Proxy User and Password fields. Otherwise, leave them blank. Your System Administrator should be able to provide you with correct Proxy Host address and (if required) Proxy User and Password.

Finally, press the Run button. If a successful connection is made, then your Internet proxy server settings will be saved (in file <root>/client/proxy.max), so for your future runs you can use your normal POMS Client shortcut.


Deploying Servers

Server Deployment as Application

You can deploy an App Server or Proxy Server either as a Windows application or as a Windows service. We recommend the former while you are experimenting with POMS, and the latter for your production environment. The advantage of running a server as a Windows service is that you do not need to log into the server machine in order to run the server. This makes the method ideal for production environments.

To run an App Server or Proxy Server as an application, go to the PragSoft POMS menu in your Windows Start menu and select POMS App Server or POMS Proxy Server. A DOS window will commence. The server shortcuts are setup to send their output to date-stamped log files. This will ensure that the server output can be remotely viewed using the Server Monitor. You can view the actual command line for a server by right clicking on it and selecting Properties from the popup menu. The meaning of the command line options are explained below, in case you wish to adjust them by hand.

-cp is followed by the path of the JAR files the server uses.
-Xmx512m specifies the maximum amount of memory available to the server (512 megabytes in this example).
-prod means that this is a production server.
-log is followed by the path of the log file to which all server output will be directed. Removing this options causes the output to go to the DOS window instead. (Do not remove this option if you're deploying your server as a service.)
-host is followed by the URL of the server.
-root is followed by the root directory for the server.
-profile is followed by the path of the server profile.

Server Deployment as Service

To run an App Server or Proxy Server as a service, you must first configure the following BAT files for installing the service.
    <root>/bin/InstallPomsAppService.bat
    <root>/bin/InstallPomsProxyService.bat
To run these scripts you must have already installed the J2SE SDK (JRE is not sufficient).

To illustrate how these files are configured, the parameters appearing in InstallPomsAppService.bat and their default values are listed below. The parameters for InstallPomsProxyService.bat are a subset of these and should be configured similarly.

SERVICE_NAME="POMS App Server" This is the service name as it will appear in your Windows Services applet.
POMS_ROOT=C:\POMS This is the root directory for POMS. Change it if you've installed elsewhere.
POMS_JAR="%POMS_ROOT%\jar\POMS.jar" Don't change this.
SERVER_URL=localhost:443 Change this to reflect the URL of the server (hostname should be the host on which you're deploying the server).
SVR_PROFILE="prag/po/profile.max" Don't change this.
TIMEZONE="America/New_York" Change this to reflect your timezone (e.g., "Australia/Melbourne").
MEMORY_LIMIT=512M Change this if you want to set the server maximum memory to a different size.
JAVA_HOME="C:\j2sdk1.4.2" Change this to point to where the Java 2 SDK is installed.
JAVA_DLL=%JAVA_HOME%\jre\bin\server\jvm.dll Don't change this.
CLASS_PATH=%JAVA_HOME%\lib\tools.jar;%RT_JAR% Don't change this.
JAVA_SVC_EXE="%POMS_ROOT%\bin\JavaService.exe" Don't change this.

Having configured the file, run it to install the service. We recommend that you run the BAT file in a DOS window (rather than just double-clicking it), so that if there are any errors, you can see them. Subsequently, you can stop/restart a service from the Windows Services applet (in the Control Panel). If you need to change any of the service parameters, stop the service, change the parameter and rerun the BAT file for it to take effect.

Installing Your Own Security Certificate

The POMS installation includes a security certificate in the file ssl/POMS.jks. All client-server communication is SSL-encrypted using this certificate. You can use this as is or, if you prefer, generate your own security certificate to replace it. However, to avoid the risk of breaking the installation, we recommend that you use the certificate provided by us.

To generate your own security certificate, use the following command:

keytool.exe -genkey -keyalg RSA -alias server -validity 18250 -keystore POMS.jks
where keytool.exe is a utility in the bin directory of your Java installation. Follow the prompts and enter the requested information. First time you're asked for a password, enter the default password changeit (do not use any other password). The second time you're asked for a password, just press enter.

This command produces a self-signed security certificate in the keystore POMS.jks. You will need to replace the ssl/POMS.jks file in the POMS installation with this one, both on the client and server sides.

You can, optionally, export the certificate to a certificate file using this command:

keytool.exe -keystore POMS.jks -export -alias server -file POMS.cer
This produces a certificate file named POMS.cer, which you can open to view the certificate details, such as validity period. However, POMS does not require POMS.cer, it uses POMS.jks instead.

IMPORTANT: If you generate your own certificate, you must ensure that the new POMS.jks file replaces the old one on all client and server installations. If a client and a server use two different versions of this file, they will not be able to communicate.


User Login

In a new POMS installation, two user accounts are predefined: To log into POMS, go to the PragSoft POMS in your Windows Start menu, and choose POMS Client or POMS Standalone, depending on your deployment model. Wait until the login screen appears and then enter a username and password and press Login.

Once successfully connected, the Application Frame will appear. If this is your first login, you should change your password.


Table of Contents | Next Chapter >>

Copyright 2005 PragSoft Corporation (www.pragsoft.com)