diff options
| -rw-r--r-- | INSTALL | 496 |
1 files changed, 443 insertions, 53 deletions
@@ -1,71 +1,461 @@ -Installing LedgerSMB 1.3 +LedgerSMB 1.3 (svn trunk) INSTALL +================================= +This document aims to provide a detailed step by step process to configure a +working instance of LedgerSMB 1.3 from subversion repository or pre-alpha +release tarball. -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. +Subsitute your own values for file paths and definitions shown in ALL_CAPS. -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. +Install LedgerSMB 1.3 Source +------------------------------------ -MANUAL INSTALL: -=============================================================================== +LedgerSMB 1.3 is still in pre-beta, with no tarball release files. Check out +LedgerSMB 1.3 from svn trunk: -1) Untar in desired location. +$ svn co https://ledger-smb.svn.sourceforge.net/svnroot/ledger-smb/trunk /path/to/ledgersmb13 -2) Check Dependencies -The Makefile.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 Makefile.PL" from the command -line. Missing dependencies can generally be installed via a Linux distributor's -package manager or by CPAN. (Makefile.PL itself uses Module::Install, which is -available in packages like perl-Module-Install or libmodule-install-perl.) +Change working directory to WORKING_DIR: +---------------------------------------- -Once this is done and dependencies are satisfied, you can check to see whether -the installation nominally works by running "make 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. +WORKING_DIR is the location you have manually installed the LedgerSMB 1.3 source +or checkout. LedgerSMB 1.3 in pre-alpha form is not currently packaged for any +distribution. -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 +$ cd /path/to/ledgersmb13/ +/path/to/ledgersmb13 $ -3) 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) Multi-company installations should use user tables in a separate dataset - from any accounting data. +All commands from this point forward are executed from WORKING_DIR unless +otherwise noted. -4) Install Tsearch2 Full Text indexing engine for PostgreSQL (not optional) - a) If you installed PostgreSQL from source, Tsearch2 is in contrib. - b) If you installed from package, you will need the package - postgresql-contrib or equivalent - c) Use psql to apply the tsearch2.sql to template1. The file is normally - installed to - /usr/share/postgresql/contrib/tsearch2.sql or - //usr/share/postgresql/<version>/contrib/tsearch2.sql -5) Install tablefunc.sql for PostgreSQL (not optional) - See notes in 4 above for location of script and apply to template1. +Automating Installation +----------------------- -6) Install pg_trgm.sql into database or template1. - See notes in 4 above for location of script. Apply to template1. +You can extract the commands in this document with: $ grep -e '^\$' INSTALL -7) Create central database - a) create the ledgersmb role (optional) - b) create the ledgersmb database (if using a multi-company central db) - c) cd to the sql/ directory of the new ledger directory. - d) load the Pg-database.sql script into ledgersmb or your database. +This provides a decent approximation of what would be required for a scripted +install as of this writing. -8) Set the admin password: - From psql, determine what admin password you wish to use. Then type: - "update users_conf set password = md5('my_password');" - Naturally you would use your password instead of my_password. -9) Edit the ledgersmb.conf file as appropriate. +Apache Configuration +==================== -Congratulations, you have manually installed LedgerSMB 1.3. +LedgerSMB uses Apache-2.x, with mod_rewrite. + + +Create up an Apache conf file for the WORKING_DIR location +---------------------------------------------------------- + +Configure ledgersmb-httpd.conf for apache, subsituting WORKING_DIR with the +absolute path of your LedgerSMB installation (e.g. /path/to/ledgersmb13): + +The following sed command applies the repetitive substitution automatically. + +$ cat ledgersmb-httpd.conf | sed "s|WORKING_DIR|$(pwd)|" > ledgersmb-httpd-13.conf + +You can also apply the substitution manually in your preferred text editor. + +Install the Apache conf file +---------------------------- + +Move the apache conf file ledgersmb-httpd-13.conf to a location where it will be +picked up on apache restart: + +$ sudo mv ledgersmb-httpd-13.conf /etc/apache2/app/ledgersmb13.conf + +Restart apache: + +$ sudo /etc/init.d/apache2 restart + * Stopping apache2 ... [ ok ] + * Starting apache2 ... [ ok ] + + +Verify that RewriteRule is working +---------------------------------- + +LedgerSMB 1.3 depends on mod_rewrite's ReWriteRule. Make sure that your Apache +has module or built-in support for mod_rewrite. You can test this if you are +unsure. Use an .htaccess file to check that mod_rewrite is working and that our +directory alias has been loaded by apache: + +$ echo -e 'RewriteEngine on\nRewriteRule ^(.*)$ http://www.google.com [R]' > /path/to/ledgersmb13/.htaccess + +$ wget -qO /dev/stdout http://localhost/ledgersmb | grep -c '<title>Google</title>' +1 + +If you saw the grep output "1" above, RewriteRule is working. Remove your +temporary .htaccess file: + +$ rm .htaccess + + +Apache must be able to read and write WORKING_DIR +------------------------------------------------- + +Make sure the WORKING_DIR directory is read-writable by user:group +apache:apache, or as appropriate for your distribution's Apache conventions. + + +Check And Satisfy Perl Dependencies +=================================== + +LedgerSMB depends on Perl-5.8, and several CPAN packages, which may or may not +be available as system packages for your linux distribution: + +$ perl -v | grep v5. +This is perl, v5.8.8 built for i686-linux + +Run Makefile.PL to check for LedgerSMB's Perl dependencies. The output should be +similar to the following: + +$ perl Makefile.PL +include /path/to/ledgersmb13/inc/Module/Install.pm +include inc/Module/Install/Metadata.pm +include inc/Module/Install/Base.pm +include inc/Module/Install/AutoInstall.pm +include inc/Module/Install/Include.pm +include inc/Module/AutoInstall.pm +*** Module::AutoInstall version 1.03 +*** Checking for Perl dependencies... +[Core Features] +- Test::More ...loaded. (0.8) +- Test::Trap ...loaded. (0.0.23) +- Test::Exception ...loaded. (0.27) +- Data::Dumper ...loaded. (2.121) +- Locale::Maketext ...loaded. (1.13) +- Locale::Maketext::Lexicon ...loaded. (0.64 >= 0.56) +- DBI ...loaded. (1.601 >= 1.00) +- MIME::Base64 ...loaded. (3.07) +- Digest::MD5 ...loaded. (2.36) +- HTML::Entities ...loaded. (1.35) +- DBD::Pg ...loaded. (1.49) +- Math::BigFloat ...loaded. (1.51) +- IO::File ...loaded. (1.13) +- Encode ...loaded. (2.12) +- Locale::Country ...loaded. (2.07) +- Locale::Language ...loaded. (2.07) +- Time::Local ...loaded. (1.18) +- Cwd ...loaded. (3.2701) +- Config::Std ...loaded. (0.0.4) +- MIME::Lite ...loaded. (3.01) +- Template ...loaded. (2.19 >= 2.14) +- Error ...loaded. (0.17012) +- CGI::Simple ...loaded. (1.0) +[POS module credit card processing support] +- Net::TCLink ...loaded. (3.4) +[Experimental scripting engine] +- Parse::RecDescent ...loaded. (1.94) +[Developer tool dependencies] +- Getopt::Long ...loaded. (2.35) +- FileHandle ...loaded. (2.01) +[PDF and Postscript output] +- Template::Latex ...loaded. (2.17) +[OpenOffice.org output] +- XML::Twig ...loaded. (3.32) +- OpenOffice::OODoc ...loaded. (2.035) +[Excel output] +- Excel::Template::Plus ...loaded. (0.03) +*** Module::AutoInstall configuration finished. +include inc/Module/Install/Makefile.pm +include inc/Module/Install/WriteAll.pm +Writing META.yml +include inc/Module/Install/Win32.pm +include inc/Module/Install/Can.pm +include inc/Module/Install/Fetch.pm +include inc/Module/Install/Build.pm +Writing Makefile for LedgerSMB + +Use your distribution's CPAN or packaging tools to satisfy the dependencies +shown above. + + +========================= +PostgreSQL Configuration +========================= + +LedgerSMB 1.3 is tightly integrated with PostgreSQL. In the current pre-alpha +state, it is necessary to run several PostgreSQL commands and SQL statements +exactly as shown below. Automated installers will ease this process in future +releases. + + +TODO: Securing PostgreSQL with LedgerSMB +======================================== + +An experienced PostgreSQL expert should author a section which describes how to +properly modify the typical default pg_hba.conf etc., such that LedgerSMB 1.3 +works, but without opening up the database to unneccessary network access. + + +Installing PostgreSQL Contrib Function Libraries (Not Optional) +=============================================================== + +LedgerSMB 1.3 depends on several function libraries distributed with PostgreSQL, +but typically not installed by default in most distributions. + +Identify the system package containing the files tsearch2.sql, tablefunc.sql, +and pg_trgm.sql. Install that package, and locate the files on the filesystem. + +You only need to install these function libraries once per postgresql cluster. + +For the remainder of this INSTALL procedure, you will need to become user +postgres, or have the ability to log in to psql as your current user, or issue +the commands with: sudo -u postgres [cmd]. + + +Install Tsearch2 Full Text indexing engine for PostgreSQL +--------------------------------------------------------- + +$ psql -U postgres -d template1 -f /usr/share/postgresql-8.3/contrib/tsearch2.sql + + +Install tablefunc.sql for PostgreSQL +------------------------------------ + +$ psql -U postgres -d template1 -f /usr/share/postgresql-8.3/contrib/tablefunc.sql + + +Install pg_trgm.sql for PostgreSQL +---------------------------------- + +$ psql -U postgres -d template1 -f /usr/share/postgresql-8.3/contrib/pg_trgm.sql + + +TODO: Test install of tsearch2, tablefunc, pg_trgm +-------------------------------------------------- + +Create test functions for user to verify proper contrib library +loading. Instruct the user how to run them. + + +Configure a LedgerSMB PostgreSQL role +===================================== + +Create the ledgersmb PostgreSQL role (optional): + +$ createuser --no-superuser --createdb --no-createrole -U postgres --pwprompt --encrypted ledgersmb + + +Make a note of the password you enter, we'll refer to it as LSMB_PASSWORD. + + +Configure a LedgerSMB Company Database +====================================== + +Create a LedgerSMB company database. The user and configuration information +are stored alongside the accounting data as of this writing: + +$ createdb -U postgres -O ledgersmb mycompany + + +Install the plpgsql procedural language to the company database: + +$ createlang plpgsql mycompany + + +Apply the SQL statements in /path/to/ledgersmb13/sql/Pg-database.sql to +the company database: + +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/Pg-database.sql + + +Apply the in-development SQL statements in the files WORKING_DIR/sql/modules/ to +the company database, in exactly the following order: + +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Drafts.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/chart.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Account.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Session.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Business_type.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Location.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Company.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Customer.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Date.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Defaults.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Settings.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Employee.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Entity.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Payment.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Person.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Report.sql +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/sql/modules/Voucher.sql + +At the time of this writing, the following files are in an earlier state of development and not ready to be +loaded: + +admin.sql +security.sql +Reconciliaton.sql + + +Generate A Custom Roles SQL Statement File +------------------------------------------ + +Preprocess the sql/modules/Roles.sql file with sed, generating a custom SQL file in WORKING_DIR: + +$ sed -e 's/<?lsmb dbname ?>/mycompany/g' /path/to/ledgersmb13/sql/modules/Roles.sql > /path/to/ledgersmb13/mycompany_roles.sql + + +Apply the SQL statements in the sed-generated file mycompany_roles.sql to the +company database: + +$ psql -U postgres -d mycompany -f /path/to/ledgersmb13/mycompany_roles.sql + + +Create A PostgreSQL Role +------------------------ + +Create a postgresql role which you will use to log into the company +database: + +$ createuser --no-superuser --createdb --no-createrole -U postgres --pwprompt --encrypted myuser + +Note the password entered at the prompt as MYUSER_PASSWORD. You will use this to login to the +LedgerSMB 1.3 instance. + + +Create A Company User +===================== + +The following section creates a company user 'myuser' and configures that user +for use with 'mycompany'. + + +Insert myuser Entity +-------------------- + +Using the psql console, insert myuser to the entity table. + +$ psql -U postgres -d mycompany -t -c "INSERT INTO entity (name, entity_class, created) VALUES ('myuser', 3, NOW()) RETURNING name, entity_class, created;" + myuser | 3 | 2008-08-08 + +INSERT 0 1 + + +Insert myuser Persion +--------------------- + +Insert the myuser entity into the person table: + +$ 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;" + 2 | Firstname | Lastname | 2008-08-08 + +INSERT 0 1 + + +Insert myuser Employee +---------------------- + +Insert the myuser person into the entity_employee table: + +$ 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;" + 1 | 2 | 2008-08-08 | myuser + +INSERT 0 1 + +Insert myuser User +------------------ + +Insert the myuser username and its entity id into the users table: + +$ psql -U postgres -d mycompany -t -c "INSERT INTO users (username, entity_id) VALUES ('myuser', 2) RETURNING username, entity_id;" + myuser | 2 + +INSERT 0 1 + + +Insert myuser Preferences +------------------------- + +Insert the myuser's person_id into user_preferences: + +$ psql -U postgres -d mycompany -t -c "INSERT INTO user_preference (id) VALUES (1) RETURNING id;" + 1 + + +Temporary Workaround: Grant All Roles To myuser +----------------------------------------------- + +As of this writing, the following workaround is recommended to apply all +LedgerSMB 1.3 roles (i.e. rolname LIKE 'lsmb%') to a company user. Create the +following function: + +$ 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;" +CREATE FUNCTION + + +And execute the function for myuser: + +$ psql -U postgres -d mycompany -t -c "SELECT grant_all_roles('myuser');" + + +Login to LedgerSMB 1.3 Instance +=============================== + +It should now be possible to log into your LedgerSMB 1.3 instance at: + +http://localhost/ledgersmb + +With cookies enabled for localhost. + +Name: myuser +Password: MYUSER_PASSWORD +Company: mycompany + + +Workarounds +=========== + +In its pre-alpha state, when accessing certain parts of the LedgerSMB 1.3 system +you may encounter permission errors. For example: + +DBD::Pg::st execute failed: ERROR: permission denied for relation warehouse +Error! +SELECT id, description +FROM warehouse +ORDER BY 2 +ERROR: permission denied for relation warehouse + +It is possible to grant the permissions directly, until a bug is filed, and the +code and this INSTALL document is updated to fix the bug. As of this writing, +the following SQL statements help avoid these types of errors: + +$ psql -U postgres -d mycompany -t -c "GRANT SELECT ON warehouse TO public;" +GRANT +$ psql -U postgres -d mycompany -t -c "GRANT SELECT ON translation TO public;" +GRANT +$ psql -U postgres -d mycompany -t -c "GRANT SELECT ON pricegroup TO public;" +GRANT +$ psql -U postgres -d mycompany -t -c "GRANT SELECT ON taxmodule TO public;" +GRANT +$ psql -U postgres -d mycompany -t -c "GRANT SELECT ON sic TO public;" +GRANT + + +How-To Section +============== + +Q: How do I remove the 90+ roles for mycompany created by the INSTALL process? + +A: First, since most objects in the mycompany database depend on these roles, +you must drop the mycompany database first, obviously with loss of data. + +$ dropdb -U postgres mycompany + +After that, you must issue the droprole command for each rolname in the query +embedded in the following command: + +$ for role in `psql -U postgres -t -c "SELECT rolname FROM pg_roles WHERE rolname LIKE 'lsmb_mycompany%';"`; do dropuser -U postgres $role; done + + +Q: The Admin UI isn't functional yet, how to I set my preferred CSS stylesheet? + +A: You might find another CSS stylesheet to your liking, but there is currently +no UI to set it. Run the following command. If you know your users.id, you can +modify the query: + +$ psql -U postgres -d mycompany -c "UPDATE user_preference SET stylesheet='ledgersmb-smallgray.css';" +UPDATE 1 |