Installation instructions for GNUe Application Server
=====================================================


Requirements
------------

To install gnue-appserver, you need at least the following prerequisites
installed on your system [Debian packages in brackets]:

* Python 2.1 or greater [python python-dev]

* XML Tools for Python [python-xml]

* Egenix MX DateTime tools for Python [python-egenix-mxdatetime]

* at least one of the following database interfaces, depending on the database
  you want to use:
  - psycopg (preferred for PostgreSQL) [python-psycopg]
  - popy (also possible for PostgreSQL) [python-popy]
  - pygresql (also possible for PostgreSQL) [python-pygresql]
  - python-mysqldb (for MySQL)
  you can find more information about possible database backends in the file
  README.Databases, distributed with GNUe Common.

* at least one of the following RPC libraries:
  - py-xmlrpc [python-xmlrpc]
  - Pythonware xmlrpc (included in Python starting with 2.2)

* GNUe Common 0.5.0 or greater [gnue-common]

To build the documentation, you need GNU Texinfo 4.0 or newer installed.

You also need a running database server (one of those supported by GNUe) on the
local or on a remote machine, and you need the corresponding database client
installed on the local machine.  We very much recommend that you make sure that
you can access the database with the databases's normal client tools before you
try to install and run gnue-appserver.

It is of course suggested that you have GNUe's front end tools installed either
on the local or on a remote machine.


Installation
------------

* Make sure that you have write permission in the directory /usr/local and it's
  subdirectories.

* From the shell prompt, change into the directory containing the file
  "setup.py" and type "./setup.py install".  If you have all prerequisites
  installed, the installation process should run without errors.  If any error
  occures although you have fulfilled all dependencies described above, this is
  probably a bug, either in the installation program or in the documentation.
  Please report it.


Configuration
-------------

(Future releases might have an own documentation file describing configuration
more detailed)

The most important configuration file for gnue-appserver is "connections.conf".
If you did a standard installation, you can find it in /usr/local/gnue/etc.

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

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
