path: root/INSTALL

Installing LedgerSMB 1.2
========================

This document contains information on how to install LedgerSMB. We
recommend that the reader start by reading the section on manual
installation and then start by trying the automated means mentioned
later.

Also this document assumes that the reader is already familiar with the
release notes. If you have not already done so, please read the
release_notes file in the doc/ directory.


DISTRO AND OS-SPECIFIC NOTES
============================

Debian users should read README.debian

OpenBSD users, please consult the README.OpenBSD

For Unix systems, '$' signifies the bash prompt, '=>' the psql prompt.


MANUAL INSTALL
==============

1) Untar in desired location (for example, /usr/local/ledgersmb,
refered to as LEDGERPATH for the remainder of this INSTALL file).
LedgerSMB files should be owned by the apache user, apache:apache on
many systems.

2) Install the procedural language on your database server

Note:  installing here on the template1 database will permit it
to propogate to every future database created, both those used
by LedgerSMB (which require it) and to other databases you
may create for other applications (which may not need it).
If that is not what you want, consider first creating a
template2-plpgsql database, adapting this command to install
the language on that application specific template, leaving
your template1 clean.  Then you can use your template2-plpgsql
database as a starting point for any datasets you create
for LedgerSMB.

We start by ensuring that the plpgsql language has not already
been installed.  If that first query does not result in a
record where the 'lanname' field is 'plpgsql', then you need
to install the procedural language.

# su - postgres
$ psql

=> \c template1
=> SELECT * FROM pg_language;
=> \q

$ createlang plpgsql template1
$ psql

=> ALTER ROLE postgres WITH PASSWORD 'YOURPASSWORD';

Some distributions will create a postgres database user without
ever prompting the user for an administrative password for
the user.  If you start as root, su - postgres and invoke
psql from the postgres shell prompt, you would never need the
postgres database user's password.  But you will need to know
the password later when you start creating accounting datasets.
So might as well create one now.

3) Create a postgresql admin database role, by convention named
'ledgersmb':

$ createuser --no-superuser --createdb --no-createrole \
-U postgres --pwprompt --encrypted ledgersmb

(\ is a bash line continuation character, this is a single command)

The prompted password (referred to as MYROLEPASSWORD) will later be
used in the DBConnect: string in the configuration file
'ledgersmb.conf'

If you prefer to work in postgresql's psql console, the equivalent SQL
statement to create the ledgersmb role is:

=> CREATE ROLE ledgersmb LOGIN PASSWORD 'MYROLEPASSWORD' NOINHERIT
CREATEDB;

Further commands and database interaction should be conducted using
the new LedgerSMB admin role 'ledgersmb'.


4) Create a central user database, owned by the LedgerSMB admin role,
'ledgersmb':

$ createdb -U ledgersmb -O ledgersmb ledgersmb

The equivalent SQL statement is:

=> CREATE DATABASE ledgersmb WITH ENCODING='SQL_ASCII'
OWNER=ledgersmb;


5) On the database that will store your user and session information,
run the included Pg-central.sql SQL commands to configure the user
and session tables and functions:

$ psql -U ledgersmb -d ledgersmb -f LEDGERPATH/sql/Pg-central.sql

(LEDGERPATH is in the location you expanded the release
tarball file. If you untarred in '/usr/local' then LEDGERPATH will
be '/usr/local/ledgersmb').

NOTE: LedgerSMB's preferred configuration is to store the user and
session management tables in a separate database from the company
databases (aka 'datasets', created in admin.pl). If you are already
working with or prefer to have your user and session tables in one
company dataset, see further information in the manual.  You must have
PLPGSQL installed in the dataset as well.  However that is beyond the
scope of these instructions.


6) The SQL commands in step 5) created an LedgerSMB-managed admin user,
e.g. a row in the users and users_conf table. You must now update the
'admin' user's password in users_conf from the default password.

$ psql -U ledgersmb -d ledgersmb

ledgersmb=> UPDATE users_conf SET password = md5('MYPASSWORD')
WHERE id = 1;

(Change MYPASSWORD to your preferred administrative password, which
is separate, but can be the same spelling as MYROLEPASSWORD).

ledgersmb=> \q


7) Edit the LEDGERPATH/ledgersmb.conf file:

a) Copy 'ledgersmb.conf.default' to 'ledgersmb.conf'

b) Make sure to set the section under [globaldb] to point to the
central user and session database, using password MYROLEPASSWORD:

[globaldb]
DBname       = ledgersmb
DBhost       = localhost
DBport       = 5432
DBUserName   = ledgersmb
DBPassword   = MYROLEPASSWORD


8) Add configuration to Apache:

$ sh configure_apache.sh

You will be prompted for the user which runs your apache server.
This user is usually known as: apache, www-data, nobody or
something similiar.

You will also be prompted for the directory where you want to install
the modified apache configuration file for LedgerSMB.  On an apache2
installation (at least on a Debian server) that would be:

    /etc/apache2/sites-available

$ cd /etc/apache2/sites-available
$ a2en ledgersmb-http.conf

That will create a symlink in your ../sites-enabled/ directory
and prompt you to restart your server.

9) Check Dependencies:

The Build.PL script can be used to test for unmet dependencies and
run other tests. It doesn't install anything yet, but it will tell
you what you are missing. To check for dependencies, run:

$ perl Build.PL

Missing dependencies can generally be installed via a Linux
distribution's package manager, or by CPAN. (Build.PL itself uses
Module::Build, which is available in packages like perl-Module-Build
or libmodule-build-perl.)

Alternately you can use the Makefile.PL as follows:

$ perl Makefile.PL

That should serve essentially the same function as running
Build.PL would.

Once this is done and dependencies are satisfied, you can check to
see whether the installation nominally works by running:

$ ./Build test

or, if you are using the makefile, try this instead:

$ make 
$ make test

The test suites currently check to make sure all the perl modules
load and that a number of numeric tests are passed.

Dependencies which are recommended are needed only for specific
functionality and may not be required in all circumstances. These
include:

* Net::TCLink for credit card processing in a POS environment

* Parse::RecDescent for the CLI script host

Finally, if you are using the makefile, instead of the Build
method, to install the application, as the root user, use this:

# make install

10) Restart Apache (instructions vary with your Linux distro or operating
system).

On a Debian system try: 

# /etc/init.d/apache2 reload

Create Datasets and Users
=========================

1) Create Datasets:

Browse to:

http://hostname/ledgersmb/admin.pl

login with 'MYPASSWORD'

Create dataset(s) with:

User: ledgersmb
Password: MYPASSWORD

Superuser: postgres
Password: (postgres password)

Create one dataset (a postgresql datatabase) for each separate
company which will use LedgerSMB for accounting, e.g.:

ledgeracme
ledgerbigco
(...)


2) Create User(s) pointing to specific datasets:

Browse to:

http://hostname/ledgersmb/admin.pl

login with 'MYPASSWORD'

Create user(s) pointing to a specific dataset (ledgeracme, etc.)
with database login information:

User: ledgersmb
Password: MYPASSWORD

Congratulations, you have installed and configured LedgerSMB 1.2


FTP INSTALLATION
================

If you control the server and have shell access, the instructions above
are preferred over those given here. instead of those given here. This
is simply a set of notes for those who must install on a shared server.

If you do not have access to the server's configuration files install
LedgerSMB in userspace by ftp'ing all the files to your server.

1) Untar ledgersmb in your private_html directory.

2) turn on script execution for the folder ledgersmb. You can control
this with an .htaccess file:

Options +ExecCGI
DirectoryIndex login.pl

3) Protect the users directory with an .htpasswd file:

order allow,deny
deny from all

4) Protect the templates directory with an .htpasswd file:

order allow,deny
deny from all

5) Set up your PostgreSQL database and the tables. The procedure is
specified above.

You will most likely only have access to PostgreSQL with some other
tools like pgadmin.


TROUBLESHOOTING
===============

Error: Access Denied in admin.pl
---------------------------------

Likely causes:

1) The password entered may not match the password set in Manual Install
step 5). You can repreat that step as often as you need to get login
to admin.pl working, but in case your 'admin' user is not id=1, try
using the expanded version of the SQL:

ledgersmb==> UPDATE users_conf SET password=md5('MYPASSWORD')
WHERE id = (SELECT id FROM user
WHERE username = 'admin');

(Substitute 'MYPASSWORD' for your chosen password).

2) The central database may have been created with a different postgres
user (role) than you are using for the connection. In this case, you
may not have permission to access the required database entities.

To correct this, assuming that the admin database role is ledgersmb,
issue the following commands from psql:

ledgersmb==> GRANT ALL ON users TO ledgersmb;
ledgersmb==> GRANT ALL ON users_id_seq TO ledgersmb;
ledgersmb==> GRANT ALL ON users_conf TO ledgersmb;
ledgersmb==> GRANT ALL ON session TO ledgersmb;
ledgersmb==> GRANT ALL ON session_session_id_seq TO ledgersmb;


Error: "No GlobalDBH Configured or Could not Connect"
-----------------------------------------------------

LedgerSMB 1.2 uses a dedicated connection to the central database for
user authentication. When the attempt to connect to that database fails,
the error message above is displayed. In this case, check the following
parameters under the [globaldbh] of the ledgersmb.conf file.

1) DBUserName should match the database user you imported Pg-central
as (if you followed the instructions above, that would be ledgersmb).

2) DBPassword needs to match the database password to used to connect
to.

You can test the above causes by running (from the command line):

$ psql -U [DBUserName]
password: [DBPassword]

When you enter the password, it will not show up on the screen.

The other line that you should pay attention to is the DBConnect
line. Parameters in the form of name=value need to match those for
your host. The following parameters need to be set correctly in that
line:

dbname=ledgersmb  (the database you imported Pg-Central.sql into).
host=localhost    (don't change unless you know what you are doing!)
port=5432         (don't change unless you know what you are doing!)

The full line should then be something like:

DBConnect: dbi:Pg:dbname=ledgersmb;host=localhost;port=5432

And that section of ledgersmb.conf looks like:

[globaldb]
DBname     = ledgersmb
DBhost     = localhost
DBport     = 5432
DBUserName = ledgersmb
DBPassword = MYROLEPASSWORD


OTHER ISSUES:
===================================
Before submitting a bug, please consult the COMPATABILITY list.  This documents
which versions of software have known interoperability problems with LedgerSMB.