New INSTALL, courtesy of Jeff K.

git-svn-id: https://ledger-smb.svn.sourceforge.net/svnroot/ledger-smb/branches/1.2@946 4979c152-3d1c-0410-bac9-87ea11338e46

1 files changed, 284 insertions, 189 deletions

diff --git a/INSTALL b/INSTALL
index a2c25001..26baad61 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,204 +1,299 @@
-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:
-===============================================================================
+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 (for example, /usr/local/).
-
-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.
-
-
-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:
-   (ledgerpath) is wherever you untarred the file.  If you untarred to 
-   /usr/local/ then it will be /usr/local/ledger-smb.
-
-    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
-
-7b) If you want to store the company information in the same database, run the 
-    following command:
-
-    bash$ createlang -U postgres -d ledgersmb plpgsql;
-
-    If not, then you can skip to step 8.
-
-8)  Edit the ledger-smb.conf file as appropriate.
-
-  a)  Copy the ledger-smb.conf.default to ledger-smb.conf
-  b)  Make sure to set the section under [globaldbh] to point to the database 
-      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 or operating
-    system).
-
-12) Create Datasets and Users:
-   Visit http://hostname/ledger-smb/admin.pl, login with MYPASSWORD, 
-   Create datasets with user ledgersmb, superuser postgres
-      (omit the superuser if creating inside the database you imported 
-      Pg-central into).
-   Create users pointing to datasets.
-
+ 
+For Unix systems, '$' signifies the bash prompt, '=>' the psql prompt.
+ 
+ 
+MANUAL INSTALL
+==============
+ 
+1) Untar in desired location (for example, /usr/local/ledger-smb,
+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) 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
+'ledger-smb.conf'
+ 
+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'.
+ 
+3) 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;
+ 
+4) 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/ledger-smb').
+
+
+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.
+
+ 
+5) The SQL commands in step 4) 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
+ 
+ 
+6) Edit the LEDGERPATH/ledger-smb.conf file:
+ 
+a) Copy 'ledger-smb.conf.default' to 'ledger-smb.conf'
+
+b) Make sure to set the section under [globaldbh] to point to the
+central user and session database, using password MYROLEPASSWORD:
+
+[globaldb]
+DBConnect: dbi:Pg:dbname=ledgersmb;host=localhost;port=5432
+DBUserName: ledgersmb
+DBPassword: MYROLEPASSWORD
+ 
+ 
+7) Add configuration to Apache:
+ 
+$ sh configure_apache.sh
+ 
+ 
+8) 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.)
+ 
+Once this is done and dependencies are satisfied, you can check to
+see whether the installation nominally works by running:
+
+$ ./Build 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
+ 
+ 
+9) Restart Apache (instructions vary with your Linux distro or operating
+system).
+ 
+ 
+Create Datasets and Users
+=========================
+ 
+1) Create Datasets:
+ 
+Browse to:
+
+http://hostname/ledger-smb/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
+(...)
+ 
+ 
+1) Create User(s) pointing to specific datasets:
+ 
+Browse to:
+
+http://hostname/ledger-smb/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 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
-
+ 
+ 
+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 ledger-smb in your private_html directory.
+ 
+2) turn on script execution for the folder ledger-smb. 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
-
-d) protect the templates directory with an .htpasswd file
-
+ 
+4) 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 above.
-
-You will most likely only have access to PostgreSQL with
-some other tools like pgadmin.
-
-
+ 
+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
-
+===============
+ 
+Error: Access Denied in admin.pl
+---------------------------------
+ 
 Likely causes:
-
-1)  The password entered may not match the password set in step 6.  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('MYPASSWORD') WHERE id = 
-        (select id FROM user WHERE username = 'admin');
-
-    Of course, substitute 'MYPASSWORD' 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;
-
---------------------------------------------------
-
+ 
+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=mp5('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 ledger-smb.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.
-
+-----------------------------------------------------
+ 
+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 ledger-smb.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):
-bash$ psql -U [DBUserName]
+ 
+$ 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:
 
-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 (or whatever database you imported Pg-Central.sql into).
-host=localhost (don't change this unless you know what you are doing!)
-port=5432      (don't change this unless you know what you are doing!)
+DBConnect: dbi:Pg:dbname=ledgersmb;host=localhost;port=5432
+ 
+And that section of ledger-smb.conf looks like:
 
-The full line should then be something like:
+[globaldb]
 DBConnect: dbi:Pg:dbname=ledgersmb;host=localhost;port=5432
+DBUserName: ledgersmb
+DBPassword: MYROLEPASSWORD