diff options
| -rw-r--r-- | INSTALL | 473 |
1 files changed, 284 insertions, 189 deletions
@@ -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 |