summaryrefslogtreecommitdiff
path: root/INSTALL
blob: a5ed25156554a747eeb708c922847a279b843bed (plain)
  1. LedgerSMB 1.3 (svn trunk) INSTALL
  2. =================================
  3. This document aims to provide a detailed step by step process to configure a
  4. working instance of LedgerSMB 1.3 from subversion repository or pre-alpha
  5. release tarball.
  6. Subsitute your own values for file paths and definitions shown in ALL_CAPS.
  7. Install LedgerSMB 1.3 Source
  8. ------------------------------------
  9. LedgerSMB 1.3 is still in pre-beta, with no tarball release files. Check out
  10. LedgerSMB 1.3 from svn trunk:
  11. $ svn co https://ledger-smb.svn.sourceforge.net/svnroot/ledger-smb/trunk /path/to/ledgersmb13
  12. Change working directory to WORKING_DIR:
  13. ----------------------------------------
  14. WORKING_DIR is the location you have manually installed the LedgerSMB 1.3 source
  15. or checkout. LedgerSMB 1.3 in pre-alpha form is not currently packaged for any
  16. distribution.
  17. $ cd /path/to/ledgersmb13/
  18. /path/to/ledgersmb13 $
  19. All commands from this point forward are executed from WORKING_DIR unless
  20. otherwise noted.
  21. Automating Installation
  22. -----------------------
  23. You can extract the commands in this document with: $ grep -e '^\$' INSTALL
  24. This provides a decent approximation of what would be required for a scripted
  25. install as of this writing.
  26. Apache Configuration
  27. ====================
  28. LedgerSMB uses Apache-2.x, with mod_rewrite.
  29. Create up an Apache conf file for the WORKING_DIR location
  30. ----------------------------------------------------------
  31. Configure ledgersmb-httpd.conf for apache, subsituting WORKING_DIR with the
  32. absolute path of your LedgerSMB installation (e.g. /path/to/ledgersmb13):
  33. The following sed command applies the repetitive substitution automatically.
  34. $ cat ledgersmb-httpd.conf | sed "s|WORKING_DIR|$(pwd)|" > ledgersmb-httpd-13.conf
  35. You can also apply the substitution manually in your preferred text editor.
  36. Install the Apache conf file
  37. ----------------------------
  38. Move the apache conf file ledgersmb-httpd-13.conf to a location where it will be
  39. picked up on apache restart:
  40. $ sudo mv ledgersmb-httpd-13.conf /etc/apache2/app/ledgersmb13.conf
  41. Restart apache:
  42. $ sudo /etc/init.d/apache2 restart
  43. * Stopping apache2 ... [ ok ]
  44. * Starting apache2 ... [ ok ]
  45. Verify that RewriteRule is working
  46. ----------------------------------
  47. LedgerSMB 1.3 depends on mod_rewrite's ReWriteRule. Make sure that your Apache
  48. has module or built-in support for mod_rewrite. You can test this if you are
  49. unsure. Use an .htaccess file to check that mod_rewrite is working and that our
  50. directory alias has been loaded by apache:
  51. $ echo -e 'RewriteEngine on\nRewriteRule ^(.*)$ http://www.google.com [R]' > /path/to/ledgersmb13/.htaccess
  52. $ wget -qO /dev/stdout http://localhost/ledgersmb | grep -c '<title>Google</title>'
  53. 1
  54. If you saw the grep output "1" above, RewriteRule is working. Remove your
  55. temporary .htaccess file:
  56. $ rm .htaccess
  57. Apache must be able to read and write WORKING_DIR
  58. -------------------------------------------------
  59. Make sure the WORKING_DIR directory is read-writable by user:group
  60. apache:apache, or as appropriate for your distribution's Apache conventions.
  61. Check And Satisfy Perl Dependencies
  62. ===================================
  63. LedgerSMB depends on Perl-5.8, and several CPAN packages, which may or may not
  64. be available as system packages for your linux distribution:
  65. $ perl -v | grep v5.
  66. This is perl, v5.8.8 built for i686-linux
  67. Run Makefile.PL to check for LedgerSMB's Perl dependencies. The output should be
  68. similar to the following:
  69. $ perl Makefile.PL
  70. include /path/to/ledgersmb13/inc/Module/Install.pm
  71. include inc/Module/Install/Metadata.pm
  72. include inc/Module/Install/Base.pm
  73. include inc/Module/Install/AutoInstall.pm
  74. include inc/Module/Install/Include.pm
  75. include inc/Module/AutoInstall.pm
  76. *** Module::AutoInstall version 1.03
  77. *** Checking for Perl dependencies...
  78. [Core Features]
  79. - Test::More ...loaded. (0.8)
  80. - Test::Trap ...loaded. (0.0.23)
  81. - Test::Exception ...loaded. (0.27)
  82. - Data::Dumper ...loaded. (2.121)
  83. - Locale::Maketext ...loaded. (1.13)
  84. - Locale::Maketext::Lexicon ...loaded. (0.64 >= 0.56)
  85. - DBI ...loaded. (1.601 >= 1.00)
  86. - MIME::Base64 ...loaded. (3.07)
  87. - Digest::MD5 ...loaded. (2.36)
  88. - HTML::Entities ...loaded. (1.35)
  89. - DBD::Pg ...loaded. (1.49)
  90. - Math::BigFloat ...loaded. (1.51)
  91. - IO::File ...loaded. (1.13)
  92. - Encode ...loaded. (2.12)
  93. - Locale::Country ...loaded. (2.07)
  94. - Locale::Language ...loaded. (2.07)
  95. - Time::Local ...loaded. (1.18)
  96. - Cwd ...loaded. (3.2701)
  97. - Config::Std ...loaded. (0.0.4)
  98. - MIME::Lite ...loaded. (3.01)
  99. - Template ...loaded. (2.19 >= 2.14)
  100. - Error ...loaded. (0.17012)
  101. - CGI::Simple ...loaded. (1.0)
  102. [POS module credit card processing support]
  103. - Net::TCLink ...loaded. (3.4)
  104. [Experimental scripting engine]
  105. - Parse::RecDescent ...loaded. (1.94)
  106. [Developer tool dependencies]
  107. - Getopt::Long ...loaded. (2.35)
  108. - FileHandle ...loaded. (2.01)
  109. [PDF and Postscript output]
  110. - Template::Latex ...loaded. (2.17)
  111. [OpenOffice.org output]
  112. - XML::Twig ...loaded. (3.32)
  113. - OpenOffice::OODoc ...loaded. (2.035)
  114. [Excel output]
  115. - Excel::Template::Plus ...loaded. (0.03)
  116. *** Module::AutoInstall configuration finished.
  117. include inc/Module/Install/Makefile.pm
  118. include inc/Module/Install/WriteAll.pm
  119. Writing META.yml
  120. include inc/Module/Install/Win32.pm
  121. include inc/Module/Install/Can.pm
  122. include inc/Module/Install/Fetch.pm
  123. include inc/Module/Install/Build.pm
  124. Writing Makefile for LedgerSMB
  125. Use your distribution's CPAN or packaging tools to satisfy the dependencies
  126. shown above.
  127. =========================
  128. PostgreSQL Configuration
  129. =========================
  130. LedgerSMB 1.3 is tightly integrated with PostgreSQL. In the current pre-alpha
  131. state, it is necessary to run several PostgreSQL commands and SQL statements
  132. exactly as shown below. Automated installers will ease this process in future
  133. releases.
  134. TODO: Securing PostgreSQL with LedgerSMB
  135. ========================================
  136. An experienced PostgreSQL expert should author a section which describes how to
  137. properly modify the typical default pg_hba.conf etc., such that LedgerSMB 1.3
  138. works, but without opening up the database to unneccessary network access.
  139. Installing PostgreSQL Contrib Function Libraries (Not Optional)
  140. ===============================================================
  141. LedgerSMB 1.3 depends on several function libraries distributed with PostgreSQL,
  142. but typically not installed by default in most distributions.
  143. Identify the system package containing the files tsearch2.sql, tablefunc.sql,
  144. and pg_trgm.sql. Install that package, and locate the files on the filesystem.
  145. You only need to install these function libraries once per postgresql cluster.
  146. For the remainder of this INSTALL procedure, you will need to become user
  147. postgres, or have the ability to log in to psql as your current user, or issue
  148. the commands with: sudo -u postgres [cmd].
  149. Install Tsearch2 Full Text indexing engine for PostgreSQL
  150. ---------------------------------------------------------
  151. $ psql -U postgres -d template1 -f /usr/share/postgresql-8.3/contrib/tsearch2.sql
  152. Install tablefunc.sql for PostgreSQL
  153. ------------------------------------
  154. $ psql -U postgres -d template1 -f /usr/share/postgresql-8.3/contrib/tablefunc.sql
  155. Install pg_trgm.sql for PostgreSQL
  156. ----------------------------------
  157. $ psql -U postgres -d template1 -f /usr/share/postgresql-8.3/contrib/pg_trgm.sql
  158. TODO: Test install of tsearch2, tablefunc, pg_trgm
  159. --------------------------------------------------
  160. Create test functions for user to verify proper contrib library
  161. loading. Instruct the user how to run them.
  162. Configure a LedgerSMB PostgreSQL role
  163. =====================================
  164. Create the ledgersmb PostgreSQL role (optional):
  165. $ createuser --no-superuser --createdb --no-createrole -U postgres --pwprompt --encrypted ledgersmb
  166. Make a note of the password you enter, we'll refer to it as LSMB_PASSWORD.
  167. Configure a LedgerSMB Company Database
  168. ======================================
  169. Create a LedgerSMB company database. The user and configuration information
  170. are stored alongside the accounting data as of this writing:
  171. $ createdb -U postgres -O ledgersmb mycompany
  172. Install the plpgsql procedural language to the company database:
  173. $ createlang plpgsql mycompany
  174. Apply the SQL statements in /path/to/ledgersmb13/sql/Pg-database.sql to
  175. the company database:
  176. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/Pg-database.sql
  177. Apply the in-development SQL statements in the files WORKING_DIR/sql/modules/ to
  178. the company database, in exactly the following order:
  179. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Drafts.sql
  180. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/chart.sql
  181. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Account.sql
  182. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Session.sql
  183. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Business_type.sql
  184. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Location.sql
  185. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Company.sql
  186. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Customer.sql
  187. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Date.sql
  188. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Defaults.sql
  189. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Settings.sql
  190. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Employee.sql
  191. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Entity.sql
  192. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Payment.sql
  193. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Person.sql
  194. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Report.sql
  195. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Voucher.sql
  196. At the time of this writing, the following files are in an earlier state of development and not ready to be
  197. loaded:
  198. admin.sql
  199. security.sql
  200. Reconciliaton.sql
  201. Generate A Custom Roles SQL Statement File
  202. ------------------------------------------
  203. Preprocess the sql/modules/Roles.sql file with sed, generating a custom SQL file in WORKING_DIR:
  204. $ sed -e 's/<?lsmb dbname ?>/mycompany/g' /path/to/ledgersmb13/sql/modules/Roles.sql > /path/to/ledgersmb13/mycompany_roles.sql
  205. Apply the SQL statements in the sed-generated file mycompany_roles.sql to the
  206. company database:
  207. $ psql -U postgres -d mycompany -f /path/to/ledgersmb13/mycompany_roles.sql
  208. Create A PostgreSQL Role
  209. ------------------------
  210. Create a postgresql role which you will use to log into the company
  211. database:
  212. $ createuser --no-superuser --createdb --no-createrole -U postgres --pwprompt --encrypted myuser
  213. Note the password entered at the prompt as MYUSER_PASSWORD. You will use this to login to the
  214. LedgerSMB 1.3 instance.
  215. Create A Company User
  216. =====================
  217. The following section creates a company user 'myuser' and configures that user
  218. for use with 'mycompany'.
  219. Insert myuser Entity
  220. --------------------
  221. Using the psql console, insert myuser to the entity table.
  222. $ psql -U postgres -d mycompany -t -c "INSERT INTO entity (name, entity_class, created) VALUES ('myuser', 3, NOW()) RETURNING name, entity_class, created;"
  223. myuser | 3 | 2008-08-08
  224. INSERT 0 1
  225. Insert myuser Persion
  226. ---------------------
  227. Insert the myuser entity into the person table:
  228. $ psql -U postgres -d mycompany -t -c "INSERT INTO person (entity_id, first_name, last_name, created) VALUES (2, 'Firstname', 'Lastname', NOW()) RETURNING entity_id, first_name, last_name, created;"
  229. 2 | Firstname | Lastname | 2008-08-08
  230. INSERT 0 1
  231. Insert myuser Employee
  232. ----------------------
  233. Insert the myuser person into the entity_employee table:
  234. $ psql -U postgres -d mycompany -t -c "INSERT INTO entity_employee (person_id, entity_id, startdate, role) VALUES (1, 2, NOW(), 'myuser') RETURNING person_id, entity_id, startdate, role;"
  235. 1 | 2 | 2008-08-08 | myuser
  236. INSERT 0 1
  237. Insert myuser User
  238. ------------------
  239. Insert the myuser username and its entity id into the users table:
  240. $ psql -U postgres -d mycompany -t -c "INSERT INTO users (username, entity_id) VALUES ('myuser', 2) RETURNING username, entity_id;"
  241. myuser | 2
  242. INSERT 0 1
  243. Insert myuser Preferences
  244. -------------------------
  245. Insert the myuser's person_id into user_preferences:
  246. $ psql -U postgres -d mycompany -t -c "INSERT INTO user_preference (id) VALUES (1) RETURNING id;"
  247. 1
  248. Temporary Workaround: Grant All Roles To myuser
  249. -----------------------------------------------
  250. As of this writing, the following workaround is recommended to apply all
  251. LedgerSMB 1.3 roles (i.e. rolname LIKE 'lsmb%') to a company user. Create the
  252. following function:
  253. $ psql -U postgres -d mycompany -t -c "CREATE OR REPLACE FUNCTION grant_all_roles(in_login varchar) RETURNS INT as \$\$ DECLARE role_info RECORD; BEGIN FOR role_info IN select * from pg_roles WHERE rolname LIKE 'lsmb%' LOOP EXECUTE 'GRANT ' || role_info.rolname || ' TO ' || in_login; END LOOP; RETURN 1; END; \$\$ language plpgsql;"
  254. CREATE FUNCTION
  255. And execute the function for myuser:
  256. $ psql -U postgres -d mycompany -t -c "SELECT grant_all_roles('myuser');"
  257. Login to LedgerSMB 1.3 Instance
  258. ===============================
  259. It should now be possible to log into your LedgerSMB 1.3 instance at:
  260. http://localhost/ledgersmb
  261. With cookies enabled for localhost.
  262. Name: myuser
  263. Password: MYUSER_PASSWORD
  264. Company: mycompany
  265. Workarounds
  266. ===========
  267. In its pre-alpha state, when accessing certain parts of the LedgerSMB 1.3 system
  268. you may encounter permission errors. For example:
  269. DBD::Pg::st execute failed: ERROR: permission denied for relation warehouse
  270. Error!
  271. SELECT id, description
  272. FROM warehouse
  273. ORDER BY 2
  274. ERROR: permission denied for relation warehouse
  275. It is possible to grant the permissions directly, until a bug is filed, and the
  276. code and this INSTALL document is updated to fix the bug. As of this writing,
  277. the following SQL statements help avoid these types of errors:
  278. $ psql -U postgres -d mycompany -t -c "GRANT SELECT ON warehouse TO public;"
  279. GRANT
  280. $ psql -U postgres -d mycompany -t -c "GRANT SELECT ON translation TO public;"
  281. GRANT
  282. $ psql -U postgres -d mycompany -t -c "GRANT SELECT ON pricegroup TO public;"
  283. GRANT
  284. $ psql -U postgres -d mycompany -t -c "GRANT SELECT ON taxmodule TO public;"
  285. GRANT
  286. $ psql -U postgres -d mycompany -t -c "GRANT SELECT ON sic TO public;"
  287. GRANT
  288. How-To Section
  289. ==============
  290. Q: How do I remove the 90+ roles for mycompany created by the INSTALL process?
  291. A: First, since most objects in the mycompany database depend on these roles,
  292. you must drop the mycompany database first, obviously with loss of data.
  293. $ dropdb -U postgres mycompany
  294. After that, you must issue the droprole command for each rolname in the query
  295. embedded in the following command:
  296. $ for role in `psql -U postgres -t -c "SELECT rolname FROM pg_roles WHERE rolname LIKE 'lsmb_mycompany%';"`; do dropuser -U postgres $role; done
  297. Q: The Admin UI isn't functional yet, how to I set my preferred CSS stylesheet?
  298. A: You might find another CSS stylesheet to your liking, but there is currently
  299. no UI to set it. Run the following command. If you know your users.id, you can
  300. modify the query:
  301. $ psql -U postgres -d mycompany -c "UPDATE user_preference SET stylesheet='ledgersmb-smallgray.css';"
  302. UPDATE 1