Installation instructions for GNUe Reports

Note: Instructions for Debian are at the end of this document.

Short Version
=============

For the impatient...

Install the following prerequisites:

 * Python 2.0 or later    http://www.python.org/
 * GNUe-Common            http://www.gnuenterprise.org/downloads/common
 * Sablotron              http://www.gingerall.com/charlie/ga/xml/p_sab.xml
 * PySablot               http://sourceforge.net/projects/pysablot/

Then, as root:

 $ python2 ./setup.py install  (may also be python2.1 or python2.2)
 $ cd /usr/local/gnue/etc
 $ cp sample.gnue.conf gnue.conf
 $ cp sample.report-filters.conf report-filters.conf


Introduction
============

GNUe Reports is the primary reporting engine for GNU Enterprise.
It requires a few prerequisite packages to be installed prior to
installing reports.

Currently, reports will only run in a command-line mode -- the
"server" implementation of GNUe Reports is still underway. This
means Reports is currently useful for evaluation or for small,
centralized (2-tier) sites.


Prerequisites
==============

GNUe Reports needs some prerequisites to work. You need a database
managment system and the scripting language Python (version 2.0 or
higher).  Most modern Unix platforms have a python package available.

The following minimum programs are required for running GNUe-Reports:

 Python 2.0 or later    http://www.python.org/
 Sablotron              http://www.gingerall.com/charlie/ga/xml/p_sab.xml
 PySablot               http://sourceforge.net/projects/pysablot/
 GNUe-Common            http://www.gnuenterprise.org/downloads/common


Installation
============

Run the following command:

  python2 setup.py install

If python2 is not found, try one of these alternates:

  python2.1 setup.py install
  python2.2 setup.py install


Configuration
=============

Make sure that you have a valid /usr/local/gnue/etc/gnue.conf and
a valid /usr/local/gnue/etc/report-filters.conf.  Sample versions of
these files are installed by gnue-common as sample.gnue.conf and
sample.report-filters.conf.  These samples will be sufficient for
most sites. Simply copy the sample files to the needed files.

See the various sections below for setting up the "destinations"
(printers, email, file, and fax.)


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.


Debian Installation
===================

To install on a Debian system, you need to apt-get the following packages
(these exist in Woody; I'm not sure about Potato):

  python2.1
  python2.1-dev
  python2.1-egenix-mxdatetime
  sablotron
  libexpat1
  python2.1-psycopg  (if needed -- for PostgreSQL support)
  python2.1-mysqldb  (if needed -- for MySQL support)
  hylafax-client     (if needed -- for Fax support)

Also, grab the debs for PySablot from:
  http://www.gnuenterprise.org/~jcater/debian/pysablot2.1_0.1-1_i386.deb

and install as:
  dpkg --install pysablot2.1_0.1-1_i386.deb

You should now have all the prerequisites installed and can install
GNUe Common and GNUe Reports using:

  python2.1 setup.py install



