Quickstart and Installing Webservices
-------------------------------------

( You should skip to step 5. if you are installing from a binary distribution,
  however read the BINARYINSTALL document!! )


1. Configure and install phlib under /usr/local

cd into phlib src directory
./configure --prefix=/usr/local
make
make install (as root)


2. Configure and install goldwater under /usr/local
    (goldwater requires expat and readline (development as it needs the header files)

cd into goldwater src directory
./configure --prefix=/usr/local --with-phlib=/usr/local
make
make install (as root)


3. Configure and install pnet and pnetlib
(this readme assumes /usr/local)


4. Configure and install DGEE

There are many build options that may be supplied to affect where components
are installed, by default it follows the GNU standard.

The location of logfiles and the webservice repository will generally want
to be somewhere writable by a user running the DGEE (as it does not run as
root).  

This example assumes that apache build tool apxs is installed in /usr/local/sbin
If you do not have apxs then you'll have to try using the precompiled 
mod_dgee.so in apache/precompiled at installation/configuration time.
The default install base of /usr/local is used:

mkdir $HOME/dgee_release
cd into dgee src directory
./configure --with-phlib=/usr/local --with-goldwater=/usr/local --with-pnet=/usr/local --with-apache=/usr/local/sbin
make
make install (as root)

The build will fail the apache module if apxs is not where specified.


** Making Sure Libraries Can Be Found at Runtime **

You might need to add the location of libgc.so and other pnet delivered
libraries to /etc/ld.so.conf and run ldconfig having installed pnet, as dgee 
needs to find them at runtime.  Also you should add the dgee libs to
ld.so.conf as well - so assuming both pnet and dgee have been installed in
/usr/local, add the following to /etc/ld.so.conf and run ldconfig:
/usr/local/lib
/usr/local/lib/pnet


5. Setup your environment

The DGEE needs some environment variables set for it to find its resources,
and to help this an env script is provided that should be sourced as required.

If you use the DGEE supplied commands (dgadmin, dgeestart, csdgmx, dginstallws,
dgremovews etc) to administer the system then the environment will not need
setting manually.  However if you need to change the runtime configuration
file at any time then the environment will need setting. See the FAQ for
further details.

If you want to sent the environment perminantly for a user then the env script
should be sourced by the .profile of the dgee 'user'.

By default the DGEE runs as the nobody user which does not have a home
directory, starting the dgee as root will see it switching to the configured
user (nobody unless otherwise configured).

So before running as root, execute the command:

shell> . /usr/local/share/dgee/dgeeenv.sh

If you're running the DGEE as another user, then edit that users 
~/.bash_profile or ~/.profile depending on which you use and add the following
line:

. /usr/local/share/dgee/dgeeenv.sh

(You'll have to log out and back in again as this user for the change to take
 effect)


6. Checking the System Configuration is correct

Run the command dgeediagnose.

This will check and report on may configuration issues that may affect the 
running of the DGEE.


7. Starting DGEE

Run the command dgeestart

(See the README for further information)


8. Configure Apache

Add the following to your apache httpd.conf at the appropriate locations (the
apache src directory contains an example httpd.conf):

LoadModule dgee_module     /usr/local/libexec/mod_dgee.so
AddModule mod_dgee.c

include /usr/local/etc/mod_dgee.conf

# Optional 'directory' based DGEE association 
# allows http://url/dgee/test in addition to the default 
# http://url/test.dgmx
#
<Location /dgee>
  include /usr/local/etc/mod_dgee.conf
</Location>


Apache needs to run as either the user who started the DGEE or the DGEE needs
to run as the Apache user.

The following settings in httpd.conf file are suggested:
User nobody
Group nobody

or, if these are not appropriate and you are building the DGEE yourself, then
you may use the --with-username and --with-usergroup configure options (see
./configure --help for details).

If you did not build mod_dgee.so yourself then you will need to copy the
precompiled version from src/apache/precompiled/mod_dgee.so to
/usr/local/libexec/mod_dgee.so

(See INSTALL for details on Apache2).


9. Start Apache

Start apache in the usual way


10. You may now install a webservice

cd examples
make

This will create wstest.dll, state.dll and math.dll

Generate a dgmx files for each of these webservices:

csdgmx wstest.dll
csdgmx state.dll
csdgmx math.dll

Now install the webservice into the dgee by running dgeeinstallws script:

dgeeinstallws wstest
dgeeinstallws state
dgeeinstallws math

(Or you can copy the dll files directly into /usr/local/var/dgee/data and the
dgmx files into /usr/local/var/dgee/index - make sure the ownership on the
directory and files is correct).

You can now view the web service documentation for this webservice by pointing
your browser at:

http://my.local.apache.webserver/wstest.dgmx
http://my.local.apache.webserver/state.dgmx
http://my.local.apache.webserver/math.dgmx

If you want to see the documentation in XML form, use the following:

http://my.local.apache.webserver/wstest.dgmx?xml


XML-RPC access to the webservice is enabled by POSTing your XML-RPC request
to http://my.local.apache.webserver/wstest.dgmx

The perl directory contains a simple XMLRPC test client.  
It requires XMLRPC::Lite which is part of SOAP::Lite.



Notes:
------

Shutting down the DGEE before Apache will leave Apache hanging onto system
IPC resources.  This can be cleaned up by stopping Apache and running
dgeestop again.

Please see the README and INSTALL files and examples/readme for further
information.


Use examples/wstest.cs as a guide to writing your own webservices.

If you're really Interested...
------------------------------
Investigate the following administrative commands:

dgadmin pl      # DGEE Process List
dgadmin sl      # DGEE Service List

You can enter these commands interactively by typeing dgadmin directly.
Type help to get a full list of commands available.

(dgadmin is an alias for goldwater, using 'goldwater' will produce the same
 results).


Chris Smith - 26/03/2003

