

Contents
--------

 * System requirements
 * Simple Server Setup: Running on Starman
 * Installing Apache 2
 * Installing PostgreSQL
 * PostgreSQL authorization settings
 * Installing Perl module dependencies
   * for Debian
   * for Fedora
   * for <your system>
 * Initializing a company database
   * Manual Database Creation (needed on Windows platforms)
 * 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, Nginx, MS IIS, etc)
 * PostgreSQL 9.0+
 * Perl 5.10+


Installation process overview
=============================

 1) Install the base software: web server (Apache),
    database server (PostgreSQL) and Perl from your distribution
    and package manager or source. Read on for details
 2) Installing Perl module dependencies from your distribution and
    package manager or CPAN.  Read on for details
 3) Give the web server access to the ledgersmb directory
 4) Edit ./ledgersmb/ledgersmb.conf to be able to access the database
    and locate the relevant PostgreSQL contrib scripts
 5) Initializing a company database
    Database setup and upgrade script at http://localhost/ledgersmb/setup.pl
 6) Login with your name (database username),
    password (database user password), Company (databasename)

Running on Starman
===================
As an alternative to Apache 2, LedgerSMB now supports the Perl-based web server
named Starman.  To install you need:

 * Starman
 * CGI::Emulate::PSGI
 * PSGI::Middleware::Static
 * Plack::Builder

Compared to Apache 2, Starman seems to perform better at the Perl portions of
the application, but slower at serving Javascript and CSS files, though these
are usually cached on the browser.  Thus it is not unusual to see the software
seem to be slower at the first and then pick up speed, becoming faster than the
equivalent CGI installations.

The above may be installed by running the Makefile.PL and selecting appropriate
options.

Then from the LedgerSMB directory starting is as simple as:

 starman --preload-app tools/starman.psgi

The server by default starts on port 5000 so you would access the installation
by pointing your web browser to:

 http://localhost:5000/login.pl

You can also daemonize Starman, run it on the default port, and much more.  See
the starman documentation for details.

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

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

 $ apt-get install apache2

On Fedora and its derivatives (RedHat, Centos ++) 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 and its derivatives 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  postgres postgres  127.0.0.1/32    md5

As of 1.4, connections to template1 are no longer required for the db setup 
process.

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


Installing Perl module dependencies
===================================

LedgerSMB depends on these additional modules (not listing core modules):

  CGI::Simple
  Carp::Always
  Config::IniFiles
  DBD::Pg
  DBI
  Data::Dumper
  DateTime
  DateTime::Format::Strptime
  Digest::MD5
  File::MimeInfo
  HTML::Entities    (part of HTML::Parser)
  IO::Scalar        (part of IO-stringy)
  JSON
  Locale::Maketext
  Locale::Maketext::Lexicon
  Log::Log4perl
  MIME::Base64
  MIME::Lite
  Math::BigFloat    (part of Math::BigInt)
  Moose
  Number::Format
  Template  (also known as The Template Toolkit or TT)
  Try::Tiny
  namespace::autoclean

and these optional ones:

  XML::Simple        [RESTful Web Services XML support]
  Image::Size        [Size detection for images for embedding in LaTeX]
  Parse::RecDescent  [Support for the *experimental* scripting engine]
  Getopt::Long       [Developer tool dependencies]
  FileHandle         [Developer tool dependencies]
  Locale::Country    [Developer tool dependencies]
  Locale::Language   [Developer tool dependencies]
  Template::Plugin::Latex [Support for Postscript and PDF output]
  Tex::Encode             [Support for Postscript and PDF output]
  XML::Twig               [Support for OpenOffice output]
  OpenOffice::OODoc       [Support for OpenOffice output]

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

  Module::Install

To run the tests, you additionally need:

  Test::More
  Test::Trap
  Test::Exception


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:

 $ cpanm --notest --quiet --installdeps .

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

---- Actions for Debian Wheezy  (7.x oldstable)

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

 $ aptitude install libdatetime-perl libdbi-perl libdbd-pg-perl \
   libcgi-simple-perl libtemplate-perl libmime-lite-perl \
   liblocale-maketext-lexicon-perl libtest-exception-perl \
   libtest-trap-perl liblog-log4perl-perl libmath-bigint-gmp-perl \
   libfile-mimeinfo-perl libtemplate-plugin-number-format-perl \
   libdatetime-format-strptime-perl libconfig-general-perl \
   libdatetime-format-strptime-perl libio-stringy-perl libmoose-perl \
   libconfig-inifiles-perl libnamespace-autoclean-perl \
   libcarp-always-perl libjson-perl


This installs the required modules available from the Wheezy repository.

To install the (optional) PDF/Postscript output module, install the
following packages by executing this command:

 $ aptitude install libtemplate-plugin-latex-perl texlive-latex-recommended

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

 $ aptitude install libxml-twig-perl


---- Actions for Debian Jessie  (8.x stable)

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

 $ aptitude install libcgi-simple-perl libcarp-always-perl \
     libconfig-inifiles-perl libdbi-perl libdbd-pg-perl \
     libdata-dumper-perl libdatetime-perl libdatetime-format-strptime-perl \
     libfile-mimeinfo-perl libhtml-parser-perl libio-stringy-perl \
     libjson-perl liblocale-maketext-perl liblocale-maketext-lexicon-perl \
     liblog-log4perl-perl libmime-lite-perl libmath-bigfloat-gmp-perl \
     libmoose-perl libnumber-format-perl libtemplate-perl \
     libtry-tiny-perl libnamespace-autoclean-perl


This installs the required modules available from the Jessie repository.

To install the (optional) PDF/Postscript output module, install the
following packages by executing this command:

 $ aptitude install libtemplate-plugin-latex-perl \
     texlive-latex-recommended libtex-encode-perl 

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

 $ aptitude install libopenoffice-oodoc-perl


---- Common Debian related remarks

Please see the following about UTF8 characters, XeTeX, and templates:

http://ledgersmb.org/faq/localization/im-using-non-ascii-unicode-characters-why-cant-i-generate-pdf-output





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

LedgerSMB 1.3 and up store 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. In case of upgrading from 1.3, the schema is called lsmb13.

An alternative method is the 'prepare-company-database.pl' script in the tools/
directory.  This script can be useful in creating and populating databases from
the command line. The script will ask for the password of the 'postgres' user
or can be run as 'root' to make it 'su' to postgres. Additionally, the script
creates a superuser to assign ownership of the created company database to. By
default this user is called 'lsmb_dbadmin'.  The reason for this choice is that
when removing the 'lsmb_dbadmin' 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. At the same time, the name has been
chosen to distinguish the database admin from the application admin, a user
with full administration power within the application.

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.pl --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 database admin called 'lsmb_dbadmin'
(password: 'LEDGERSMBINITIALPASSWORD'), a single user called
'admin' (password: 'admin') and the roles required to manage authorizations.

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.

Manual Database Creation:
-------------------------
In some environments, using the tools above is not possible.  These may
include some heavily scripted environments which require additional control
than the above tools provide, or rare environments where environemnt variables
are not recognized by libpq or are not properly transmitted from Perl to the
called program (such problems have been reported to us on Microsoft Windows
platforms).

These instructions also provide basic documentation for custom db creation
tools.

In this case:

1.  Load the sql/Pg-database.sql using a tool of your choice (psql or PgAdmin)
2.  Load the modules in the order located in sql/modules/LOADORDER
    * can be done programmatically, see the UNIX Bash script reload_modules.sh
      in that same directory.
    * can use tools of your choice (PGAdmin, psql).

When upgrading a database, you perform that second stage, and then set the
version record in the defaults table to the appropriate version (with a new
database, this is set by default).  To do this:

    * SELECT * FROM setting__set('version', '1.3.41'); -- or other version


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.

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.]

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.  From
that location, it'll be automatically included upon the next server (re)start.
On Apache 2.4 on Debian and derivatives, you can store the configuration file 
in the /etc/apache2/conf-enabled directory. You will need to add the cgi module
by going to /etc/apache2/mods-enabled/ and creating a symbolic link like this:
ln -s /etc/apache2/mods-available/cgi.load cgi.load
You also may need to add a symbolic link to enable apache to see postgres:
ln -s /user/bin/psql /bin/psql
both these commands will need to be performed with root permissions (use sudo)]

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'.
