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


MANUAL INSTALL:
===============================================================================

1)  Untar in desired location.

2)  Decide where to put the user/session management tables.  In general, we
recommend as follows:
  a)  Single dataset installations should use the user tables in the dataset.
  b)  Multicompany installations should use user tables in a separate dataset
      from any accounting data.
To be integrated into the documentation, these minimalist steps have made
installation/migration of ledger-smb much easier for me:


3) Create a admin database role named 'ledgersmb':

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


4) Create a central user database database, owned by admin role:

    bash$ createdb -U ledgersmb -O ledgersmb ledgersmb


5) Run the included SQL commands to configure the central user database:

    bash$ psql -U ledgersmb -d ledgersmb -f (ledgerpath)/sql/Pg-central.sql


6) Update your admin password in the central user database
    (change MYPASSWORD to your preferred administrative password).

    bash$ psql -U ledgersmb -d ledgersmb

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

7) Quit the interactive SQL console:

    ledgersmb=> \q

Configure apache, visit admin.pl, login with MYPASSWORD, create datasets
with user ledgersmb, superuser postgres, create users pointing to datasets,
etc.


8)  Edit the ledger-smb.conf file as appropriate.
  a)  Make sure to set the section under GlobalDBH to point to hte databae you
      imported Pg-central into.

9)  Add configuration to Apache:
    bash$ sh configure_apache.sh

10) 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" from the command line.
Missing dependencies can generally be installed via a Linux distributor'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.)

Once this is done and dependencies are satisfied, you can check to see whether
the installation nominally works by running "./Build test" from the command
line.  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

11) Restart Apache (instructions may vary with your Linux distro).

12) Create Datasets and Users:
   Visit http://hostname/ledger-smb/admin.pl, login with MYPASSWORD, 
   Create datasets with user ledgersmb, superuser postgres
   Create users pointing to datasets.

Congratulations, you have manually installed 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.

a) untar ledger-smb in your private_html directory
b) turn on script execution for the folder ledger-smb
You can control this with an .htaccess file

  Options +ExecCGI
  DirectoryIndex login.pl

c) protect the users directory with an .htpasswd file

order allow,deny
deny from all

d) protect the templates directory with an .htpasswd file

order allow,deny
deny from all

e) set up your PostgreSQL database and the tables.  The basic
procedure is specified in the INSTALL file.

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 step 4.  You can 
    repreat that step prior to the creation of user accounts as often as you 
    wish.

    After the creation of user accounts, the commant to reset the admin password
    is:
    UPDATE users_conf SET password=mp5('password') WHERE id = 
        (select id FROM user WHERE username = 'admin');

    Of course, substitute 'password' for your chosen password.

2)  The central database may have been created with a different user than you 
    are using for the connection and you may not have permission to access the
    required database entities.  To correct this, assuming that the desired 
    database username is ledgersmb, the following commands from psql:
      GRANT ALL ON users TO ledgersmb;
      GRANT ALL ON users_id_seq TO ledgersmb;
      GRANT ALL ON users_conf TO ledgersmb;
      GRANT ALL ON session TO ledgersmb;
      GRANT ALL ON session_session_id_seq TO ledgersmb;