summaryrefslogtreecommitdiff
path: root/INSTALL
blob: f90ec25b40b5bb732a6787a9aea5e696ac060831 (plain)
  1. Installing LedgerSMB 1.2
  2. ========================
  3. This document contains information on how to install LedgerSMB. We
  4. recommend that the reader start by reading the section on manual
  5. installation and then start by trying the automated means mentioned
  6. later.
  7. Also this document assumes that the reader is already familiar with the
  8. release notes. If you have not already done so, please read the
  9. release_notes file in the doc/ directory.
  10. DISTRO AND OS-SPECIFIC NOTES
  11. ============================
  12. Debian users should read README.debian
  13. OpenBSD users, please consult the README.OpenBSD
  14. For Unix systems, '$' signifies the bash prompt, '=>' the psql prompt.
  15. MANUAL INSTALL
  16. ==============
  17. 1) Untar in desired location (for example, /usr/local/ledger-smb,
  18. refered to as LEDGERPATH for the remainder of this INSTALL file).
  19. LedgerSMB files should be owned by the apache user, apache:apache on
  20. many systems.
  21. 2) Create a postgresql admin database role, by convention named
  22. 'ledgersmb':
  23. $ createuser --no-superuser --createdb --no-createrole \
  24. -U postgres --pwprompt --encrypted ledgersmb
  25. (\ is a bash line continuation character, this is a single command)
  26. The prompted password (referred to as MYROLEPASSWORD) will later be
  27. used in the DBConnect: string in the configuration file
  28. 'ledger-smb.conf'
  29. The equivalent SQL statement to create the ledgersmb role is:
  30. => CREATE ROLE ledgersmb LOGIN PASSWORD 'MYROLEPASSWORD' NOINHERIT
  31. CREATEDB;
  32. Further commands and database interaction should be conducted using
  33. the new LedgerSMB admin role 'ledgersmb'.
  34. 3) Create a central user database, owned by the LedgerSMB admin role,
  35. 'ledgersmb':
  36. $ createdb -U ledgersmb -O ledgersmb ledgersmb
  37. The equivalent SQL statement is:
  38. => CREATE DATABASE ledgersmb WITH ENCODING='SQL_ASCII'
  39. OWNER=ledgersmb;
  40. 4) On the database that will store your user and session information,
  41. run the included Pg-central.sql SQL commands to configure the user
  42. and session tables and functions:
  43. $ psql -U ledgersmb -d ledgersmb -f LEDGERPATH/sql/Pg-central.sql
  44. (LEDGERPATH is in the location you expanded the release
  45. tarball file. If you untarred in '/usr/local' then LEDGERPATH will
  46. be '/usr/local/ledger-smb').
  47. NOTE: LedgerSMB's preferred configuration is to store the user and
  48. session management tables in a separate database from the company
  49. databases (aka 'datasets', created in admin.pl). If you are already
  50. working with or prefer to have your user and session tables in one
  51. company dataset, see further information in the manual. You must have
  52. PLPGSQL installed in the dataset as well. However that is beyond the
  53. scope of these instructions.
  54. 5) The SQL commands in step 4) created an LedgerSMB-managed admin user,
  55. e.g. a row in the users and users_conf table. You must now update the
  56. 'admin' user's password in users_conf from the default password.
  57. $ psql -U ledgersmb -d ledgersmb
  58. ledgersmb=> UPDATE users_conf SET password = md5('MYPASSWORD')
  59. WHERE id = 1;
  60. (Change MYPASSWORD to your preferred administrative password, which
  61. is separate, but can be the same spelling as MYROLEPASSWORD).
  62. ledgersmb=> \q
  63. 6) Edit the LEDGERPATH/ledger-smb.conf file:
  64. a) Copy 'ledger-smb.conf.default' to 'ledger-smb.conf'
  65. b) Make sure to set the section under [globaldbh] to point to the
  66. central user and session database, using password MYROLEPASSWORD:
  67. [globaldb]
  68. <<<<<<< .mine
  69. DBname = ledgersmb
  70. DBhost = localhost
  71. DBport = 5432
  72. DBUserName = ledgersmb
  73. DBPassword = <set me to correct password>
  74. =======
  75. DBname = ledgersmb
  76. DBhost = localhost
  77. DBport = 5432
  78. DBUserName = ledgersmb
  79. DBPassword = MYROLEPASSWORD
  80. >>>>>>> .r1061
  81. 7) Add configuration to Apache:
  82. $ sh configure_apache.sh
  83. 8) Check Dependencies:
  84. The Build.PL script can be used to test for unmet dependencies and
  85. run other tests. It doesn't install anything yet, but it will tell
  86. you what you are missing. To check for dependencies, run:
  87. $ perl Build.PL
  88. Missing dependencies can generally be installed via a Linux
  89. distribution's package manager, or by CPAN. (Build.PL itself uses
  90. Module::Build, which is available in packages like perl-Module-Build
  91. or libmodule-build-perl.)
  92. Once this is done and dependencies are satisfied, you can check to
  93. see whether the installation nominally works by running:
  94. $ ./Build test
  95. The test suites currently check to make sure all the perl modules
  96. load and that a number of numeric tests are passed.
  97. Dependencies which are recommended are needed only for specific
  98. functionality and may not be required in all circumstances. These
  99. include:
  100. * Net::TCLink for credit card processing in a POS environment
  101. * Parse::RecDescent for the CLI script host
  102. 9) Restart Apache (instructions vary with your Linux distro or operating
  103. system).
  104. Create Datasets and Users
  105. =========================
  106. 1) Create Datasets:
  107. Browse to:
  108. http://hostname/ledger-smb/admin.pl
  109. login with 'MYPASSWORD'
  110. Create dataset(s) with:
  111. User: ledgersmb
  112. Password: MYPASSWORD
  113. Superuser: postgres
  114. Password: (postgres password)
  115. Create one dataset (a postgresql datatabase) for each separate
  116. company which will use LedgerSMB for accounting, e.g.:
  117. ledgeracme
  118. ledgerbigco
  119. (...)
  120. 1) Create User(s) pointing to specific datasets:
  121. Browse to:
  122. http://hostname/ledger-smb/admin.pl
  123. login with 'MYPASSWORD'
  124. Create user(s) pointing to a specific dataset (ledgeracme, etc.)
  125. with database login information:
  126. User: ledgersmb
  127. Password: MYPASSWORD
  128. Congratulations, you have manually installed LedgerSMB 1.2.
  129. FTP INSTALLATION
  130. ================
  131. If you control the server and have shell access, the instructions above
  132. are preferred over those given here. instead of those given here. This
  133. is simply a set of notes for those who must install on a shared server.
  134. If you do not have access to the server's configuration files install
  135. LedgerSMB in userspace by ftp'ing all the files to your server.
  136. 1) Untar ledger-smb in your private_html directory.
  137. 2) turn on script execution for the folder ledger-smb. You can control
  138. this with an .htaccess file:
  139. Options +ExecCGI
  140. DirectoryIndex login.pl
  141. 3) Protect the users directory with an .htpasswd file:
  142. order allow,deny
  143. deny from all
  144. 4) Protect the templates directory with an .htpasswd file:
  145. order allow,deny
  146. deny from all
  147. 5) Set up your PostgreSQL database and the tables. The procedure is
  148. specified above.
  149. You will most likely only have access to PostgreSQL with some other
  150. tools like pgadmin.
  151. TROUBLESHOOTING
  152. ===============
  153. Error: Access Denied in admin.pl
  154. ---------------------------------
  155. Likely causes:
  156. 1) The password entered may not match the password set in Manual Install
  157. step 5). You can repreat that step as often as you need to get login
  158. to admin.pl working, but in case your 'admin' user is not id=1, try
  159. using the expanded version of the SQL:
  160. ledgersmb==> UPDATE users_conf SET password=mp5('MYPASSWORD')
  161. WHERE id = (SELECT id FROM user
  162. WHERE username = 'admin');
  163. (Substitute 'MYPASSWORD' for your chosen password).
  164. 2) The central database may have been created with a different postgres
  165. user (role) than you are using for the connection. In this case, you
  166. may not have permission to access the required database entities.
  167. To correct this, assuming that the admin database role is ledgersmb,
  168. issue the following commands from psql:
  169. ledgersmb==> GRANT ALL ON users TO ledgersmb;
  170. ledgersmb==> GRANT ALL ON users_id_seq TO ledgersmb;
  171. ledgersmb==> GRANT ALL ON users_conf TO ledgersmb;
  172. ledgersmb==> GRANT ALL ON session TO ledgersmb;
  173. ledgersmb==> GRANT ALL ON session_session_id_seq TO ledgersmb;
  174. Error: "No GlobalDBH Configured or Could not Connect"
  175. -----------------------------------------------------
  176. LedgerSMB 1.2 uses a dedicated connection to the central database for
  177. user authentication. When the attempt to connect to that database fails,
  178. the error message above is displayed. In this case, check the following
  179. parameters under the [globaldbh] of the ledger-smb.conf file.
  180. 1) DBUserName should match the database user you imported Pg-central
  181. as (if you followed the instructions above, that would be ledgersmb).
  182. 2) DBPassword needs to match the database password to used to connect
  183. to.
  184. You can test the above causes by running (from the command line):
  185. $ psql -U [DBUserName]
  186. password: [DBPassword]
  187. When you enter the password, it will not show up on the screen.
  188. The other line that you should pay attention to is the DBConnect
  189. line. Parameters in the form of name=value need to match those for
  190. your host. The following parameters need to be set correctly in that
  191. line:
  192. dbname=ledgersmb (the database you imported Pg-Central.sql into).
  193. host=localhost (don't change unless you know what you are doing!)
  194. port=5432 (don't change unless you know what you are doing!)
  195. The full line should then be something like:
  196. DBConnect: dbi:Pg:dbname=ledgersmb;host=localhost;port=5432
  197. And that section of ledger-smb.conf looks like:
  198. [globaldb]
  199. DBname = ledgersmb
  200. DBhost = localhost
  201. DBport = 5432
  202. DBUserName = ledgersmb
  203. DBPassword = MYROLEPASSWORD
  204. OTHER ISSUES:
  205. ===================================
  206. Before submitting a bug, please consult the COMPATABILITY list. This documents
  207. which versions of software have known interoperability problems with LedgerSMB.