Configuration of the GNU Enterprise Application Server
======================================================

First thing you have to do is to install the gnue-appserver package and all its
dependencies.  You have several ways of doing this:

A. Install the packages available for your platform and distribution of choice.
   * Debian packages are included in the standard distribution.
   * Ubuntu packages are contained in the "universe" component.
   * Microsoft Windows installation files in .exe format are available at
     http://www.gnuenterprise.org/downloads/current.php
   (If you provide packages for other platforms/distributions please let us
   know so we can add you to this list)

B. If no ready-made packages are available for your platform and distribution,
   download the source packages of gnue-common and gnue-appserver from
   http://www.gnuenterprise.org/downloads/current.php and follow the
   instructions given in the file "INSTALL" of each of these packages.

C. If you *really* want to follow the bleeding edge of development, you can
   access our SVN repository by following the instructions given at
   http://www.gnuenterprise.org/developers/svn.php. Please make sure your read
   the file "README.cvs" in every package, if available.

Once you have installed the gnue-common and gnue-appserver packages, you have
to do several configuration steps:


1. Prepare your database backend
--------------------------------

Make sure that your database server is running and accepting connections from
the machine you want to run gnue-appserver on.  Also make sure that your
current user is allowed to create new users and new databases on the database
server.

Please refer primarly to the documentation of your database server about how to
achieve and test this.  However, the files "hints.postgresql.txt",
"hints.mysql.txt" and "hints.firebird.txt" in gnue-common's documentation
directory contain some hints on how to set up the respective database servers
for use with GNU Enterprise.

Note that you do not yet create the actual database on the database server.


2. Set up your connections.conf
-------------------------------

The most important configuration file for gnue-appserver is "connections.conf".
On Posix compatible systems (like GNU/Linux) you will find this file in the
"/etc/gnue" directory (for prepackaged versions) or in the "/usr/local/gnue/etc"
directory (if you installed from the source packages).  Alternatively, all GNU
Enterprise tools accept a "--connections" paramter that overrides the location
of the connections.conf file.

On the machine running gnue-appserver, you must have an entry in the
connections.conf pointing to your database.  The default database name in
appserver is "gnue".  You can change it with the command line option
"--connection".  If you don't use postgresql you have to set the username and
password for the database you want to use by command line options.

Example for a correct connections.conf entry on the machine running
gnue-appserver:

  [gnue]
  comment = Database for GNUe Application Server
  provider = psycopg
  host = localhost
  dbname = gnue
  username = frank
  password = secret

[gnue]: the name of the database connection (you can define several connections
  to different databases in the same connections.conf file).  You can tell
  gnue-appserver which connection to use with the "--connection" command line
  parameter or with the "connection" configuration option in gnue.conf.

comment: comment text without any special meaning

provider: can for example be "psycopg", "pygresql", or "pypgsql" for PostgreSQL
  database servers (depending on the database driver you installed), "mysql"
  for MySQL database server, "interbase" for Firebird/Interbase database
  servers, or "sqlite" if you use the SQLite embedded database.

host: hostname of the machine running the database server

dbname: name of the database

username: user name gnue-appserver should use to connect to the database.
  Some databases do not or not always require a username.  If a username is
  required, you can either define it here or with the "--username" command line
  parameter to gnue-appserver.  If no username is given, it defaults to "gnue".

password: password gnue-appserver should use to connect to the database.
  Some databases do not or not always require a password. If a password is
  required, you can either define it here or with the "--password" command line
  parameter to gnue-appserver.

You can find more information about the available database drivers (providers)
and the required and optional entries in connections.conf for each of them on
http://www.gnuenterprise.org/tools/common/databases/.


3. Create the basic database
----------------------------

Before you can start gnue-appserver, you have to create a database and populate
it with some system tables.

For PostgreSQL, Firebird/Interbase, MySQL or SQLite:
* execute the script 'gnue-setupdb'

All other database servers:
* create your database as described in your database documentation
* make sure you have access to this database and it fits your settings in your
  connections.conf
* in the directory "/usr/share/gnue/appserver" (if you installed a prepackaged
  version) or "/usr/local/gnue/share/gnue/appserver" (if you installed from the
  source packages), run the command "gnue-schema --connection=gnue gnue.gsd".

At this point, you should be able to run gnue-appserver.


4. Feed applications into the application server
------------------------------------------------

The GNU Enterprise Application Server defines a directory (or a list of
directories) to be the "module path".  Applications written for the GNU
Enterprise Application Server provide files with the ending ".gcd" and ".gld".
These files have to be copied into that directory (or into one of the
directories in the list, respectively), or a subdirectory thereof.

The module path can be defined with the "modulepath" configuration option in
gnue.conf and overridden with the "--modulepath" command line parameter to
gnue-appserver.  If you wish to specify a list of directories to search
through, separate the directories by a semicolon (";").

If the module path is neither configured in gnue.conf nor specified on the
command line, it defaults to "/usr/share/gnue/appserver" for prepackaged
installs, and to "/usr/local/gnue/share/gnue/appserver" for standard installs
from the source packages.

Whenever you change a file in the module path, you can send the running
gnue-appserver process a SIGHUP signal, this will make all changes become
effective.

Some applications also provide files with an extension of ".gsd" that contain
default or sample data.  You can read in those files with the command
"gnue-schema --connection=gnue <filename>".


5. Configure access to gnue-appserver for the front end
-------------------------------------------------------

On the machine running the front ends (gnue-forms, gnue-reports,
gnue-designer), you need an entry in the connections.conf that points to the
Application Server.  If you have the front ends installed on the same machine
as gnue-appserver, there's only a single connections.conf with both entries.

Example for a correct connections.conf entry on the machine running gnue-forms,
gnue-reports or gnue-designer:

  [appserver]
  comment = Connection to the GNUe Application Server
  provider = appserver
  rpctype = xmlrpc
  host = localhost
  port = 8765
  transport = http
