Installation instructions for GNU Enterprise Reports
====================================================


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

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

* Python 2.3 or greater [python python-dev]

* GNUe Common 0.6.8 or greater [gnue-common]

* at least one of the following database interfaces, depending on the database
  you want to use (unless you run gnue-reports in a three tier environment with
  gnue-appserver):
  - psycopg2 (preferred for PostgreSQL) [python-psycopg2]
  - psycopg (also possible for PostgreSQL) [python-psycopg]
  - pyPgSQL (also possible for PostgreSQL) [python-pgsql]
  - pygresql (also possible for PostgreSQL) [python-pygresql]
  - python-mysqldb (for MySQL) [python-mysqldb]
  - KInterbasDB (for Interbase/Firebird) [python-kinterbasdb]
  - MaxDB (for MaxDB) [python-maxdb]
  - PySQLite (for SQLite2) [python-sqlite]
  - PySQLite2 (for SQLite3) [python-pysqlite2]
  You can find more information about possible database backends on the web
  page http://www.gnuenterprise.org/tools/common/databases/.

You also need either a database server (one of those supported by GNUe) or GNUe
AppServer running on the local or on a remote machine, and in case of a
database server, you need the corresponding database client software 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-forms against a database server.


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

* Make sure that you have write permission in the directory /usr/local and its
  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.


Support for the "printer" destination
-------------------------------------

Currently, the only "printer" adapter available is the "bsd" adapter. This
adapter uses the command-line "lpr".  Most Unix distro's include some form
of the "lpr" command.

You should modify your gnue.conf and set the PrinterAdapter to "bsd":

  PrinterAdapter = bsd

Also, you can modify the following parameters to better reflect your
local setup:

  LprCommand = /usr/bin/lpr -P%s

Note the "%s" -- this will be replaced with the printer spool specified by
the end user.  It is important to include this "%s".

You can now send reports to your printer. Example gnue-reports:

  $ gnue-reports -D printer -d lp --filter text myreport.grd

The report will be run as a "text" document, then sent, via lpr, to
the printer "lp".


Support for the "file" destination
----------------------------------

Currently, the only "file" adapter available is the "text" adapter. This
adapter simply creates a text file with the provided name.

You should modify your gnue.conf and set the FileAdapter to "text":

  FileAdapter = text

Example gnue-reports:

  $ gnue-reports -D file -d $HOME/myreport.html --filter html myreport.grd

The report will be run as an "html" document and saved to the file
"myreport.html" in the user's home directory.

Note that if the destination is set to "-", then the stdout "file" is used.
In other words, -d -  will output the report to the console (or through a
unix pipe.)  When using -d -, it is best to also specify the --quiet option.

Example gnue-reports using Unix pipes:

  $ gnue-reports --quiet -D file -d- --filter html | enscript -P lp


Support for the "email" destination
-----------------------------------

Currently, the only "email" adapter available is the "sendmail" adapter.
Work is underway for a native SMTP adapter that will communicate directly
with an SMTP server.

You should modify your gnue.conf and set the EmailAdapter to "sendmail":

  EmailAdapter = sendmail

Also, you can modify the following parameters to better reflect your
local setup:

  SendmailBin = /usr/sbin/sendmail
  SendmailFrom = "GNUe Reports Server" noreply-reports@mydomain.com
  SendmailSubject = Your Requested Report

You can now send reports via email. Example gnue-reports:

  $ gnue-reports -D email -d you@yourdomain.com --filter html myreport.grd

The report will be sent as an attachment. In the above example, the
attachment will be an "html" file.


Support for the "fax" destination
---------------------------------

Currently, the only "fax" adapter available is the "hylafax" adapter.
Support for HylaFax is provided by the "sendfax" command.  The hylafax
adapter does not communicate directly with the hylafax server, but,
rather, uses HylaFax's "sendfax" command-line program.

Before attempting to send faxes via GNUe Reports, be sure to test the
sendfax command line tool manually and make sure it is properly configured:

  sendfax -n -d <myfaxnumber> -h <faxhost> /etc/issue

Once you are satisfied that your local machine is configured properly for
HylaFax, you should modify your gnue.conf to set the FaxAdapter parameter:

  FaxAdapter = hylafax

Also, you can modify the following parameters to better reflect your
local setup:

  HylaFaxCommand = /usr/bin/sendfax -n -h faxserver.mydomain.com -d %s

Note the "%s" -- this will be replaced with the fax number specified by
the end user.  It is important to include this "%s".

You can now send reports via HylaFAX. Example gnue-reports:

  $ gnue-reports -D fax -d 1-901-555-4433 --filter text myreport.grd

The report will be run as a "text" document, then sent, via sendfax, to
the fax machine at (901) 555-4433.  Note that --filter must be a type
that sendfax can convert.  Once Postscript support is added to GNUe
Reports, "--filter postscript" will be the logical choice. Until then,
unless you've manually configured sendfax to convert html documents,
"--filter text" is the only reasonable choice.
