summaryrefslogtreecommitdiff
path: root/INSTALL
blob: a2c25001c2bc9cf0d2960a5ae2a13a906c0026ba (plain)
  1. Installing LedgerSMB 1.2
  2. This document contains information on how to install LedgerSMB. We recommend
  3. that the reader start by reading the section on manual installation and then
  4. start by trying the automated means mentioned later.
  5. Also this document assumes that the reader is already familiar with the release
  6. notes. If you have not already done so, please read the release_notes file in
  7. the doc/ directory.
  8. DISTRO AND OS-SPECIFIC NOTES:
  9. ===============================================================================
  10. Debian users should read README.debian
  11. MANUAL INSTALL:
  12. ===============================================================================
  13. 1) Untar in desired location (for example, /usr/local/).
  14. 2) Decide where to put the user/session management tables. In general, we
  15. recommend as follows:
  16. a) Single dataset installations should use the user tables in the dataset.
  17. b) Multicompany installations should use user tables in a separate dataset
  18. from any accounting data.
  19. 3) Create a admin database role named 'ledgersmb':
  20. bash$ createuser --no-superuser --createdb --no-createrole -U postgres
  21. --pwprompt --encrypted ledgersmb
  22. 4) Create a central user database database, owned by admin role:
  23. bash$ createdb -U ledgersmb -O ledgersmb ledgersmb
  24. 5) Run the included SQL commands to configure the central user database:
  25. (ledgerpath) is wherever you untarred the file. If you untarred to
  26. /usr/local/ then it will be /usr/local/ledger-smb.
  27. bash$ psql -U ledgersmb -d ledgersmb -f (ledgerpath)/sql/Pg-central.sql
  28. 6) Update your admin password in the central user database
  29. (change MYPASSWORD to your preferred administrative password).
  30. bash$ psql -U ledgersmb -d ledgersmb
  31. ledgersmb=> UPDATE users_conf SET password = md5('MYPASSWORD') WHERE id = 1;
  32. 7) Quit the interactive SQL console:
  33. ledgersmb=> \q
  34. 7b) If you want to store the company information in the same database, run the
  35. following command:
  36. bash$ createlang -U postgres -d ledgersmb plpgsql;
  37. If not, then you can skip to step 8.
  38. 8) Edit the ledger-smb.conf file as appropriate.
  39. a) Copy the ledger-smb.conf.default to ledger-smb.conf
  40. b) Make sure to set the section under [globaldbh] to point to the database
  41. you imported Pg-central into.
  42. 9) Add configuration to Apache:
  43. bash$ sh configure_apache.sh
  44. 10) Check Dependencies
  45. The Build.PL script can be used to test for unmet dependencies and run other
  46. tests. It doesn't install anything yet, but it will tell you what you are
  47. missing. To check for dependencies, run "perl Build.PL" from the command line.
  48. Missing dependencies can generally be installed via a Linux distributor's
  49. package manager or by CPAN. (Build.PL itself uses Module::Build, which is
  50. available in packages like perl-Module-Build or libmodule-build-perl.)
  51. Once this is done and dependencies are satisfied, you can check to see whether
  52. the installation nominally works by running "./Build test" from the command
  53. line. The test suites currently check to make sure all the perl modules load
  54. and that a number of numeric tests are passed.
  55. Dependencies which are recommended are needed only for specific functionality
  56. and may not be required in all circumstances. These include:
  57. * Net::TCLink for credit card processing in a POS environment
  58. * Parse::RecDescent for the CLI script host
  59. 11) Restart Apache (instructions may vary with your Linux distro or operating
  60. system).
  61. 12) Create Datasets and Users:
  62. Visit http://hostname/ledger-smb/admin.pl, login with MYPASSWORD,
  63. Create datasets with user ledgersmb, superuser postgres
  64. (omit the superuser if creating inside the database you imported
  65. Pg-central into).
  66. Create users pointing to datasets.
  67. Congratulations, you have manually installed LedgerSMB 1.2.
  68. FTP INSTALLATION:
  69. ============================================================================
  70. If you control the server and have shell access, the
  71. instructions above are preferred over those given here.
  72. instead of those given here. This is simply a set of
  73. notes for those who must install on a shared server.
  74. If you do not have access to the server's configuration
  75. files install LedgerSMB in userspace by ftp'ing all the
  76. files to your server.
  77. a) untar ledger-smb in your private_html directory
  78. b) turn on script execution for the folder ledger-smb
  79. You can control this with an .htaccess file
  80. Options +ExecCGI
  81. DirectoryIndex login.pl
  82. c) protect the users directory with an .htpasswd file
  83. order allow,deny
  84. deny from all
  85. d) protect the templates directory with an .htpasswd file
  86. order allow,deny
  87. deny from all
  88. e) set up your PostgreSQL database and the tables. The basic
  89. procedure is specified above.
  90. You will most likely only have access to PostgreSQL with
  91. some other tools like pgadmin.
  92. TROUBLESHOOTING
  93. ===========================================================================
  94. Error: Access Denied in admin.pl
  95. Likely causes:
  96. 1) The password entered may not match the password set in step 6. You can
  97. repreat that step prior to the creation of user accounts as often as you
  98. wish.
  99. After the creation of user accounts, the commant to reset the admin password
  100. is:
  101. UPDATE users_conf SET password=mp5('MYPASSWORD') WHERE id =
  102. (select id FROM user WHERE username = 'admin');
  103. Of course, substitute 'MYPASSWORD' for your chosen password.
  104. 2) The central database may have been created with a different user than you
  105. are using for the connection and you may not have permission to access the
  106. required database entities. To correct this, assuming that the desired
  107. database username is ledgersmb, the following commands from psql:
  108. GRANT ALL ON users TO ledgersmb;
  109. GRANT ALL ON users_id_seq TO ledgersmb;
  110. GRANT ALL ON users_conf TO ledgersmb;
  111. GRANT ALL ON session TO ledgersmb;
  112. GRANT ALL ON session_session_id_seq TO ledgersmb;
  113. --------------------------------------------------
  114. Error: "No GlobalDBH Configured or Could not Connect"
  115. LedgerSMB 1.2 uses a dedicated connection to the central database for user
  116. authentication. When the attempt to connect to that database fails, the error
  117. message above is displayed. In this case, check the following parameters
  118. under the [globaldbh] of the ledger-smb.conf file.
  119. 1) DBUserName should match the database user you imported Pg-central as (if
  120. you followed the instructions above, that would be ledgersmb).
  121. 2) DBPassword needs to match the database password to used to connect to.
  122. You can test the above causes by running (from the command line):
  123. bash$ psql -U [DBUserName]
  124. password: [DBPassword]
  125. When you enter the password, it will not show up on the screen.
  126. The other line that you should pay attention to is the DBConnect line.
  127. Parameters in the form of name=value need to match those for your host. The
  128. following parameters need to be set correctly in that line:
  129. dbname=ledgersmb (or whatever database you imported Pg-Central.sql into).
  130. host=localhost (don't change this unless you know what you are doing!)
  131. port=5432 (don't change this unless you know what you are doing!)
  132. The full line should then be something like:
  133. DBConnect: dbi:Pg:dbname=ledgersmb;host=localhost;port=5432