

Contents
--------

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



System requirements
===================

LedgerSMB depends on the following software:

 * a web server (Apache v2.x or MS IIS)
 * PostgreSQL 8.2+
 * Perl 5.8+



Installing Apache 2
===================

On Debian and its derivatives - like Ubuntu - Apache installation
is as simple as running:

 $ apt-get install apache2

On Fedora systems the following command does the same:

 $ yum install httpd

On other systems, the steps to follow may differ.  Please submit
instructions for your system for inclusion here.


Installing PostgreSQL
=====================

On Debian and its derivatives installing PostgreSQL works with:

 $ apt-get install postgresql-server postgresql-client postgresql-contrib

On Fedora systems this command does the same:

 $ yum install postgresql postgresql-server postgresql-contrib

On other systems, the steps to follow may differ.  Please submit
instructions for your system for inclusion here.


PostgreSQL authorization settings (pg_hba.conf)
===============================================

pg_hba.conf settings for production
-----------------------------------

LedgerSMB passes through the HTTP auth info to PostgreSQL as user
credentials.  Currently we do not support Kerberos auth but that won't
be hard to add once someone wants it (maybe a couple hours of
development time).  Consequently, you should be aware of a couple of
things:

1)  Re-usable credentials are required.  That basically means HTTP
Basic unless you want to set up Kerberos.  As a result you will
certainly want to run this over SSL if this is not a single system
operation (which in your cases it is not).

2)  This also means that PostgreSQL must be able to use the
credentials the web server accepts.  Currently we recommend the md5
authentication method in the pg_hba.conf.  If you set pg_hba.conf
options to trust, then it won't even check the password or the
password expiration, so don't do that outside of testing/recovery
scenarios.

3)  The postgres user or other db superuser must be given access via
the web app in order to create databases.

A typical pg_hba.conf entry might be:

host   all   all   127.0.0.1/32    md5

If you want to lock this down, you can lock it down further by:
host   lsmbdb  all  127.0.0.1/32    md5
host   template1 postgres 127.0.0.1/32    md5
host  postgres postgres  127.0.0.1/32    md5

Note that the above will require new pg_hba.conf lines for each db created.


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
  File::MimeInfo

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]

To build using the Makefile.PL you will also need:

  Module::Install

All these modules can be downloaded from CPAN, the modules distribution
archive for Perl. However our experience has been that if your distribution
provides a module via its package manager (apt, rpm, etc.), you will have
fewer difficulties if you use that instead.

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 test

which will ask you which modules it should download, if you didn't install
- using your package manager - all of the required and optional modules
listed above. If you don't want support for a specific module, simply
answer 'no' in response to the download question.

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 Squeeze 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 libmath-bigint-gmp-perl \
   libfile-mimeinfo-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 libmath-bigint-gmp-perl libfile-mimeinfo-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



---- Actions for Fedora 18

 $ sudo yum install mlocate perl perl-Class-Std perl-ExtUtils-MakeMaker \
   perl-Test-Base perl-Test-Pod perl-Test-Pod-Coverage tar

Get repoforge's perl-Config-Std (0.900-1 or newer version):
 $ curl http://apt.sw.be/source/perl-Config-Std-0.900-1.rf.src.rpm --O \ 
   perl-Config-Std-0.900-1.rf.src.rpm

Rebuild the source rpm:

As root do:
 $ rpmbuild --rebuild perl-Config-Std-0.900-1.rf.src.rpm

 $ yum localinstall /path/to/new-rpm/perl-Config-Std-XXXXX.rpm

 $ yum localinstall ledgersmb-1.3.XX.noarch.rpm



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

LedgerSMB 1.3 stores data for each company in a separate "database".  A
database is a PostgreSQL concept for grouping tables, indexes, etc.

Each company database must be named.  This name is essentially the system
identifier within PostgreSQL for the company's dataset.  The name for the
company database can only contain letters, digits and underscores.
Additionally, it must start with a letter.  Company database names are
case insensitive, meaning you can't create two separate company databases
called 'Ledgersmb' and 'ledgersmb'.

One way you can create databases fairly easily is by directing your web browser
to the setup.pl script at your installed ledgersmb directory.  So if the 
base URL is http://localhost/ledgersmb/, you can access the database setup and 
upgrade script at http://localhost/ledgersmb/setup.pl.  This is very different
from the approaches taken by LedgerSMB 1.2.x and earlier and SQL-Ledger, but
rather forms a wizard to walk you through the process.

Please note that the setup.pl file assumes that LedgerSMB is already configured 
to be able to access the database and locate the relevant PostgreSQL contrib 
scripts.  In particular, you must have the  contrib_dir directive set to point
to those scripts properly in your ledgersmb.conf before you begin.

If you are upgrading from 1.2, your 1.2 tables will be moved to schema lsmb12.
Please keep this schema for some months. Updates which need this schema may
still be necessary.

An alternative method is the 'prepare-company-database.sh' script contributed by
Erik Huelsmann.  This script can be useful in creating and populating databases
from the command line and it offers a reference implementation written in BASH
for how this process is done.   The prepare-company-database.sh script is only
supported on GNU environments, but a prepare-company-database.pl is included
with nearly identical syntax which is supported everywhere LedgerSMB is.

The 'prepare-company-database.sh' script in the tools/ directory will set
up databases to be used for LedgerSMB. The script should be run as 'root'
because it wants to 'su' to the postgres user.  Alternatively, if you
know the password of the postgres user, you can run the script as any other
user.  You'll be prompted for the password.  Additionally, the script creates
a superuser to assign ownership of the created company database to. By
default this user is called 'ledgersmb'.  The reason for this choice is that
when removing the ledgersmb user, you'll be told about any unremoved parts
of the database, because the owner of an existing database can't be removed
until that database is itself removed.

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:

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

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

Upon completion, it will 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 will have loaded a minimal list of languages required
to succesfully navigate the various screens.

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.

Note: The script expects to be able to connect to the postgresql database
      server over a TCP/IP connection after initial creation of the ledgersmb
      user.  The ledgersmb user will be used to log in. To ensure that's
      possible, it's easiest to ensure there's a row in the pg_hba.conf file
      [the file which says how PostgreSQL should enforce its login policy]
      with a 'host' configuration for the 127.0.0.1/32 address and the md5
      authentication enforcement.  This line can be inserted for the duration
      of the configuration of LedgerSMB, if the file doesn't have one.  The
      line can safely be removed afterwards.


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

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

The default configuration file only works with Apache 2.2.  To run this with 
Apache 2.4, you will want to move the ledgersmb-httpd.conf.template out of the
way and replace it with the ledgersmb-httpd-2.4.conf.template before proceding.

Default installation layouts for Apache HTTPD on various operating systems 
and distributions: http://wiki.apache.org/httpd/DistrosDefaultLayout

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.

Also note on Debian, if using Apache 2.4, you may need to:
 # a2enmod cgi

Also as root.]

A default configuration file to be used with Apache2 comes with LedgerSMB in
its root project directory: ledgersmb-httpd.conf.template. You can use the 
'configure_apache.sh' script to fill out the template.

You my need to add a commmand to your Apache configuration to load the
configuration in that file by including the following line:

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

If your distribution load extra config files from example conf.d 
you do not need to add the the line to your Apache configuration.
[Debian, Fedora, Centos, RedHat]

[On Debian and derivatives, you can store the resulting
configuration file directly in the /etc/apache2/conf.d directory, for Apache 
2.2, and /etc/apache2/conf-enabled/ for Apache 2.4.  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

On some systems apachectl might be called apache2ctl.

On systems without apachectl support, you will need to run either:

 $ service apache2 restart

or

 $ /etc/init.d/apache2 restart


Manual configuration
====================

If you want to perform the installation of the company database completely
manually, you should consult the 'tools/prepare-company-database.sh' script
as the authorative documentation of the steps to perform.


Company database removal
========================

In the tools/ directory, there's a script which will remove a company
database and all the standard authorization data that's created by
the 'prepare-company-database.sh' script.  Said script is called
'delete-company-database.sh'.
