[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
SF.net SVN: ledger-smb: [946] branches/1.2/INSTALL
- Subject: SF.net SVN: ledger-smb: [946] branches/1.2/INSTALL
- From: ..hidden..
- Date: Sat, 17 Mar 2007 22:30:47 -0700
Revision: 946
http://svn.sourceforge.net/ledger-smb/?rev=946&view=rev
Author: einhverfr
Date: 2007-03-17 22:30:46 -0700 (Sat, 17 Mar 2007)
Log Message:
-----------
New INSTALL, courtesy of Jeff K.
Modified Paths:
--------------
branches/1.2/INSTALL
Modified: branches/1.2/INSTALL
===================================================================
--- branches/1.2/INSTALL 2007-03-18 03:21:07 UTC (rev 945)
+++ branches/1.2/INSTALL 2007-03-18 05:30:46 UTC (rev 946)
@@ -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
+
+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:
-MANUAL INSTALL:
-===============================================================================
+=> 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').
-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:
+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.
- a) Single dataset installations should use the user tables in the dataset.
+
+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;
- b) Multicompany installations should use user tables in a separate dataset
- from any accounting data.
+(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:
-3) Create a admin database role named 'ledgersmb':
+[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:
- bash$ createuser --no-superuser --createdb --no-createrole -U postgres
- --pwprompt --encrypted ledgersmb
+$ 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:
-4) Create a central user database database, owned by admin role:
+$ ./Build test
- bash$ createdb -U ledgersmb -O ledgersmb ledgersmb
+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
-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.
+login with 'MYPASSWORD'
- bash$ psql -U ledgersmb -d ledgersmb -f (ledgerpath)/sql/Pg-central.sql
+Create dataset(s) with:
+User: ledgersmb
+Password: MYPASSWORD
-6) Update your admin password in the central user database
- (change MYPASSWORD to your preferred administrative password).
+Superuser: postgres
+Password: (postgres password)
- bash$ psql -U ledgersmb -d ledgersmb
+Create one dataset (a postgresql datatabase) for each separate
+company which will use LedgerSMB for accounting, e.g.:
- ledgersmb=> UPDATE users_conf SET password = md5('MYPASSWORD') WHERE id = 1;
+ledgeracme
+ledgerbigco
+(...)
+
+
+1) Create User(s) pointing to specific datasets:
+
+Browse to:
-7) Quit the interactive SQL console:
+http://hostname/ledger-smb/admin.pl
- ledgersmb=> \q
+login with 'MYPASSWORD'
-7b) If you want to store the company information in the same database, run the
- following command:
+Create user(s) pointing to a specific dataset (ledgeracme, etc.)
+with database login information:
- 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.
-
+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 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.
-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;
-
---------------------------------------------------
-
+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:
+DBConnect: dbi:Pg:dbname=ledgersmb;host=localhost;port=5432
+
+And that section of ledger-smb.conf looks like:
-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!)
-
-The full line should then be something like:
+[globaldb]
DBConnect: dbi:Pg:dbname=ledgersmb;host=localhost;port=5432
+DBUserName: ledgersmb
+DBPassword: MYROLEPASSWORD
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.