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