New INSTALL file, to replace INSTALL and INSTALL.manual

[Erik Huelsmann <..hidden..>]

Hi Chris,

Below you'll find a new file which I hope can replace INSTALL and
INSTALL.manual. The file refers to my database setup script submitted
earlier to simplify the instructions.


Let me know your comments!


Bye,

Erik.

-----------------------------------------------------




Contents
--------

 * System requirements
 * Installing Perl module dependencies
   * for Debian
   * for Fedora
   * for <your system>
 * Adding configuration to Apache 2.x
 * Initializing a company database


Installing Perl module dependencies
-----------------------------------

LedgerSMB depends on these required modules:

 * Data::Dumper
 * Log::Log4perl
 * Locale::Maketext
 * DateTime
 * Locale::Maketext::Lexicon
 * DBI
 * MIME::Base64
 * Digest::MD5
 * HTML::Entities
 * DBD::Pg
 * Math::BigFloat
 * IO::File
 * Encode
 * Locale::Country
 * Locale::Language
 * Time::Local
 * Cwd
 * Config::Std
 * MIME::Lite
 * Template
 * Error
 * CGI::Simple

and these optional ones:

 * Net::TCLink        [Support for TrustCommerce credit card processing]
 * Parse::RecDescent  [Support for the *experimental* scripting engine]
 * Template::Plugin::Latex [Support for Postscript and PDF output]
 * XML::Twig          [Support for OpenOffice output]
 * Excel::Template::Plus [Support for Excel output]


All these modules can be downloaded from CPAN, the modules distribution
archive for Perl, but experiences were most positive when using the
modules from distributions, when available.

The sections below list specific instructions for the different OSes and
distributions. If you plan to depend as much as possible - as recommended -
on your distribution, you should follow the instructions in those sections
before proceeding here.

When you have completed the distribution specific steps described below,
you should proceed to run:

 $ perl Makefile.PL
 $ make install

which will ask you which modules to download from CPAN from the list of
optional modules.

Remark: If you've never downloaded packages from CPAN, Perl is likely
to ask you a number of questions regarding the configuration of the
CPAN module (the Perl module downloader) as well.




>>> Perl module dependencies for Debian

[For a list of actions to take on Lenny, see below]

---- Actions for Debian Squeeze

To install all the required packages which Lenny supports, execute the
following command:

 $ aptitude install libdatetime-perl libdbi-perl libdbd-pg-perl \
   libcgi-simple-perl libtemplate-perl libconfig-std-perl libmime-lite-perl \
   liberror-perl liblocale-maketext-lexicon-perl libtest-exception-perl \
   libtest-trap-perl liblog-log4perl-perl

This installs the modules available from the Squeeze repository.

As far as the optional packages are concerned on Squeeze, the Excel and
PDF/Postscript output options are not directly available. If you want
these output options, you'll need to download them from CPAN.

Please note that the PDF/Postscript module depends on the TeX/LaTeX
package which *is* in the Squeeze package repository:

 $ aptitude install texlive-latex-recommended

The credit card processing support for TrustCommerce is available
from the Squeeze repository through:

 $ aptitude install libnet-tclink-perl

The Open Office output option is available from the Squeeze repository
as well through the command:

 $ aptitude install libxml-twig-perl


---- Actions for Debian Lenny

To install all the required packages which Lenny supports, execute the
following command:

 $ aptitude install libdatetime-perl libdbi-perl libdbd-pg-perl \
   libcgi-simple-perl libtemplate-perl libconfig-std-perl libmime-lite-perl \
   liberror-perl liblocale-maketext-lexicon-perl libtest-exception-perl \
   liblog-log4perl-perl

The required module Test::Trap isn't available as a Lenny package. In order
to install that component, execute the following commands:

 $ aptitude install libmodule-install-perl
 $ cpan 'Test::Trap'


As far as the optional packages are concerned on Lenny, the Excel and
PDF/Postscript output options are not directly available. If you want
these output options, you'll need to download them from CPAN.

Please note that the PDF/Postscript module depends on the TeX/LaTeX
package which *is* in the Lenny package repository:

 $ aptitude install texlive-latex-recommended

The credit card processing support for TrustCommerce is available
from the Lenny repository through:

 $ aptitude install libnet-tclink-perl

The Open Office output option is available from the Lenny repository
as well through the command:

 $ aptitude install libxml-twig-perl



Adding configuration to Apache 2.x
==================================

LedgerSMB requires a webserver which passes authentication information
through to the LedgerSMB application (instead of handling those itself).
Currently, Apache (with mod_rewrite support) and IIS are known to support
this requirement. The section below details the Apache setup process.

If your Apache has been built with module support, your configuration files
should include the following line somewhere:

LoadModule rewrite_module <path-to-apache-modules-directory>/mod_rewrite.so

[On Debian and its derivatives, mod_rewrite can be enabled using the command

 $ a2enmod rewrite

executed as the root user.]

A default configuration file to be used with Apache2 comes with LedgerSMB in
its root project directory: ledgersmb-httpd.conf.  To be able to use it, you
need to run the following command:

 $ sed -e 's!WORKING_DIR!/path/to/lsmb!g' < ledgersmb-httpd.conf \
      > lsmb-httpd.conf

Then, you need to add a commmand to your Apache configuration to load the
configuration in that file by including the following line:

Include /path/to/lsmb/lsmb-httpd.conf

[Regarding Debian and derivatives, you can store the resulting configuration
file directly in the /etc/apache2/conf.d directory. From that location, it'll
be automatically included upon the next server (re)start.]


In order for the changes to take effect, you should run

 $ apachectl restart

or the less invasive 'restart as soon as possible'

 $ apachectl graceful


Initializing a company database
===============================

LedgerSMB depends on the PostgreSQL database system. Additionally, 3 'contrib'
modules must also be available: tsearch2.sql, pg_trgm.sql and tablefunc.sql.

The 'prepare-company-database.sh' script in the root directory of the sources
will set up databases to be used for LedgerSMB. The script should be run as
the root user because it wants to 'su' to the postgres user.

The following invocation of the script sets up your first test company,
when invoked as the root user and from the root directory of the LedgerSMB
sources:

 $ ./prepare-company-database.sh --company testinc

The script assumes your PostgreSQL server runs on 'localhost' with port
PostgreSQL's default port (5432).

Upon completion, it'll have created a company database with the name
'testinc', a user called 'ledgersmb' (password: 'LEDGERSMBINITIALPASSWORD'),
a single user called 'admin' (password: 'admin') and the roles required to
manage authorizations.

Additionally, it'll have loaded a US chart of accounts and some data used
by the LedgerSMB application itself.

All these can be adjusted using arguments provided to the setup script. See
the output generated by the --help option for a full list of options.


----------------------------------------------------