DotGNU Execution Environment Source Installation Guide

This document explains how to install DGEE by building it from the source distribution. Visit the DGEE Packages page for instructions on installing the binary package distributions.

Source Code Downloads

The DGEE is an appserver which currently uses the Portable.Net runtime to execute the services. The DGEE is centered around its own Savannah project . DGEE uses Apache to manage HTTP traffic for its xmlrpc frontends. GnuPG-signed md5sums are here.

Source

• phlib-1.20.tgz
• goldwater-1.4.0.tgz
• dgee-0.1.6-2.tgz

Building

Suggested steps for building the dgee are:

1. Configure and install phlib under /usr/local
2. Configure and install goldwater under /usr/local
   (goldwater requires expat and readline (and readline-devel as it needs the
   header files for compilation)
3. Configure and install pnet and pnetlib
4. Configure and install DGEE somewhere like /usr/local (the default location)
5. Make sure Libraries can be found (see below)
6. Configure Apache as described below.
7. Setup your environment and boot the DGEE (see the README file).
8. Follow the instruction in the examples dgee src directory for compiling
and installing a test webservice and getting the documentation generated for
it.


Read the README, QUICKSTART and BINARYINSTALL guides as they cover a lot of
the more interesting configuration points from various angles.


Notes:
------

The DGEE should be installed into a user account as it needs to run as a
'user'.  You could probably create a special dgee user for this purpose,
however - if you're running the DGEE along with Apache, you'll need it to run
as the same user as Apache, often 'nobody'.

Configuration options:

--prefix=         Where to install the dgee
--with-phlib=     Where phlib has been installed (defaults to /usr/local)
--with-goldwater= Where Goldwater has been installed (defaults to /usr/local)
--with-pnet=      Where portable.net has been installed (defaults to /usr/local)
--with-apache=    Where to find the apache v1 apxs tool.
--with-apache2=   Enable Apache 2 (and where to find the apache v2 apxs tool)
--with-python     Enable pythonVM support (--without-python to disable)
--with-username=  The username the DGEE will run as (default nobody)
--with-usergroup= The usergroup the DGEE will run as (default nobody)

(./configure --help gives the full list)

Apache 1 Notes:
---------------
Apache v1 support is enabled by default.  To disable it, use --without-apache.
To configure DGEE for use with Apache v1, then use --with-apache=
If apache apxs is not available on the build machine, there is a pre-built
apache/precompiled/mod_dgee.so that may be copied into the DGEE libdir 
[dgee_install_base]/libexec/mod_dgee.so

Apache is last in the build process just incase apxs cannot be found.

It may warn with the following message on apache startup:
[warn] Loaded DSO /usr/local/libexec/mod_dgee.so uses plain Apache 1.3 API, this
module might crash under EAPI! (please recompile it with -DEAPI)

This appears to be okay and has not so-far caused any problems.  The solution
is to build mod_dgee.so yourself against your installed apache.

Apache 2 Notes:
---------------
Apache 2 is disabled by default, enable it with --with-apache2 (you may want to
disable apache 1 support by using --without-apache).

If apache2 apxs is not available on the build machine, there is a pre-built
apache2/precompiled/mod_dgee2.so that may be copied into the DGEE libdir
[dgee_install_base]/etc/mod_dgee2.so


Once Installed
--------------
Once built and installed, you should set the profile of the DGEE owner to 
dot src the dgeeenv.sh file to set up the environment.

ie add the line:
. [dgee_install_base]/share/dgee/dgeeenv.sh

to the users .profile (or .bash_profile)

(This used to be mandatory but with DotGNU 0.1 all the DGEE command line tools
 work without the environment being set up so this step may be skipped. It is
 left documented here for reference as experienced users may do things with the
 DGEE outside the supplied command line tools).


Make 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 /sbin/ldconfig:

/usr/local/lib
/usr/local/lib/pnet



IPC Resources
-------------

The user that Apache is running as must be the same as the DGEE user (ie the
one that started Goldwater and thus owns the IPC resources).

shell> ipcs 

------ Shared Memory Segments --------
key       shmid     owner     perms     bytes     nattch    status      
0x00000000 0         gdm       777       98304     2         dest        
0x00004e20 15826945  nobody    600       20648     10                    
...
...

In this example it is the user 'nobody', which is the default for DGEE.

Reason: Apache needs to have permission to 'join' the DGEE application so that
it may fire off requests.  To do this it requires access to the DGEE IPC
resources, which have tight permissions.


Tuning IPC resources
--------------------
DGEE requires several message queues to run.  Each client connecting to the
DGEE also requires a message queue.  Apache is one such client, so for
every apache child process that may run, a message queue is required.

Run the tool dgeediagnose. This will help with the sizing of the DGEE IPC
resources.

In addition the following should be considered:

shell> ipcs -l
...

------ Messages: Limits --------
max queues system wide = 128
max size of message (bytes) = 8192
default max size of queue (bytes) = 16384


This shows that a maximum of 128 queues are available.  As long as apache is
configured to only have ~100 child processes then there will be enough to
go around.

However it is likely that your kernel is configured for a max of 16 
message queues, which is far too small.

To change this do the following as root:

shell> echo 128 > /proc/sys/kernel/msgmni

or to make the increment persist across reboots (This example taken from a
RedHat system),  edit /etc/sysctl.conf and add :

# Increase Max Message Queues to 128
kernel.msgmni = 128

Now load the new settings:

shell> sysctl -p

Follow this by a check to see if the change has been accepted:
shell> ipcs -l 


Configuring Apache
------------------
Add the following to your apache httpd.conf at the appropriate location (the
apache src directory contains an example httpd.conf) to load and install the
apache dgee module:

LoadModule dgee_module     [dgee_install_base]/libexec/dgee/mod_dgee.so
AddModule mod_dgee.c


And add the following to invoke the dgee for suitable requests:

include [dgee_install_base]/etc/mod_dgee.conf


<Location /dgee>
  include [dgee_install_base]/etc/mod_dgee.conf
</Location>

Where dgee_install_base is the path to the installation base of the DGEE 
application, /usr/local by default.


Summary
-------
1. Make sure Apache runs as the same userid as the DGEE application.
2. Make sure approximately max_apache_child_processes + 20 message queues
   are available.


-- end --